IBM Cloud Docs
経路の管理

経路の管理

IBM Cloud Metrics Routing UI、IBM Cloud Metrics Routing CLI、IBM Cloud Metrics Routing REST API、IBM Cloud Metrics Routing Terraformプロバイダを使って、アカウントのルートを管理できます。 ルートは、リージョン内でどのメトリクスをルーティングし、どこにルーティングするかを示すルールを定義する。

IBM Cloud Metrics Routing 経路について詳しくは、 経路 を参照してください。

経路について

IBM Cloud Metrics Routingを構成すると、サービスがサポートされている異なる地域で生成されたプラットフォーム・メトリクスをターゲット宛先にルーティングできます。

  • IBM Cloud Metrics Routingが利用可能なリージョンで生成されたプラットフォーム・メトリクスのみをルーティングできます。 詳細については、リージョンを参照してください。

  • 規制要件とコンプライアンス要件がある場合は、ルート・ルールがそれらに準拠していることを確認してください。

IAM アクセス権限

経路を管理するには、正しい IAM 権限が必要です。 詳しくは、 IAM アクセス権限の管理 を参照してください。

UI を使用した経路の作成

UIを使用してルートを作成するには、以下を実行してください。

  1. IBM Cloudアカウントにログインする.

  2. 「メニュー」 アイコン 「メニュー」アイコン > **「可観測性」**をクリックします。

  3. **「モニタリング」**をクリックします。

  4. ルーティングをクリックします。

  5. Routes タブをクリックします。

  6. 作成をクリックし、ルート作成ページを開きます。

  7. ルートに意味のある名前を入力します。

  8. 次へ をクリックします。

  9. ルーティングルールで、ルール1アクションを変更します:

    • 関連するターゲットにメトリクスをルーティングするルールに Send を選択します。

    • このルールに一致するメトリクスをドロップするルールに Drop を選択します。

  10. inclusion filters を追加して、ルールで指定されたターゲットにルーティングされるメトリクスを決定します。

希望するフィルタと条件を選択し、包含フィルタでマッチさせる値を指定する。

複数の包含フィルタを追加するには、フィルタを追加をクリックしてください。

  1. ルールと関連付ける ターゲット をリストから選択して追加する。 ターゲットが定義されていない場合は、ターゲットを追加をクリックして新しいターゲットを作成します。

  2. ルールを追加をクリックして、ルートに追加のルールを追加します。

ルートルールの順番はルーティングの動作に影響する。 ルールは順番に処理され、あるルールにマッチすると、それ以降のルールは処理されない。

ルーティングルールの順序は、各ルール定義の右側にある上下の矢印をクリックすることで変更できる。

ルールまたはフィルタを削除する必要がある場合は、ルールまたはフィルタに関連付けられている削除アイコンをクリックします。

1ルートにつき最大10個のルールを設定できる。

  1. ルートを定義したら、Next をクリックします。

  2. ルートの定義を見直して、ルールの順序が意図した通りであることを確認してください。

  3. 「作成」 をクリックします。

UIを使ってルートを更新する

UIを使用してルートを更新するには、次の手順を実行します。

  1. IBM Cloudアカウントにログインする.

  2. 「メニュー」 アイコン 「メニュー」アイコン > **「可観測性」**をクリックします。

  3. **「モニタリング」**をクリックします。

  4. ルーティングをクリックします。

  5. Routes タブをクリックします。

  6. 更新するルートを決定し、アクションアイコン をクリックします。

  7. 名前を変更をクリックしてルート名を変更します。

  8. Edit をクリックすると、ルートルールが更新されます。

  9. ルーティングルールで、ルールのアクションを変更します:

    • 関連するターゲットにメトリクスをルーティングするルールに Send を選択します。

    • このルールに一致するメトリクスをドロップするルールに Drop を選択します。

  10. inclusion filters を追加または変更して、ルールで指定されたターゲットにルーティングされるメトリクスを決定します。

希望するフィルタと条件を選択し、包含フィルタでマッチさせる値を指定する。

複数の包含フィルタを追加するには、フィルタを追加をクリックしてください。

  1. リストからターゲットを選択して、ルールに関連付ける ターゲット を修正する。 ターゲットが定義されていない場合は、ターゲットを追加をクリックして新しいターゲットを作成します。

  2. ルールを追加をクリックして、ルートに追加のルールを追加します。

