CLI の前提条件

CLI を使用してルートを管理する前に、ローカルシステムに最新の Activity Tracker Event Routing CLI V2 プラグインをインストールしてください。 Activity Tracker Event Routing CLI のインストールを参照してください。

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

CLI を使用した経路の作成

このコマンドは、Activity Tracker Event Routing ターゲットの新規経路を作成するために使用します。

ibmcloud atracker route create --name ROUTE_NAME  ( --target-ids TARGETS  [--locations REGIONS] | --rules RULES | --file RULES_DEFINITION_JSON_FILE ) [--output FORMAT]

OK
Route
Name:                    dev-eu-de-route
ID:                      44444444-4444-4444-4444-444444444444
CRN:                     crn:v1:staging:public:atracker:eu-de:a/11111111111111111111111111111111::route:44444444-4444-4444-4444-444444444444
Version:                 0
Rules:                   [locations: [us-south], target_ids: [33333333-3333-3333-3333-333333333333]]
Created:                 2022-02-24T21:10:09.996Z
Updated:                 2022-02-24T21:10:09.996Z

CLI を使用した経路の更新

このコマンドは、Activity Tracker Event Routing ターゲットの経路を更新するために使用します。 経路が最初に作成された時の値とは異なる値をコマンドで指定すると、その値がコマンドの指定値に更新されます。

ibmcloud atracker route update --route ROUTE [--name ROUTE_NAME] [--force] ( [--target-ids TARGETS]  [--locations REGIONS] | [--rules RULES] | [--file RULES_DEFINITION_JSON_FILE] ) [--output FORMAT] [--output FORMAT]

OK
Route
Name:                    dev-eu-de-route
ID:                      44444444-4444-4444-4444-444444444444
CRN:                     crn:v1:staging:public:atracker:eu-de:a/11111111111111111111111111111111::route:44444444-4444-4444-4444-444444444444
Version:                 1
Rules:                   [locations: [*], target_ids: [55555555-5555-5555-5555-555555555555]]
Created:                 2022-02-24T21:10:09.996Z
Updated:                 2022-02-24T21:13:37.218Z

CLI を使用した経路の削除

このコマンドは、Activity Tracker Event Routing 経路を削除するために使用します。

ibmcloud atracker route rm --route ROUTE [--force]

Are you sure you want to remove the route with the Route ID 44444444-4444-4444-4444-444444444444? [y/N]> y
OK
Route with route ID 44444444-4444-4444-4444-444444444444 was successfully removed.

FAILED
No route found with route name - 33333333-3333-3333-3333-333333333333

CLI を使用した経路の表示

このコマンドは、Activity Tracker Event Routing 経路に関する情報を取得するために使用します。

ibmcloud atracker route get --route ROUTE [--output FORMAT]

OK
Route
Name:                    dev-eu-de-route-0
ID:                      44444444-4444-4444-4444-444444444444
CRN:                     crn:v1:staging:public:atracker:eu-de:a/11111111111111111111111111111111::route:44444444-4444-4444-4444-444444444444
Version:                 2
Rules:                   [locations: [us-south], target_ids: [55555555-5555-5555-5555-555555555555]]
Created:                 2022-02-24T21:10:09.996Z
Updated:                 2022-02-24T21:15:07.281Z

CLI を使用したすべての経路のリスト表示

このコマンドを使用して、Activity Tracker Event Routing 用に構成されたすべての経路をリストします。

ibmcloud atracker route ls [--output FORMAT]

Name                      ID                                     Rules                                              Route Version   API version   CreatedAt                  UpdatedAt
my-global-route           aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa   [[11111111-1111-1111-1111-111111111111],[global]]  5               2             2022-05-04T20:18:00.595Z   2022-05-05T19:04:58.374Z
send-all-to-us-east       bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb   [[22222222-2222-2222-2222-222222222222],[*]]       0               2             2022-05-06T12:02:47.832Z   2022-05-06T12:02:47.832Z

API の経路とアクション

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

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

