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. 對於服務訪問， 選擇 Writer。

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 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 清單的相關資訊，請參閱 端點。

• 您可以使用下列格式的 API 端點，從專用網路管理目標: https://private.REGION.atracker.cloud.ibm.com

• 您可以使用下列格式的 API 端點，從公用網路管理目標: https://REGION.atracker.cloud.ibm.com

• 您可以透過更新帳戶設定來停用公用端點。 如需相關資訊，請參閱 配置目標和區域設定。

如需 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是否啟用了服務到服務驗證。 如果服務到服務已啟用且不提供 apikey，請將此標誌設為 true。

在回應中，您會取得目標的相關資訊，例如 id，指出目標的 GUID，以及 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是否啟用了服務到服務驗證。 如果服務到服務已啟用且不提供 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 要求來刪除美國南部中 ID 為 00000000-0000-0000-0000-000000000000 的目標:

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 回應代碼：

使用使用者介面建立 Event Streams 目標

僅列出並可選取帳戶中的資源。 若要指定不同帳戶中的資源，請在 選擇目的地下選取 指定 CRN。

1. 登入 IBM Cloud 帳戶。
2. 點擊「選單」圖示 > 可觀測性。
3. 選擇「活動追蹤」……
4. 按一下 建立，以開啟建立畫面。
5. 選擇類型: 按一下 Event Streams。
6. 選擇目的地: 挑選 依實例搜尋 或 指定 CRN
   • 依實例搜尋: 從表格中選取 Event Streams 實例，或按一下 建立 以建立新的 Event Streams 實例。
   • 指定 CRN: 輸入 Event Streams 實例的雲端資源名稱 (CRN)。 這可讓您從不同的帳戶輸入 CRN。

• 服務認證: 選取其中一個服務認證，它包含分配管理系統清單使用者名稱及 api_key 或密碼。
• Event Streams 主題: 選取現有主題。
• 目標名稱: 輸入有意義的目標名稱。
• 目標區域: 選取將處理事件資料的區域。
• 切換 設為預設目標，以在 IBM Cloud Activity Tracker Event Routing 設定中自動將新目標設為預設目標。 如需詳細資料，請參閱 預設目標文件。
• 按一下 建立目標。

使用使用者介面更新 Event Streams 目標

僅列出並可選取帳戶中的資源。 若要指定不同帳戶中的資源，請在 選擇目的地下選取 指定 CRN。

1. 登入 IBM Cloud 帳戶。
2. 點擊「選單」圖示 > 可觀測性。
3. 選擇「活動追蹤」。
4. 選定要更新的目標，然後點擊「。
5. 您可以按一下 取消設為預設值，在 IBM Cloud Activity Tracker Event Routing 設定中移除作為預設目標的目標。 如需詳細資料，請參閱 預設目標文件。
6. 按一下 編輯 以開啟更新畫面。
7. 詳細資料: 按一下 編輯，以更新目標的名稱或區域。 您也可以切換 預設目標，以在 IBM Cloud Activity Tracker Event Routing 設定中新增或移除目標作為預設目標。
8. 按一下 儲存 以更新目標。
9. 目的地: 按一下 編輯，以變更與目標相關聯的 Event Streams 實例、服務認證或主題。
10. 按一下 儲存 以更新目標。

使用使用者介面刪除目標

若「IBM Cloud Activity Tracker Event Routing」目標已被用於某條路由，或作為預設目標設定，則無法刪除該目標。

1. 登入 IBM Cloud 帳戶。
2. 點擊「選單」圖示 > 可觀測性。
3. 選擇「活動追蹤」。
4. 選定要刪除的目標，然後點擊「。
5. 按一下 刪除，然後在確認畫面中按一下 刪除。

使用 UI 列出區域中的所有目標

1. 登入 IBM Cloud 帳戶。
2. 點擊「選單」圖示 > 可觀測性。
3. 選擇「活動追蹤」。

下表列出了所有目標的詳細資訊：

• 目標類型
• 目的地名稱
• 目的地區域
• 路徑: 如果在任何路徑中使用它
• 目標狀態：
  • 作用中: 目標如預期般運作
  • 錯誤: 目標配置錯誤，事件將不會遞送至目的地。 更新目標詳細資料或目的地以修正目標配置，或刪除目標 (如果不再需要的話)