ルートルールの順番はルーティングの動作に影響する。 ルールは順番に処理され、あるルールにマッチすると、それ以降のルールは処理されない。

ルーティングルールの順序は、各ルール定義の右側にある上下の矢印をクリックすることで変更できる。

ルールまたはフィルタを削除する必要がある場合は、ルールまたはフィルタに関連付けられている削除アイコンをクリックします。

1ルートにつき最大10個のルールを設定できる。

  1. 更新をクリックして、ルートを変更します。

UIを使用してルートを表示する

UI を使ってルートを表示するには、次のようにします。

  1. IBM Cloudアカウントにログインする.

  2. 「メニュー」 アイコン 「メニュー」アイコン > **「可観測性」**をクリックします。

  3. **「モニタリング」**をクリックします。

  4. ルーティングをクリックします。

  5. Routes タブをクリックします。

    設定されたルートが一覧表示される。 経路は独立して処理されるので、経路の順番はルーティングの動作に影響しない。

    各ルートにはルート名とルールが表示されます。

    routesページにはルーティングガイダンスも表示され、ルーティングの設定に関する追加情報が表示されます。

UI を使用した経路の削除

UI を使用してルートを削除するには、次の手順を実行します。

  1. IBM Cloudアカウントにログインする.

  2. 「メニュー」 アイコン 「メニュー」アイコン > **「可観測性」**をクリックします。

  3. **「モニタリング」**をクリックします。

  4. ルーティングをクリックします。

  5. Routes タブをクリックします。

  6. 削除するルートを決定し、アクションアイコン をクリックします。

  7. 削除をクリックすると、ルート全体が削除されます。 ルートが削除される前に、ルート名を入力する必要があります。

CLI の前提条件

CLI を使用してルートを管理する前に、次の手順を完了してください:

  1. IBM Cloud CLI をインストールします

  2. IBM Cloud Metrics Routing CLI をインストールします

  3. IBM Cloud にログインします。 次のコマンドを実行します。 ibmcloud login

CLI を使用した経路の作成

ルートを作成するにはこのコマンドを使う。

経路名はアカウント内で固有です。

ibmcloud metrics-router route create --name ROUTE_NAME ( --rules RULES |  --file RULES_DEFINITION_JSON_FILE ) [--output FORMAT] [--force]

コマンド・オプション

--name ROUTE_NAME

経路に付ける名前。

リソース名に個人識別情報 (PII) を含めないでください。

--rules RULES

メトリックのルーティング方法を定義する JSON 形式のルール配列定義 (単一引用符で囲む)。 詳しくは、 ルーティング・ルールの定義 を参照してください。

--file RULES_DEFINITION_JSON_FILE

メトリックのルーティング方法を定義するルーティング・ルールを含む JSON ファイル。 詳しくは、 ルーティング・ルールの定義 を参照してください。

--output FORMAT

現在サポートされている形式は JSON です。 指定すると、出力が JSON 形式で返されます。 JSON を指定しない場合は、出力が表形式で返されます。

help | --help | -h

コマンドで使用できるオプションがリストされます。

**ibmcloud metrics-router route create**コマンドの使用例を以下に示します。

この例では、ルート作成に成功した例を示している。

ibmcloud mr route create --name target1 --rules '[{"action": "send", "targets":[{"id":"551957a7-c1e3-4160-84d8-4268709f6743"}]}]'
OK
Route
Name:         target1
ID:           06a29ca2-40f5-4371-ae3c-76a896577bd3
CRN:          crn:v1:bluemix:public:metrics-router:global:a/xxxx::route:06a29ca2-40f5-4371-ae3c-76a896577bd3
Rule 0:       [[551957a7-c1e3-4160-84d8-4268709f6743(mon-std)], []]
Created At:   2023-05-30T21:14:21.460Z
Updated At:   2023-05-30T21:14:21.460Z

CLI を使用した経路の更新

ルートを更新するにはこのコマンドを使う。 経路が最初に作成された時の値とは異なる値をコマンドで指定すると、その値がコマンドの指定値に更新されます。