• https://private.REGION.atracker.cloud.ibm.comという形式の API エンドポイントを使用して、プライベート・ネットワークからの経路を管理できます。

• https://REGION.atracker.cloud.ibm.comという形式の API エンドポイントを使用して、パブリック・ネットワークからの経路を管理できます。

• 経路はグローバル構成であるため、任意の地域エンドポイントを使用して、アカウントの経路を管理できます。

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

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

API 前提条件

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

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

API を使用した経路の作成

経路を作成する前に、ターゲットを作成する必要があります。

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

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

説明

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

• ROUTE_NAME は経路の名前です。 名前の最大長は 180 文字であり、特殊文字の -、.、_、: は使用できません。

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

• LOCATIONSは、経路に関連したロケーションのリストです。 グローバル・イベントを含めるには、globalを指定します。 すべてのロケーションを含めるには、*を指定します。 複数のルールと、*ロケーションを持つルールがある場合、その他のルールは、*ロケーションを持つルールによって指定されたターゲットに残りのイベントをルーティングする他のどのルールとも一致しないイベントを使用して、指定されたターゲットにイベントをルーティングします。

• TARGET_IDは、監査イベントがルーティングおよび収集される場所を定義するターゲットの GUID です。 これには、他の領域のターゲットの GUID を含めることができます。 TARGET_IDが空の場合、ルールに一致するすべてのイベントが破棄されます。

例えば、以下の cURL 要求を使用して、グローバル・イベントおよび米国南部ロケーション・ベースのイベントをアカウントで収集してルーティングする方法を定義する経路を作成できます。

curl -X POST   https://private.us-south.atracker.cloud.ibm.com/api/v2/routes   -H "Authorization:  $ACCESS_TOKEN"   -H "content-type: application/json"  -d '{
    "name": "my-route",
    "rules": [
      {
        "locations": ["us-south", "global"],
        "target_ids": ["22222222-2222-2222-2222-222222222222"]
      }
    ]
  }'

応答では、経路の GUID を示す id や経路の CRN を示す crn など、経路に関する情報が得られます。

API を使用した経路の更新

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

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

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

curl -X PUT  <ENDPOINT>/api/v2/routes/<ROUTE_ID>   -H "Authorization:  $ACCESS_TOKEN"   -H "content-type: application/json"  -d '{
    "name": "ROUTE_NAME",
    "rules": [
      {
        "locations": ["LOCATIONS"],
        "target_ids": ["TARGET_ID"]
      }
    ]
  }'

説明

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

• <ROUTE_ID>は、更新する経路の ID です。

• ROUTE_NAME は経路の名前です。 名前の最大長は 180 文字であり、特殊文字の -、.、_、: は使用できません。

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

• LOCATIONSは、経路に関連したロケーションのリストです。 グローバル・イベントを含めるには、globalを指定します。 すべてのロケーションを含めるには、*を指定します。 複数のルールと、*ロケーションを持つルールがある場合、その他のルールは、*ロケーションを持つルールによって指定されたターゲットに残りのイベントをルーティングする他のどのルールとも一致しないイベントを使用して、指定されたターゲットにイベントをルーティングします。

• TARGET_IDは、監査イベントがルーティングおよび収集される場所を定義するターゲットの GUID です。 これには、他の領域のターゲットの GUID を含めることができます。 TARGET_IDが空の場合、ルールに一致するすべてのイベントが破棄されます。

例えば、以下の cURL 要求を使用して、アカウントでグローバルおよび米国南部および米国東部のロケーション・ベースのイベントを収集してルーティングする方法を定義する経路を更新できます。

curl -X PUT https://private.us-south.atracker.cloud.ibm.com/api/v2/routes/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa   -H "Authorization:  $ACCESS_TOKEN"   -H "content-type: application/json"  -d '{
    "name": "my-route",
    "rules": [
      {
        "locations": ["us-south", "global", "us-east],
        "target_ids": ["22222222-2222-2222-2222-222222222222"]
      }
    ]
  }'

API を使用した経路の削除

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

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

説明

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

例えば、以下の cURL 要求を実行して、ID aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaaの経路を削除できます。

