CLI 必要條件

在使用 CLI 來管理目標之前，請完成下列步驟:

1. 安裝 IBM Cloud CLI。

2. 安裝 IBM Cloud Activity Tracker Event Routing CLI。

3. 登入 IBM Cloud。 執行下列指令: ibmcloud login

使用相同帳戶的使用者介面來配置 S2S 授權

請執行下列動作，以使用 IBM Cloud 使用者介面來配置服務對服務授權。

1. 以將配置 IBM Cloud Activity Tracker Event Routing 目標的帳戶擁有者身分登入 IBM Cloud 帳戶。

   在使用您的使用者 ID 和密碼登入之後，IBM Cloud 儀表板即會開啟。

2. 點選「管理」> 存取權限 (IAM)。 此時會顯示「管理存取權限與使用者」畫面。

3. 按一下 授權。

4. 按一下建立。

5. 針對 來源服務，選取 Activity Tracker，並針對 How do you want to scope the access? 選取 All resources。

6. 針對 目標服務，選取 Cloud Object Storage for 您要如何設定存取權的範圍? 選取 根據所選取屬性的資源。

7. 選取 服務實例，且 字串等於 COS 實例的名稱。

8. 針對 服務存取權，選取 物件寫出器。

9. 按一下授權。 您的新服務對服務授權會列在 管理授權 視圖中。

您只能透過使用者介面 (UI) 對 IBM Cloud Object Storage 實例進行授權。 若要將授權範圍限制在特定的 IBM Cloud Object Storage 儲存桶內，您需要透過 API 進行授權設定。

使用 CLI 配置 S2S 授權

請執行下列動作，以使用 IBM Cloud CLI 來配置服務對服務授權。

1. 以將配置 IBM Cloud Activity Tracker Event Routing 授權的帳戶擁有者身分登入 IBM Cloud 帳戶。

2. 建立定義服務對服務授權的授權原則。

   ibmcloud iam authorization-policy-create atracker cloud-object-storage "Object Writer" [--target-service-instance-id <COS_SERVICE_INSTANCE>
   

   其中：

   COS_SERVICE_INSTANCE 是要授權之 COS 實例的 儲存區實例 CRN。

使用 API 來配置 S2S 授權

請執行下列動作，以使用 IBM Cloud API 來配置服務對服務授權。

1. 以帳戶擁有者身分登入 IBM Cloud 帳戶，該帳戶擁有者將配置 IBM Cloud Activity Tracker Event Routing IAM 授權。

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:ObjectWriter"
           }
       ],
       "resources": [
           {
               "attributes": [
                 {
                      "name": "accountId",
                      "value": "CUSTOMER_ACCOUNT_ID"
                  },
                  {
                       "name": "serviceName",
                       "value": "cloud-object-storage"
                   },
                   {
                       "name": "serviceInstance",
                       "value": "COS_SERVICE_INSTANCE"
                   }
               ]
           }
       ]
   }
   

   其中：

   CUSTOMER_ACCOUNT_ID 是將配置目標之帳戶的帳戶 GUID。 您可以使用 ibmcloud account list 指令來找到這一點。

   COS_SERVICE_INSTANCE 是要授權之 COS 實例的 儲存區實例 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 建立 COS 目標

