本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 创建与控制台的自定义集成
<a name="query-event-data-store-integration-custom"></a>

您可以使用 CloudTrail 来记录和存储混合环境中任何来源的用户活动数据，例如本地或云端托管的内部或 SaaS 应用程序、虚拟机或容器。在 CloudTrail Lake 控制台中执行此过程的前半部分，然后调用 [https://docs.amazonaws.cn/awscloudtraildata/latest/APIReference/API_PutAuditEvents.html](https://docs.amazonaws.cn/awscloudtraildata/latest/APIReference/API_PutAuditEvents.html)API 来采集事件，提供您的频道 ARN 和事件有效负载。在使用 `PutAuditEvents` API 将应用程序活动导入后 CloudTrail，您可以使用 CloudTrail Lake 来搜索、查询和分析从您的应用程序中记录的数据。

1. 登录 Amazon Web Services 管理控制台 并打开 CloudTrail 控制台，网址为[https://console.aws.amazon.com/cloudtrail/](https://console.amazonaws.cn/cloudtrail/)。

1.  在导航窗格中，打开 **Lake** 子菜单，然后选择**集成**。

1. 在 **Add integration**（添加集成）页面上，为您的通道输入名称。该名称可以包含 3-128 个字符。只允许使用字母、数字、句点、下划线和短划线。

1. 选择 **My custom integration**（我的自定义集成）。

1. 在 **Event delivery location**（事件传送位置）中，选择将相同活动事件记录到现有事件数据存储中，或创建新的事件数据存储。

   如果您选择创建新的事件数据存储，请输入事件数据存储的名称，并以天为单位指定保留期。如果您选择**一年可延期保留定价**选项，则可以将事件数据在事件数据存储中最多保留 3653 天（大约 10 年）；如果您选择**七年保留定价**选项，则最多可以保留 2557 天（大约 7 年）。

   如果您选择将活动事件记录到一个或多个现有事件数据存储中，请从列表中选择事件数据存储。事件数据存储只能包含活动事件。控制台中的事件类型必须是 **Events from integrations**（来自集成的事件）。在 API 中，`eventCategory` 值必须为 `ActivityAuditLog`。

1. 在 **Resource policy**（资源策略）中，为集成的通道配置资源策略。资源策略是 JSON 策略文档，它们指定了指定主体可在资源上执行的操作，以及在什么条件下执行操作。在资源策略中定义为主体的账户可以调用 `PutAuditEvents` API，以向您的通道传送事件。
**注意**  
如果您没有为通道创建资源策略，则只有通道所有者可以针对该通道调用 `PutAuditEvents` API。

   1. （可选）输入唯一的外部 ID，以提供额外一层保护。该外部 ID 是一个唯一的字符串，如账户 ID 或随机生成的字符串，以防范混淆代理。
**注意**  
如果资源策略包括外部 ID，则针对 `PutAuditEvents` API 的所有调用都必须包括该外部 ID。但是，如果策略未定义外部 ID，您仍然可以调用 `PutAuditEvents` API，并指定 `externalId` 参数。

   1. 选择 **Add Amazon ac** count（添加 Amazon 账户），将每个账户 ID 指定为频道资源策略中的委托人。

1. （可选）在 **Tags**（标签）区域中，您最多可以添加 50 个标签键和值对，以帮助您对事件数据存储和通道的访问进行识别、排序和控制。要详细了解如何使用 IAM 策略以根据标签授权对事件数据存储的访问，请参阅[示例：拒绝基于标签创建或删除事件数据存储的访问权限](security_iam_id-based-policy-examples.md#security_iam_id-based-policy-examples-eds-tags)。有关如何在中使用标签的更多信息 Amazon，请参阅中的为[Amazon 资源添加标签](https://docs.amazonaws.cn/tag-editor/latest/userguide/tagging.html)。*Amazon Web Services 一般参考*

1. 在准备好创建新的集成后，请选择 **Add integration**（添加集成）。没有评论页面。 CloudTrail 创建集成，但要集成您的自定义事件，您必须在请求中指定渠道 ARN。[https://docs.amazonaws.cn/awscloudtraildata/latest/APIReference/API_PutAuditEvents.html](https://docs.amazonaws.cn/awscloudtraildata/latest/APIReference/API_PutAuditEvents.html)

1. 调用 `PutAuditEvents` API 将你的活动事件摄取到其中 CloudTrail。每个 `PutAuditEvents` 请求最多可以添加 100 个活动事件（或最多 1 MB）。您需要在前面的步骤中创建的频道 ARN、 CloudTrail 要添加的事件的有效负载以及外部 ID（如果已为资源策略指定）。在将事件载荷摄入之前，请确保其中没有敏感或个人识别信息。 CloudTrail您收录的事件 CloudTrail 必须遵循. [CloudTrail 湖泊集成事件架构](query-integration-event-schema.md) 
**提示**  
[Amazon CloudShell](https://docs.amazonaws.cn/cloudshell/latest/userguide/welcome.html)用于确保您运行的是最新版本 Amazon APIs。

   以下示例演示了如何使用 **put-audit-events** CLI 命令。**--audit-events** 和 **--channel-arn** 参数是必需的。您需要在前面的步骤中创建的通道的 ARN，可以从集成详细信息页面复制该 ARN。的值**--audit-events**是事件对象的 JSON 数组。 `--audit-events`包括来自事件的必需 ID、作为值的事件所需的有效负载`EventData`，以及一个[可选的校验和](#event-data-store-integration-custom-checksum)，以帮助验证事件在摄取后是否完整性。 CloudTrail

   ```
   aws cloudtrail-data put-audit-events \
   --region region \
   --channel-arn $ChannelArn \
   --audit-events \
   id="event_ID",eventData='"{event_payload}"' \
   id="event_ID",eventData='"{event_payload}"',eventDataChecksum="optional_checksum"
   ```

   以下是包含两个事件示例的示例命令。

   ```
   aws cloudtrail-data put-audit-events \
   --region us-east-1 \
   --channel-arn arn:aws:cloudtrail:us-east-1:01234567890:channel/EXAMPLE8-0558-4f7e-a06a-43969EXAMPLE \
   --audit-events \
   id="EXAMPLE3-0f1f-4a85-9664-d50a3EXAMPLE",eventData='"{\"eventVersion\":\0.01\",\"eventSource\":\"custom1.domain.com\", ...
   \}"' \
   id="EXAMPLE7-a999-486d-b241-b33a1EXAMPLE",eventData='"{\"eventVersion\":\0.02\",\"eventSource\":\"custom2.domain.com\", ...
   \}"',eventDataChecksum="EXAMPLE6e7dd61f3ead...93a691d8EXAMPLE"
   ```

   以下示例命令添加了 `--cli-input-json` 参数，以指定事件有效负载的 JSON 文件（`custom-events.json`）。

   ```
   aws cloudtrail-data put-audit-events \
   --channel-arn $channelArn \
   --cli-input-json file://custom-events.json \
   --region us-east-1
   ```

   以下是示例 JSON 文件 `custom-events.json` 的示例内容。

   ```
   {
       "auditEvents": [
         {
           "eventData": "{\"version\":\"eventData.version\",\"UID\":\"UID\",
           \"userIdentity\":{\"type\":\"CustomUserIdentity\",\"principalId\":\"principalId\",
           \"details\":{\"key\":\"value\"}},\"eventTime\":\"2021-10-27T12:13:14Z\",\"eventName\":\"eventName\",
           \"userAgent\":\"userAgent\",\"eventSource\":\"eventSource\",
           \"requestParameters\":{\"key\":\"value\"},\"responseElements\":{\"key\":\"value\"},
           \"additionalEventData\":{\"key\":\"value\"},
           \"sourceIPAddress\":\"source_IP_address\",\"recipientAccountId\":\"recipient_account_ID\"}",
           "id": "1"
         }
      ]
   }
   ```

## （可选）计算校验和值
<a name="event-data-store-integration-custom-checksum"></a>

您在`PutAuditEvents`请求`EventDataChecksum`中指定为的值的校验和可帮助您验证 CloudTrail 收到的事件与校验和匹配的事件；它有助于验证事件的完整性。校验和值是一种 base64-SHA256 算法，您可以通过运行以下命令来计算该算法。

```
printf %s "{"eventData": "{\"version\":\"eventData.version\",\"UID\":\"UID\",
        \"userIdentity\":{\"type\":\"CustomUserIdentity\",\"principalId\":\"principalId\",
        \"details\":{\"key\":\"value\"}},\"eventTime\":\"2021-10-27T12:13:14Z\",\"eventName\":\"eventName\",
        \"userAgent\":\"userAgent\",\"eventSource\":\"eventSource\",
        \"requestParameters\":{\"key\":\"value\"},\"responseElements\":{\"key\":\"value\"},
        \"additionalEventData\":{\"key\":\"value\"},
        \"sourceIPAddress\":\"source_IP_address\",
        \"recipientAccountId\":\"recipient_account_ID\"}",
        "id": "1"}" \
 | openssl dgst -binary -sha256 | base64
```

该命令将返回校验和。示例如下：

```
EXAMPLEHjkI8iehvCUCWTIAbNYkOgO/t0YNw+7rrQE=
```

校验和值将成为您的 `PutAuditEvents` 请求中 `EventDataChecksum` 的值。如果校验和与所提供事件的校验和不匹配，则 CloudTrail 会以错误拒绝该事件。`InvalidChecksum`