CLI の前提条件

CLI を使用してターゲットを管理する前に、以下の手順を実行します。

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

2. IBM Cloud Activity Tracker Event Routing CLI をインストールします。

   Event Streams CLI コマンドを実行するには、 atracker CLI 0.3.2 以上が必要です。 以前に atracker CLI をインストールした場合は、 ibmcloud plugin update atracker を実行して atracker CLI プラグインをアップグレードすることが必要な場合があります。

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

同一アカウント内でUIを使用した S2S 認証の設定

IBM Cloud UI を使用してサービス間許可を構成するには、以下の手順を実行します。

1. IBM Cloud Activity Tracker Event Routing ターゲットを構成するアカウント所有者として IBM Cloud アカウントにログインします。

   ユーザー ID とパスワードを使用してログインすると、IBM Cloud ダッシュボードが開きます。

2. 「管理」 > **「アクセス (IAM)」**をクリックします。 アクセスとユーザーの管理 が表示されます。

3. 「許可」 をクリックします。

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

5. **ソース・サービスでは **Activity Tracker を選択し、「 アクセス範囲をどのように設定しますか？ には「 すべてのリソース 」を選択します。

6. 対象サービス 」で Message Hubアクセス範囲をどのように設定するか] は、[ 選択した属性に基づくリソース ]を選択します。

7. サービス インスタンスを選択し、 文字列はEvent Streams インスタンスの名前に等しくなります。

8. サービスアクセスは ライターを選択。

9. 「許可」 をクリックします。 新しいサービス間許可が「許可の管理」ビューにリストされます。

CLI を使用した S2S 認証の設定

IBM Cloud CLI を使用してサービス間許可を構成するには、以下の手順を実行します。

1. IBM Cloud Activity Tracker Event Routing 認証を設定するアカウント所有者として、 IBM Cloud アカウントにログイン します。