請使用這個指令來建立 IBM Cloud Object Storage 目標，以用來配置活動事件的目的地。

 ibmcloud atracker target create --name TARGET_NAME --type TARGET_TYPE ( [--file COS_ENDPOINT_DEFINITION_JSON_FILE] |  ( [--endpoint COS_ENDPOINT] [--bucket COS_BUCKET] [--target-crn COS_TARGET_CRN] ( [--api-key ( COS_API_KEY | @COS_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
Type:               		cloud_object_storage
COS Endpoint:       		s3.us-west.cloud-object-storage.appdomain.cloud
COS Target CRN:     		crn:v1:staging:public:cloud-object-storage:global:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx:
COS Bucket:         		cloud-object-my-target
Service to Service Enabled:	true
Write Status:   		success
Created:            		2021-07-21T16:04:15.174Z
Updated:            		2021-07-21T16:04:15.174Z

使用 CLI 更新 COS 目標

使用此指令來更新 IBM Cloud Activity Tracker Event Routing 區域的 COS 目標。 任何不同於最初建立目標時的指定值都會更新為指令中指定的值。

ibmcloud atracker target update --target TARGET [--name TARGET_NAME] [ [--file COS_ENDPOINT_DEFINITION_JSON_FILE] |  ( [--endpoint COS_ENDPOINT] [--bucket COS_BUCKET] [--target-crn COS_TARGET_CRN] ( [--api-key ( COS_API_KEY | @COS_API_KEY_FILE )] | [--service-to-service-enabled ( TRUE | FALSE )]))] [--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
Type:               		cloud_object_storage
COS Endpoint:       		s3.us-west.cloud-object-storage.appdomain.cloud
COS Target CRN:    		crn:v1:staging:public:cloud-object-storage:global:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx:
COS Bucket:         		cloud-object-my-target
Service to Service Enabled:	true
Write Status:   		success
Created:            		2021-07-21T16:04:15.174Z
Updated:           		2021-07-21T17:49:56.452Z

使用 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
Type:               		cloud_object_storage
COS Endpoint:       		s3.us-west.cloud-object-storage.appdomain.cloud
COS Target CRN:     		crn:v1:staging:public:cloud-object-storage:global:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx:
COS Bucket:         		cloud-object-my-target
Service to Service Enabled:	true
Write Status:   		success
Created:            		2021-07-21T16:04:15.174Z
Updated:           		2021-07-21T17:49:56.452Z

使用 CLI 取得目標的相關資訊

請使用這個指令來取得 IBM Cloud Activity Tracker Event Routing 區域的目標相關資訊。

ibmcloud atracker target get --target TARGET [--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
Type:               		cloud_object_storage
COS Endpoint:      		s3.us-west.cloud-object-storage.appdomain.cloud
COS Target CRN:     		crn:v1:staging:public:cloud-object-storage:global:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx:
COS Bucket:         		cloud-object-my-target
Service to Service Enabled:	true
Write Status:   		success
Created:           		2021-07-21T16:04:15.174Z
Updated:            		2021-07-21T17:49:56.452Z

列出地區中的所有目標

請使用這個指令來列出 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    cloud_object_storage    true				2020-11-18T03:52:08.603Z
target-02                  yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy   us-south    cloud_object_storage    true				2020-11-18T03:52:01.592Z
target-02-backup           zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz   us-east     cloud_object_storage    false				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 建立 COS 目標

您可以使用下列 cURL 指令來建立 IBM Cloud Object Storage (COS) 目標:

curl -X POST  <ENDPOINT>/api/v2/targets   -H "Authorization:  $ACCESS_TOKEN"   -H "content-type: application/json"   -d '{
    "name": "TARGET_NAME",
    "target_type": "cloud_object_storage",
    "cos_endpoint": {
      "endpoint": "PRIVATE_COS_ENDPOINT",
      "target_crn": "COS_CRN",
      "bucket": "BUCKET_NAME",
      "api_key": "API_KEY",
      "service_to_service_enabled": SERVICE_TO_SERVICE
    }
  }'

其中

• <ENDPOINT> 是您計劃在其中配置或管理目標之地區中的 API 端點。 如需相關資訊，請參閱 端點。

• TARGET_NAME 是目標的名稱。 名稱的最大長度為 256 個字元。

  請勿在任何資源名稱中包含任何個人識別資訊 (PII)。

• TARGET_TYPE 是目標的類型。 有效類型為 cloud_object_storage。

• cos_endpoint 包括目標的相關資訊。 如需如何取得儲存區詳細資料的相關資訊，請參閱 取得儲存區配置詳細資料。

PRIVATE_COS_ENDPOINT 指出要尋找此儲存區的 IBM Cloud Activity Tracker Event Routing 端點。 使用專用端點。

COS_CRN 指出您在其中佈建儲存區之 COS 實例的 CRN。

BUCKET_NAME 指出儲存區的名稱。

API_KEY 包含有權將物件上傳至儲存區的 API 金鑰。 如果 service_to_service_enabled 是 true，則會忽略此值。

SERVICE_TO_SERVICE 指出是否已針對儲存區啟用 service-to-service 授權。 如果啟用服務對服務授權，請指定 true ; 如果未啟用服務對服務授權，請指定 false。 依預設，服務對服務授權為 false。

例如，您可以使用下列 cURL 要求，在達拉斯建立目標:

curl -X POST   https://private.us-south.atracker.cloud.ibm.com/api/v2/targets   -H "Authorization:  $ACCESS_TOKEN"   -H "content-type: application/json"   -d '{
    "name": "My COS target",
    "target_type": "cloud_object_storage",
    "cos_endpoint": {
      "endpoint": "s3.private.us-south.cloud-object-storage.appdomain.cloud",
      "target_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/<account-id>:<instance-id>::",
      "bucket": "my-activity-tracking-bucket",
      "api_key": "xxxxxxxxxxxxxxxxxx",
      "service_to_service_enabled": false
    }
  }'

在回應中，您會取得目標的相關資訊，例如 id，指出目標的 GUID，以及 crn，指出目標的 CRN。

使用 API 更新 COS 目標

當您更新 IBM Cloud Object Storage (COS) 目標時，必須在要求的資料區段中包括目標資訊。

• 您必須傳遞所有欄位。
• 更新需要變更的欄位。
• 建立之後，您就無法變更目標的 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",
    "cos_endpoint": {
      "endpoint": "PRIVATE_COS_ENDPOINT",
      "target_crn": "COS_CRN",
      "bucket": "BUCKET_NAME",
      "api_key": "API_KEY",
      "service_to_service_enabled": SERVICE_TO_SERVICE
    }
  }'

其中

• <ENDPOINT> 是您計劃在其中配置或管理目標之地區中的 API 端點。 如需相關資訊，請參閱 端點。

• TARGET_ID 是目標的 ID。

• TARGET_NAME 是目標的名稱。 名稱的最大長度為 256 個字元。

  請勿在任何資源名稱中包含任何個人識別資訊 (PII)。

• TARGET_TYPE 是目標的類型。 將 COS 目標的值設為 cloud_object_storage。

• cos_endpoint 包括目標的相關資訊。 如需如何取得儲存區詳細資料的相關資訊，請參閱 取得儲存區配置詳細資料。

PRIVATE_COS_ENDPOINT 指出要尋找此儲存區的 IBM Cloud Activity Tracker Event Routing 端點。 使用專用端點。

COS_CRN 指出您在其中佈建儲存區之 COS 實例的 CRN。

BUCKET_NAME 指出儲存區的名稱。

API_KEY 包含有權將物件上傳至儲存區的 API 金鑰。 如果 service_to_service_enabled 是 true，則會忽略此值。

SERVICE_TO_SERVICE 指出是否已針對儲存區啟用 service-to-service 授權。 如果啟用服務對服務授權，請指定 true ; 如果未啟用服務對服務授權，請指定 false。 依預設，服務對服務授權為 false。

例如，您可以使用下列 cURL 要求，在達拉斯建立目標:

curl -X PUT   https://private.us-south.atracker.cloud.ibm.com/api/v2/targets   -H "Authorization:  $ACCESS_TOKEN"   -H "content-type: application/json"   -d '{
    "name": "My COS target",
    "target_type": "cloud_object_storage",
    "cos_endpoint": {
      "endpoint": "s3.private.us-south.cloud-object-storage.appdomain.cloud",
      "target_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/<account-id>:<instance-id>::",
      "bucket": "my-activity-tracking-bucket",
      "service_to_service_enabled": 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"

在回應中，您會取得 cos_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")。

使用 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") 目標。

HTTP 回應碼

當您使用 IBM Cloud Activity Tracker Event Routing REST API 時，您可以取得標準的 HTTP 回應代碼，以表示方法是否成功完成。

• 200 回應一律表示成功。
• 4xx 回應指出失敗。
• 5xx 回應通常指出內部系統錯誤。

請參閱下表中的一些 HTTP 回應代碼：

使用使用者介面建立 IBM Cloud Object Storage 目標

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

1. 登入 IBM Cloud 帳戶。
2. 點擊「選單」圖示 > 可觀測性。
3. 選擇「活動追蹤」。
4. 按一下 建立，以開啟建立畫面。
5. 選擇類型: 按一下 Object Storage。
6. 需要服務授權: 需要服務授權才能容許 IBM Cloud Activity Tracker Event Routing 與 IBM Cloud Object Storage進行通訊。 按一下 立即授權 以自動建立原則，或按一下 在 IAM 中授與存取權。
7. 選擇目的地: 挑選 依實例搜尋 或 指定 CRN
   • 依實例搜尋: 從表格中選取 IBM Cloud Object Storage 實例，或按一下 建立 以建立新的 IBM Cloud Object Storage 實例。 選取實例之後，請選取 IBM Cloud Object Storage 儲存區。
   • 指定 CRN: 輸入 IBM Cloud Object Storage 儲存區的雲端資源名稱 (CRN)。 這可讓您從不同的帳戶輸入 CRN。

• 儲存區端點: 使用預設儲存區端點或變更它。
• 目標名稱: 輸入有意義的目標名稱。
• 目標區域: 選取將處理事件資料的區域。
• 切換 設為預設目標，以在 IBM Cloud Activity Tracker Event Routing 設定中自動將新目標設為預設目標。 如需詳細資料，請參閱 預設目標文件。
• 按一下 建立目標。

使用使用者介面更新 IBM Cloud Object Storage 目標

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

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

使用使用者介面刪除目標

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

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

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

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

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

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