curl -X DELETE  https://private.us-south.atracker.cloud.ibm.com/api/v2/routes/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa -H "Authorization:  $ACCESS_TOKEN"   -H "content-type: application/json"

API を使用した経路の表示

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

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

説明

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

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

curl -X GET   https://private.us-south.atracker.cloud.ibm.com/api/v2/routes/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa    -H "Authorization:  $ACCESS_TOKEN"   -H "content-type: application/json"

API を使用したリージョン内のすべての経路のリスト

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

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

説明

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

例えば、以下の cURL 要求を実行して、米国南部で定義されている経路に関する情報を取得できます。

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

HTTP 応答コード

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

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

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

UI を使用した経路の作成

1. IBM Cloud アカウントにログインします。
2. メニュー アイコンをクリックしてください > オブザーバビリティ。
3. 「 アクティビティの追跡 」を選択します。
4. 「経路」 を選択します。
5. 「 作成 」をクリックして、作成ページを開きます。
6. 経路の分かりやすい名前を入力します。
7. 「ルーティング・ルール」 で、 「ルール 1」 を以下のように変更します。
   • 監査イベントの送信元: このルールに一致する監査イベントの場所を選択します。
   • ターゲットへ: このルールに付加するターゲットを選択します。 ルールにさらにターゲットを追加するには、 「ターゲットの追加」 をクリックします。
8. ルートにさらにルールを追加するには、 「ルールの追加」 をクリックします。
   • ルート・ルールの順序は、ルーティングの動作に影響します。 ルールは順番に処理され、ルールが一致すると、後続のルールは処理されません。
9. 各ルールには上矢印と下矢印があり、これらを使用してルールの順序を変更できます。
10. 各ルールには、ルートからルールを削除できる 「削除」 ボタンがあります。
11. ルート定義を調べて、ルールの順序が意図したとおりであることを確認してください。
12. 「作成」 をクリックします。

UI を使用したルートの更新

1. IBM Cloud アカウントにログインします。
2. メニュー アイコンをクリックしてください > オブザーバビリティ。
3. 「 アクティビティの追跡 」を選択します。
4. 「経路」 を選択します。
5. 更新するルートを決定し、 をクリックします。
6. 「名前変更」 をクリックして、経路の名前を変更します。
7. 「編集」 をクリックして、ルート・ルールを更新します。
8. 必要に応じて、既存のルールを編集します。
   • 監査イベントの送信元: このルールに一致する監査イベントの場所を選択します。
   • ターゲットへ: このルールに付加するターゲットを選択します。 ルールにさらにターゲットを追加するには、 「ターゲットの追加」 をクリックします。
9. ルートにさらにルールを追加するには、 「ルールの追加」 をクリックします。
   • ルート・ルールの順序は、ルーティングの動作に影響します。 ルールは順番に処理され、ルールが一致すると、後続のルールは処理されません。
10. 各ルールには上矢印と下矢印があり、これらを使用してルールの順序を変更できます。
11. 各ルールには、ルートからルールを削除できる 「削除」 ボタンがあります。
12. 「更新」 をクリックして、経路を変更します。

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

1. IBM Cloud アカウントにログインします。
2. メニュー アイコンをクリックしてください > オブザーバビリティ。
3. 「 アクティビティの追跡 」を選択します。
4. 「経路」 を選択します。
5. 経路テーブルは作成日順に配列されます。 経路の順序は、ルーティングの動作には影響しません。
6. 各経路ブロックには、経路名と規則が表示されます。
7. 「経路」ページには、ルーティングの構成に関する追加情報とともに 「ルーティングのガイダンス」 も表示されます。

UI を使用した経路の削除

1. IBM Cloud アカウントにログインします。
2. メニュー アイコンをクリックしてください > オブザーバビリティ。
3. 「 アクティビティの追跡 」を選択します。
4. 「経路」 を選択します。
5. 更新するルートを決定し、 をクリックします。
6. 経路全体を削除するには、 「削除」 をクリックします。 経路を削除する前に、経路名を入力する必要があります。