ibmcloud metrics-router route update --route ROUTE [--name ROUTE_NAME] ( --rules RULES |  --file RULES_DEFINITION_JSON_FILE ) [--output FORMAT] [--force]

コマンド・オプション

--route ROUTE

IDまたは現在のルート名。

--name route_NAME

経路に付ける名前。

リソース名に個人識別情報 (PII) を含めないでください。

--rules RULES

メトリックのルーティング方法を定義する JSON 形式のルール配列定義 (単一引用符で囲む)。 詳しくは、 ルーティング・ルールの定義 を参照してください。

--file RULES_DEFINITION_JSON_FILE

メトリックのルーティング方法を定義するルーティング・ルールを含む JSON ファイル。 詳しくは、 ルーティング・ルールの定義 を参照してください。

--output FORMAT

現在サポートされている形式は JSON です。 指定すると、出力が JSON 形式で返されます。 JSON を指定しない場合は、出力が表形式で返されます。

help | --help | -h

コマンドで使用できるオプションがリストされます。

**ibmcloud metrics-router route update --route my-route --name my-new-route-name**コマンドの使用例を以下に示します。

ibmcloud mr route update --route target1 --name target2
OK
Route
Name:         target2
ID:           06a29ca2-40f5-4371-ae3c-76a896577bd3
CRN:          crn:v1:bluemix:public:metrics-router:global:a/xxxx::route:06a29ca2-40f5-4371-ae3c-76a896577bd3
Rule 0:       [[551957a7-c1e3-4160-84d8-4268709f6743(mon-std)], []]
Created At:   2023-05-30T21:14:21.460Z
Updated At:   2023-05-30T21:19:40.953Z

CLI を使用した経路の削除

ルートを削除するには、このコマンドを使用します。

ibmcloud metrics-router ROUTE rm --route route [--force]

コマンド・オプション

--route ROUTE
経路の ID または名前。
--force | -f
ユーザーに追加のプロンプトを出さずに経路を削除します。
help | --help | -h
コマンドで使用できるオプションがリストされます。

**ibmcloud metrics-router route rm --route xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx**コマンドの使用例を以下に示します。

Are you sure you want to remove the route with route ID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx? [y/N]>y
OK
Route with name xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx was successfully removed.

CLIを使用してルートに関する情報を取得する

このコマンドを使用して、IBM Cloud Metrics Routing リージョンの経路に関する情報を取得します。

ibmcloud metrics-router ROUTE get --route route [--output FORMAT]

コマンド・オプション

--route ROUTE
経路の ID または名前。
--output FORMAT
現在サポートされている形式は JSON です。 指定すると、出力が JSON 形式で返されます。 JSON を指定しない場合は、出力が表形式で返されます。
help | --help | -h
コマンドで使用できるオプションがリストされます。

経路を示す ibmcloud metrics-router route get --route new-route-name コマンドの使用例を以下に示します。

ibmcloud mr route get --route route-all
OK
Route
Name:         route-all
ID:           f22e9cb6-2fcd-456d-9cf2-27813b1cc375
CRN:          crn:v1:bluemix:public:metrics-router:global:a/xxxx::route:f22e9cb6-2fcd-456d-9cf2-27813b1cc375
Rule 0:       [[551957a7-c1e3-4160-84d8-4268709f6743(mon-std)], []]
Created At:   2023-05-30T08:04:53.183Z
Updated At:   2023-05-30T08:53:22.824Z

リージョン内のすべての経路のリスト

このコマンドを使用して、IBM Cloud Metrics Routingリージョンの構成済みルートを一覧表示します。

ibmcloud metrics-router route ls [--output FORMAT]

コマンド・オプション

--output FORMAT
現在サポートされている形式は JSON です。 指定すると、出力が JSON 形式で返されます。 JSON を指定しない場合は、出力が表形式で返されます。
help | --help | -h
コマンドで使用できるオプションがリストされます。

**ibmcloud metrics-router route ls**コマンドの使用例を以下に示します。

ibmcloud mr route ls
OK
Routes
Name:         route-all
ID:           f22e9cb6-2fcd-456d-9cf2-27813b1cc375
CRN:          crn:v1:bluemix:public:metrics-router:global:a/xxxx::route:f22e9cb6-2fcd-456d-9cf2-27813b1cc375
Rule 0:       [[551957a7-c1e3-4160-84d8-4268709f6743(mon-std)], []]
Created At:   2023-05-30T08:04:53.183Z
Updated At:   2023-05-30T08:53:22.824Z