2. サービス間許可を定義する許可ポリシーを作成します。

   ibmcloud iam authorization-policy-create atracker messagehub "Writer" [--target-service-instance-id <IES_SERVICE_INSTANCE>
   

   ここで、

   IES_SERVICE_INSTANCE は認可されるEvent StreamsインスタンスのCRNです。

API を使用した S2S 認証の設定

IBM Cloud API を使用してサービス間許可を構成するには、以下の手順を実行します。

1. IBM Cloud Activity Tracker Event Routing IAM 許可を構成するアカウント所有者として IBM Cloud アカウントにログインします。

2. サービス間許可を定義するauthorization_policy_resource.jsonファイルを作成します。

   {
       "type": "authorization",
       "subjects": [
           {
               "attributes": [
                 {
                      "name": "accountId",
                      "value": "CUSTOMER_ACCOUNT_ID"
                  },
                  {
                       "name": "serviceName",
                       "value": "atracker"
                   }
               ]
           }
       ],
       "roles": [
           {
               "role_id": "crn:v1:bluemix:public:iam::::serviceRole:Writer"
           }
       ],
       "resources": [
           {
               "attributes": [
                 {
                      "name": "accountId",
                      "value": "CUSTOMER_ACCOUNT_ID"
                  },
                  {
                       "name": "serviceName",
                       "value": "messagehub"
                   },
                   {
                       "name": "serviceInstance",
                       "value": "IES_SERVICE_INSTANCE"
                   }
               ]
           }
       ]
   }
   

   ここで、

   CUSTOMER_ACCOUNT_IDは、ターゲットを構成するアカウントのアカウント GUID です。 これは、ibmcloud account listコマンドを使用して見つけることができます。

   IES_SERVICE_INSTANCE は認可されるIESインスタンスのCRNです。

3. IAM アクセス・トークンを取得します。 詳しくは、IAM アクセス・トークンの取得を参照してください。

4. 以下のコマンドを実行して、サービス間許可を構成します。

   curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header "Authorization: $ACCESS_TOKEN" -d @authorization_policy_resource.json "https://iam.cloud.ibm.com/v1/policies"
   

CLI を使用した Event Streams ターゲットの作成

このコマンドを使用して、アクティビティ・イベントの宛先設定に使用する IBM® Event Streams for IBM Cloud® ターゲットを作成します。

 ibmcloud atracker target create --name TARGET_NAME --type TARGET_TYPE ( [--file EVENTSTREAMS_ENDPOINT_DEFINITION_JSON_FILE] | ( [--target-crn EVENTSTREAMS_TARGET_CRN] [--brokers BROKER_LIST] [--topic TOPIC] [--api-key ( EVENTSTREAMS_API_KEY | @EVENTSTREAMS_API_KEY_FILE )] | [--service-to-service-enabled ( TRUE | FALSE )]) ) [--region REGION] [--output FORMAT]

Target
Name:                     my-target
ID:                       000000000-00000000-0000-0000-00000000
CRN:                      crn:v1:staging:public:atracker:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx
Region:                   us-south
Type:                     event_streams
Event Streams Target CRN: crn:v1:bluemix:public:messagehub:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx::
Event Streams Topic:      my-topic
Event Streams Brokers:    [broker-1:9093,broker-2:9093]
Write Status:             success
CreatedAt:                2022-10-20T19:20:38.888Z
UpdatedAt:                2022-10-20T19:20:38.888Z

CLI を使用した Event Streams ターゲットの更新

IBM Cloud Activity Tracker Event Routing リージョンの Event Streams ターゲットを更新するには、このコマンドを使う。 ターゲットが最初に作成された時の値とは異なる値をコマンドで指定すると、その値がコマンドの指定値に更新されます。

ibmcloud atracker target update --target TARGET [--name TARGET_NAME] [ [--file EVENTSTREAMS_ENDPOINT_DEFINITION_JSON_FILE] | ( [--brokers BROKER_LIST] [--target-crn EVENTSTREAMS_TARGET_CRN] [--topic TOPIC] ( [--api-key ( EVENTSTREAMS_API_KEY | @EVENTSTREAMS_API_KEY_FILE )] | [--service-to-service-enabled ( TRUE | FALSE )]))] [--output FORMAT]

Target
Name:                     my-new-target
ID:                       000000000-00000000-0000-0000-00000000
CRN:                      crn:v1:staging:public:atracker:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx
Region:                   us-south
Type:                     event_streams
Event Streams Target CRN: crn:v1:bluemix:public:messagehub:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx::
Event Streams Topic:      my-topic
Event Streams Brokers:    [broker-1:9093,broker-2:9093]
Write Status:             success
CreatedAt:                2022-10-20T19:20:38.888Z
UpdatedAt:                2022-10-20T19:20:38.888Z

CLI を使用したターゲットの削除

このコマンドは、ターゲットを削除するために使用します。

ibmcloud atracker target rm --target TARGET [--force]

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

Are you sure you want to remove the Target bearing Target ID 33333333-3333-3333-3333-333333333333? [y/N]> y
FAILED
Something went wrong. Error:
 Status Code:  404
 Incident ID:  67a33257-d5a4-46ec-94d9-14eb70e94f3d
 Code:         not_found
 Message:      The target id specified in `target_id` field is not found.

CLI を使用したターゲットの検証

このコマンドを使用して、IBM Cloud Activity Tracker Event Routing リージョンのターゲットが正しく構成されていることを確認します。

ibmcloud atracker target validate --target TARGET [--region REGION] [--output FORMAT]

Target
Name:               		    new-target-name
ID:                 		    xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
CRN:               		      crn:v1:staging:public:atracker:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx
Region:                     us-south
Type:                       event_streams
Event Streams Target CRN:   crn:v1:bluemix:public:messagehub:us-south:a/a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx::
Event Streams Topic:        my-test-topic
Event Streams Brokers:      [broker-1:9093,broker-2:9093]
Write Status:               success
CreatedAt:                  2022-10-20T19:20:38.888Z
UpdatedAt:                  2022-10-20T19:20:38.888Z

CLI を使用したターゲットに関する情報の取得

このコマンドを使用して、IBM Cloud Activity Tracker Event Routing リージョンのターゲットに関する情報を取得します。

ibmcloud atracker target get --target TARGET [--output FORMAT]

Target
Name:               		    updated-target-name
ID:                 		    xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
CRN:               		      crn:v1:staging:public:atracker:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx
Region:                     us-south
Type:                       event_streams
Event Streams Target CRN:   crn:v1:bluemix:public:messagehub:us-south:a/a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx::
Event Streams Topic:        my-test-topic
Event Streams Brokers:      [broker-1:9093,broker-2:9093]
Write Status:               success
CreatedAt:                  2022-10-20T19:20:38.888Z
UpdatedAt:                  2022-10-20T19:20:38.888Z

リージョン内のすべてのターゲットのリスト

このコマンドを使用して、IBM Cloud Activity Tracker Event Routing リージョンの構成済みターゲットを表示します。

ibmcloud atracker target ls [--output FORMAT]

Name                       ID                                     Region     Type             Service to Service Enabled Created
target-01                  xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx   us-south    event_streams   -				                     2020-11-18T03:52:08.603Z
target-02                  yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy   us-south    event_streams   -				                     2020-11-18T03:52:01.592Z
target-02-backup           zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz   us-east     event_streams   -				                     2021-02-26T06:53:13.466Z

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 を使用した Event Streams ターゲットの作成

以下のcurlコマンドを使って、 IBM® Event Streams for IBM Cloud® ( Event Streams ) ターゲットを作成することができます：

curl -X POST  <ENDPOINT>/api/v2/targets   -H "Authorization:  $ACCESS_TOKEN"   -H "content-type: application/json"   -d '{
    "name": "TARGET_NAME",
    "target_type": "TARGET_TYPE",
    "eventstreams_endpoint": {
        "target_crn": "EVENTSTREAMS_CRN",
        "brokers": "BROKER_LIST",
        "topic”: "TOPIC_NAME",
        "password": "API_KEY",
        "service_to_service_enabled": false}
    }
  }'

