本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 建立與 主控台的自訂整合
<a name="query-event-data-store-integration-custom"></a>

您可以使用 CloudTrail 來記錄和儲存來自混合環境中任何來源 (例如在內部部署或雲端、虛擬機器或容器中託管的內部或 SaaS 應用程式) 的使用者活動資料。在 CloudTrail Lake 主控台中執行此程序的前半部分，然後呼叫 [https://docs.aws.amazon.com/awscloudtraildata/latest/APIReference/API_PutAuditEvents.html](https://docs.aws.amazon.com/awscloudtraildata/latest/APIReference/API_PutAuditEvents.html) API 以擷取事件，並提供您的通道 ARN 和事件承載。使用 `PutAuditEvents` API 將應用程式活動擷取到 CloudTrail 之後，您可以使用 CloudTrail Lake 來搜尋、查詢和分析從應用程式記錄的資料。

1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/cloudtrail/](https://console.aws.amazon.com/cloudtrail/) 開啟 CloudTrail 主控台。

1.  在導覽窗格中，選擇 **Lake** 下方的**整合**。

1. 在 **Add integration** (新增整合) 頁面上，輸入通道的名稱。名稱長度範圍是 3-128 個字元。只能使用字母、數字、句號、底線和破折號。

1. 選擇 **My custom integration** (我的自訂整合)。

1. 在 **Event delivery location** (事件傳送位置) 中，選擇將相同的活動事件記錄到現有事件資料存放區，或建立新的事件資料存放區。

   如果您選擇建立新的事件資料存放區，請輸入事件資料存放區的名稱，並指定保留期間 (以天為單位)。如果您選擇**一年可延長保留定價**選項，則可將事件資料保留在事件資料存放區中最多 3,653 天 (約 10 年)；如果您選擇**七年保留定價**選項，則最多可保留 2,557 天 (約 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. 選擇**新增 AWS 帳戶**以指定要在頻道的資源政策中新增為主體的每個 AWS 帳戶 ID。

1. (選用) 在 **Tags** (標籤) 區域中，您最多可以新增 50 個標籤索引鍵和值組，以協助您識別、排序和控制對事件資料存放區及通道的存取權限。如需使用 IAM 政策，對以標籤為基礎的事件資料存放區授與存取權限的詳細資訊，請參閱[範例：拒絕以標籤為基礎建立或刪除事件資料存放區的存取權限](security_iam_id-based-policy-examples.md#security_iam_id-based-policy-examples-eds-tags)。如需如何在 中使用標籤的詳細資訊 AWS，請參閱《》中的[標記您的 AWS 資源](https://docs.aws.amazon.com/tag-editor/latest/userguide/tagging.html)*AWS 一般參考*。

1. 當您準備好建立新整合時，請選擇 **Add integration** (新增整合)。沒有檢閱頁面。CloudTrail 會建立整合，但若要整合您的自訂事件，您必須在 [https://docs.aws.amazon.com/awscloudtraildata/latest/APIReference/API_PutAuditEvents.html](https://docs.aws.amazon.com/awscloudtraildata/latest/APIReference/API_PutAuditEvents.html) 請求中指定通道 ARN。

1. 呼叫 `PutAuditEvents` API，將您的活動事件擷取到 CloudTrail 中。每個 `PutAuditEvents` 請求最多可供新增 100 個活動事件 (或最多 1 MB 大小)。您需要在先前步驟中建立的通道 ARN、希望 CloudTrail 新增的事件承載，以及外部 ID (如有為您的資源政策指定)。將事件擷取到 CloudTrail 之前，請確定事件承載中沒有任何敏感或個人識別資訊。您擷取到 CloudTrail 中的事件必須遵循 [CloudTrail Lake 整合事件結構描述](query-integration-event-schema.md)。
**提示**  
使用 [AWS CloudShell](https://docs.aws.amazon.com/cloudshell/latest/userguide/welcome.html) 以確保您執行的是最新的 AWS APIs。

   下列範例顯示如何使用 **put-audit-events** CLI 命令。**--audit-events** 和 **--channel-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` 錯誤。