API の経路とアクション

次の表は、経路を管理するために実行できるアクションのリストです。

ルート・アクションを使用するIBM Cloud Metrics RoutingREST API
アクション REST API メソッド API_URL
経路の作成 POST <ENDPOINT>/api/v3/routes
経路の更新 PATCH <ENDPOINT>/api/v3/routes/<route_ID>
経路の削除 DELETE <ENDPOINT>/api/v3/routes/<route_ID>
経路の読み取り GET <ENDPOINT>/api/v3/routes/<route_ID>
すべての経路をリストします GET <ENDPOINT>/api/v3/routes

プライベート・エンドポイントとパブリック・エンドポイントを使用して経路を管理することができます。 使用可能な ENDPOINTS のリストについて詳しくは、エンドポイントを参照してください。

  • プライベートネットワークからのルートは、以下の形式のAPIエンドポイントを使って管理できます: https://private.REGION.metrics-router.cloud.ibm.com

  • 以下の形式のAPIエンドポイントを使用して、パブリックネットワークからルートを管理できます: https://REGION.metrics-router.cloud.ibm.com

  • アカウント設定を更新することで、パブリック・エンドポイントを無効にすることができます。 詳しくは、 経路と地域の設定の構成 を参照してください。

REST API について詳しくは、 経路を参照してください。

API の前提条件

経路を管理するための API 呼び出しを行うには、以下のステップを実行します。

  1. IAM アクセス・トークンを取得します。 詳しくは、IAM アクセス・トークンの取得を参照してください。
  2. 経路を構成または管理する予定の地域の API エンドポイントを識別します。 詳しくは、エンドポイントを参照してください。

API を使用した経路の作成

次の cURL コマンドを使用して、経路を作成できます。

経路名はアカウント内で固有です。 経路名を再使用して複数の宛先を構成することはできません。

curl -X POST <ENDPOINT>/api/v3/routes -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json" -d '{
    -d '{
    "name": "ROUTE_NAME",
    "rules": [
      RULES
    ]
  }'

説明

<ENDPOINT>

ルートを設定または管理する予定の地域のAPIエンドポイント。 詳しくは、エンドポイントを参照してください。

ROUTE_NAME

経路に付ける名前。

リソース名に個人識別情報 (PII) を含めないでください。

RULES

メトリックのルーティング方法を定義する JSON 形式のルール配列定義 (単一引用符で囲む)。 詳しくは、 ルーティング・ルールの定義 を参照してください。

例えば、次のようなcURLリクエストを使ってルートを作成することができます:

curl -X POST https://private.us-south.metrics-router.cloud.ibm.com/api/v3/routes -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json" -d '{
    "name": "My-route",
    "rules": [
      {
        "action": "send",
        "targets": [
          {
            "id": "50375218-7cff-4234-bbb4-171bebab8408"
          },
          {
            "id": "c7519d8a-5f97-498b-a229-8542f60955cd"
          }
        ],
        "inclusion_filters": [
          {
            "operand": "location",
            "operator": "is",
            "values": ["us-east"]
          },
          {
            "operand": "service_name",
            "operator": "in",
            "values": ["codeengine","container-registry"]
          }
        ]
      }
    ]
  }'

API を使用した経路の更新

ルートおよびルールの名前を変更できます。 ルートが最初に作成されたときと異なる指定された値は、リクエストで指定された値に更新されます。

経路を更新する場合は、要求のデータ・セクションに経路情報を含める必要があります。

  • すべてのフィールドを渡す必要があります。
  • 変更する必要があるフィールドを更新します。

経路名はアカウント内で固有です。 経路名を再使用して複数の宛先を構成することはできません。

次の cURL コマンドを使用して、経路を更新できます。

curl -X PATCH <ENDPOINT>/api/v3/routes/ROUTE_ID -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json" -d '{
    "name": "ROUTE_NAME",
    "rules": [
      RULES
    ]
  }'

説明

<ENDPOINT>