説明

• TARGET_NAME は、ターゲットの名前です。 この名前の最大長は 256 文字です。

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

• TARGET_TYPE は、ターゲットのタイプです。 Event Streams ターゲットの場合は、値を event_streams に設定します。

• BROKER_LIST は、 Event Streams ブローカー (エンドポイント) のリストです。

• TOPIC_NAME は、イベントが送信される Event Streams トピックの名前です。

• API_KEY は、 Event Streams サービス資格情報で見つかったパスワード値です。 これは IAM API キーです。

• service_to_service_enabled は、IBM Cloud Activity Tracker Event Routingがサービス間認証を有効にしているかどうかを判定します。 service to serviceが有効で、apikeyを提供しない場合、このフラグをtrueに設定する。

応答では、ターゲットの GUID を示す id やターゲットの CRN を示す crn など、ターゲットに関する情報が得られます。

API を使用した Event Streams ターゲットの更新

IBM® Event Streams for IBM Cloud® ( Event Streams ) ターゲットを更新する場合、リクエストのデータセクションにターゲット情報を含める必要があります。

• すべてのフィールドを渡す必要があります。
• 変更する必要があるフィールドを更新します。
• 作成したターゲットのtarget_typeを変更することはできません。

以下の cURL コマンドを使用して、ターゲットを更新できます。

curl -X PUT  <ENDPOINT>/api/v2/targets/TARGET_ID  -H "Authorization:  $ACCESS_TOKEN"   -H "content-type: application/json"   -d '{
    "name": "TARGET_NAME",
    "target_type": "TARGET_TYPE",
    "eventstreams_endpoint": {
      "target_crn": "EVENTSTREAMS_CRN",
      "brokers": "BROKER_LIST",
      "topic”: "TOPIC_NAME",
      "password": "API_KEY",
      "service_to_service_enabled": false}
    }
  }'

説明

• TARGET_IDはターゲットの ID です。

• TARGET_NAME は、ターゲットの名前です。 この名前の最大長は 256 文字です。

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

• TARGET_TYPE は、ターゲットのタイプです。 Event Streams ターゲットの場合は、値を event_streams に設定します。

• BROKER_LIST は、 Event Streams ブローカー (エンドポイント) のリストです。

• TOPIC_NAME は、イベントが送信される Event Streams トピックの名前です。

• API_KEY は、 Event Streams サービス資格情報で見つかったパスワード値です。 これは IAM API キーです。

• service_to_service_enabled は、IBM Cloud Activity Tracker Event Routingがサービス間認証を有効にしているかどうかを判定します。 service to serviceが有効で、apikeyを提供しない場合、このフラグをtrueに設定する。

API を使用したターゲットの削除

以下の cURL コマンドを使用して、ターゲットを削除できます。

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

説明

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

例えば、以下の cURL 要求を使用して、00000000-0000-0000-0000-000000000000という ID を持つ米国南部のターゲットを削除できます。

curl -X DELETE https://private.us-south.atracker.cloud.ibm.com/api/v2/targets/00000000-0000-0000-0000-000000000000 -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

削除が成功した場合、応答で空の結果が返されます。

{}

API を使用したターゲットの検証

以下の cURL コマンドを使用して、ターゲットに書き込む資格情報をチェックすることにより、ターゲットを検証できます。

curl -X POST <ENDPOINT>/api/v2/targets/<TARGET_ID>/validate -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

説明

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

例えば、以下の cURL 要求を使用して、ID 00000000-0000-0000-0000-000000000000を持つ米国南部のターゲットを検証できます。

curl -X POST https://private.us-south.atracker.cloud.ibm.com/api/v2/targets/<TARGETID>/validate -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

レスポンスでは、例えば、 write_status のセクションで情報を得る：

"write_status": {
    "status": "success"
  },

API を使用したターゲットの表示

次の cURL コマンドを使用して、1 つのターゲットの構成の詳細を表示することができます。

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

説明

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

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

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

結果は、ターゲットが COS ("target_type": "cloud_object_storage") か Event Streams ("target_type": "event_streams") かを示します。

API を使用したすべてのターゲットのリスト表示

次の cURL コマンドを使用して、すべてのターゲットを表示できます。

