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帐户。

   使用用户标识和密码登录后，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目标

使用此命令更新Event Streams IBM Cloud Activity Tracker Event Routing site.data.keyword.messagehub}} 目标。 任何与目标最初创建时不同的指定值都将更新为命令中指定的值。

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。

在响应中，您将获得有关目标的信息，例如表示目标 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是否启用了服务到服务身份验证。 如果启用了服务到服务并且不提供 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个target的配置详情：

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 请求来获取有关在 Dallas 中定义的目标的信息：

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. 选择目标。

表格详细信息：

• 目标类型
• 目标名称
• 目的地区域
• 路线：如果在任何路线中使用
• 目标状态：
  • 活动：目标按预期工作
  • 错误：目标配置错误，事件不会被路由到目的地。 更新目标详细信息或目的地以修复目标配置，或删除不再需要的目标