ルートを設定または管理する予定の地域のAPIエンドポイント。 詳しくは、エンドポイントを参照してください。

ROUTE_ID

経路ID。

ROUTE_NAME

経路の名前。 この名前の最大長は 256 文字です。

リソース名に個人識別情報 (PII) を含めないでください。

RULES

メトリックのルーティング方法を定義する JSON 形式のルール配列定義 (単一引用符で囲む)。 詳しくは、 ルーティング・ルールの定義 を参照してください。

例えば、以下のcURLリクエストを使って、Dallasにルートを作成することができます:

curl -X PATCH https://private.us-south.metrics-router.cloud.ibm.com/api/v3/routes -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json" -d '{
    "name": "My route",
    "rules": [
      {
        "action": "send",
        "targets": [
          {
            "id": "50375218-7cff-4234-bbb4-171bebab8408"
          },
          {
            "id": "c7519d8a-5f97-498b-a229-8542f60955cd"
          }
        ],
        "inclusion_filters": [
          {
            "operand": "location",
            "operator": "is",
            "values": ["us-east"]
          },
          {
            "operand": "service_name",
            "operator": "in",
            "values": ["codeengine","container-registry"]
          }
        ]
      }
    ]
    }
  }'

API を使用した経路の削除

次の cURL コマンドを使用して、経路を削除できます。

curl -X DELETE <ENDPOINT>/api/v3/routes/<route_ID> -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

説明

<ENDPOINT>
ルートを設定または管理する予定の地域のAPIエンドポイント。 詳しくは、エンドポイントを参照してください。
<route_ID>
経路ID。

たとえば、ID '00000000-0000-0000-0000-000000000000 のルートを削除するには、次のようなcURLリクエストを使うことができます:

curl -X DELETE https://private.us-south.metrics-router.cloud.ibm.com/api/v3/routes/00000000-0000-0000-0000-000000000000 -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

API を使用した経路の表示

次のcURLコマンドを使って、1ルートのコンフィギュレーションの詳細を見ることができます:

curl -X GET <ENDPOINT>/api/v3/routes/<route_ID> -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

説明

<ENDPOINT>
ルートを設定または管理する予定の地域のAPIエンドポイント。 詳しくは、エンドポイントを参照してください。
<route_ID>
経路ID。

例えば、以下の cURL 要求を実行して、ID 00000000-0000-0000-0000-000000000000の経路に関する情報を取得できます。

curl -X GET https://private.us-south.metrics-router.cloud.ibm.com/api/v3/routes/00000000-0000-0000-0000-000000000000 -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

APIを使用するすべてのルートを一覧表示する

次の cURL コマンドを使用して、すべての経路を表示できます。

curl -X GET <ENDPOINT>/api/v3/routes -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

説明

  • <ENDPOINT>は、経路を構成または管理する予定の地域の API エンドポイントです。 詳しくは、エンドポイントを参照してください。

例えば、Dallasで定義されたルートに関する情報を取得するために、以下のcURLリクエストを実行することができます:

curl -X GET https://private.us-south.metrics-router.cloud.ibm.com/api/v3/routes -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

HTTP 応答コード

IBM Cloud Metrics Routing REST API を使用すると、メソッドが正常に完了したかどうかを示す標準 HTTP 応答コードを取得できます。

  • 200 応答は、どのような場合でも成功を示しています。
  • 4xx 応答は、失敗を示しています。
  • 5xx応答は内部システムエラーを示す。

いくつかの HTTP 応答コードについては、以下の表を参照してください。

HTTPレスポンスコード一覧
状況コード ステータス 説明
200 OK 要求は正常に終了しました。
201 OK 要求は正常に終了しました。 リソースが作成されます。
400 誤った要求 要求は失敗しました。 必要なパラメーターが欠落している可能性があります。
401 無許可 API 要求で使用されている IAM トークンは無効であるか、有効期限が切れています。
403 禁止 権限が不十分なため、操作は禁止されました。
404 見つかりません 要求されたリソースは存在しないか、既に削除されています。
429 要求が多すぎる API に到達する要求の数が多すぎるうえに各要求の間隔が短すぎます。
500 内部サーバー・エラー IBM Cloud Metrics Routing の処理で何らかの問題が発生しました。