curl -X GET <ENDPOINT>/api/v2/targets -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/targets -H "Authorization:  $ACCESS_TOKEN" -H "content-type: application/json"

結果は、ターゲットが COS ("target_type": "cloud_object_storage") か Event Streams ("target_type": "event_streams") かを示します。

HTTP 応答コード

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

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

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

UI を使用した Event Streams ターゲットの作成

アカウント内のリソースのみがリストされ、選択可能です。 別のアカウントのリソースを指定するには、 「宛先の選択」 で 「CRN の指定」 を選択します。

1. IBM Cloud アカウントにログインします。
2. 「メニュー」 アイコン > **「可観測性」**をクリックします。
3. **「Activity Tracker」**を選択します。
4. 「ルーティング」 を選択します。
5. ターゲットを選択する。
6. 「作成」 をクリックして、作成パネルを開きます。
7. タイプの選択: Event Streams をクリックします。
8. 宛先の選択: 「インスタンスで検索」 または 「CRN の指定」 を選択します。
   • インスタンスで検索: テーブルから Event Streams インスタンスを選択するか、 「作成」 をクリックして新しい Event Streams インスタンスを作成します。
   • CRN の指定: Event Streams インスタンスのクラウド・リソース名 (CRN) を入力します。 これにより、別のアカウントから CRN を入力できます。

• サービス資格情報: いずれかのサービス資格情報を選択します。サービス資格情報には、ブローカー・リストのユーザー名と、api_key またはパスワードが含まれています。
• Event Streams トピック: 既存のトピックを選択します。
• ターゲット名: ターゲットの分かりやすい名前を入力します。
• ターゲット・リージョン: イベント・データを処理するリージョンを選択します。
• 「デフォルト・ターゲットとして設定」 を切り替えて、新規ターゲットを IBM Cloud Activity Tracker Event Routing 設定のデフォルト・ターゲットとして自動的に設定します。 詳しくは、 デフォルト・ターゲットの資料 を参照してください。
• 「ターゲットの作成」 をクリックします。

UI を使用した Event Streams ターゲットの更新

アカウント内のリソースのみがリストされ、選択可能です。 別のアカウントのリソースを指定するには、 「宛先の選択」 で 「CRN の指定」 を選択します。

1. IBM Cloud アカウントにログインします。
2. 「メニュー」 アイコン > **「可観測性」**をクリックします。
3. **「Activity Tracker」**を選択します。
4. 「ルーティング」 を選択します。
5. ターゲットを選択する。
6. 更新するターゲットを決定し、 をクリックします。
7. 「デフォルトとして設定解除」 をクリックすると、 IBM Cloud Activity Tracker Event Routing 設定のデフォルト・ターゲットとしてのターゲットを削除できます。 詳しくは、 デフォルト・ターゲットの資料 を参照してください。
8. 「編集」 をクリックして、更新パネルを開きます。
9. 詳細: 「編集」 をクリックして、ターゲットの名前またはリージョンを更新します。 また、 「デフォルト・ターゲット」 を切り替えて、 IBM Cloud Activity Tracker Event Routing 設定でターゲットをデフォルト・ターゲットとして追加または削除することもできます。
10. 「保存」 をクリックして、ターゲットを更新します。
11. 宛先: 「編集」 をクリックして、ターゲットに関連付けられている Event Streams インスタンス、サービス資格情報、またはトピックを変更します。
12. 「保存」 をクリックして、ターゲットを更新します。

UIを使用したターゲットの削除

IBM Cloud Activity Tracker Event Routing ターゲットは、経路で使用されている場合、またはデフォルトのターゲット設定として使用されている場合は削除できません。

1. IBM Cloud アカウントにログインします。
2. 「メニュー」 アイコン > **「可観測性」**をクリックします。
3. **「Activity Tracker」**を選択します。
4. 「ルーティング」 を選択します。
5. ターゲットを選択する。
6. 削除するターゲットを決定し、 をクリックします。
7. 「削除」 をクリックしてから、確認パネルで 「削除」 をクリックします。

UIを使用してリージョン内のすべてのターゲットをリストする

1. IBM Cloud アカウントにログインします。
2. 「メニュー」 アイコン > **「可観測性」**をクリックします。
3. **「Activity Tracker」**を選択します。
4. 「ルーティング」 を選択します。
5. ターゲットを選択する。

表の詳細は以下のとおりです。

• ターゲット・タイプ
• 宛先名
• 宛先リージョン
• 経路: いずれかの経路で使用されている場合
• ターゲットのステータス
  • アクティブ: ターゲットは予期したとおりに機能しています
  • エラー: ターゲットの構成が誤っているため、イベントは宛先にルーティングされません。 ターゲットの詳細または宛先を更新してターゲット構成を修正するか、不要になった場合はターゲットを削除してください。