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

# AWS 使用 建立從外部記錄事件的整合 AWS CLI
<a name="lake-cli-create-integration"></a>

本節說明如何使用 AWS CLI 建立 CloudTrail Lake 整合，以從 外部記錄事件 AWS。

在 中 AWS CLI，您可以在四個命令中建立整合 （如果您已有符合條件的事件資料存放區，則為三個）。您用作整合目的地的事件資料存放區必須用於單一區域和單一帳戶；它們不能為多區域，他們不能為組織記錄事件 AWS Organizations，並且只能包含活動事件。主控台中的事件類型必須是 **Events from integrations** (來自整合的事件)。在 API 中，`eventCategory` 值必須是 `ActivityAuditLog`。如需有關整合的詳細資訊，請參閱[在 外部建立與事件來源的整合 AWS](query-event-data-store-integration.md)。

1. 如果您還沒有可用於整合的一或多個事件資料存放區，請執行 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudtrail/index.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudtrail/index.html) 以建立事件資料存放區。

   下列範例 AWS CLI 命令會建立事件資料存放區，記錄來自外部的事件 AWS。對於活動事件，`eventCategory` 欄位選取器值為 `ActivityAuditLog`。事件資料存放區的保留期間設定為 90 天。根據預設，事件資料存放區會從所有區域收集事件，但由於這是收集非AWS 事件，請新增 `--no-multi-region-enabled`選項將其設定為單一區域。依預設會啟用終止保護，且事件資料存放區不會針對組織中的帳戶收集事件。

   ```
   aws cloudtrail create-event-data-store \
   --name my-event-data-store \
   --no-multi-region-enabled \
   --retention-period 90 \
   --advanced-event-selectors '[
       {
         "Name": "Select all external events",
         "FieldSelectors": [
             { "Field": "eventCategory", "Equals": ["ActivityAuditLog"] }
           ]
       }
     ]'
   ```

   以下是回應範例。

   ```
   {
       "EventDataStoreArn": "arn:aws:cloudtrail:us-east-1:123456789012:eventdatastore/EXAMPLEf852-4e8f-8bd1-bcf6cEXAMPLE",
       "Name": "my-event-data-store",
       "AdvancedEventSelectors": [
           {
              "Name": "Select all external events",
              "FieldSelectors": [
                 {
                     "Field": "eventCategory",
                     "Equals": [
                         "ActivityAuditLog"
                       ]
                   }
               ]
           }
       ],
       "MultiRegionEnabled": true,
       "OrganizationEnabled": false,
       "BillingMode": "EXTENDABLE_RETENTION_PRICING",
       "RetentionPeriod": 90,
       "TerminationProtectionEnabled": true,
       "CreatedTimestamp": "2023-10-27T10:55:55.384000-04:00",
       "UpdatedTimestamp": "2023-10-27T10:57:05.549000-04:00"
   }
   ```

   您需要事件資料存放區 ID (ARN 的字尾或前面回應範例中的 `EXAMPLEf852-4e8f-8bd1-bcf6cEXAMPLE`)，才能繼續進行下一個步驟並建立通道。

1. 執行 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudtrail/create-channel.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudtrail/create-channel.html) 命令以建立通道，讓合作夥伴或來源應用程式將事件傳送到 CloudTrail 中的事件資料存放區。

   通道具有下列元件：  
**來源**  
CloudTrail 會使用此資訊來判斷代表您將事件資料傳送至 CloudTrail 的合作夥伴。來源是必要元件，可以是 `Custom` (針對所有有效的非AWS 事件)，或合作夥伴事件來源的名稱。每個來源最多可有一個通道。  
如需可用合作夥伴的 `Source` 值的相關資訊，請參閱[整合合作夥伴的其他資訊](query-event-data-store-integration.md#cloudtrail-lake-partner-information)。  
**擷取狀態**  
通道狀態會顯示從通道來源接收到最後一個事件的時間。  
**目的地**  
目的地是從通道接收事件的 CloudTrail Lake 事件資料存放區。您可以變更通道的目的地事件資料存放區。

   若要停止從來源接收事件，請刪除通道。

   您需要至少一個目的地事件資料存放區的 ID，才能執行此命令。目的地的有效類型為 `EVENT_DATA_STORE`。您可以將擷取的事件傳送至多個事件資料存放區。下列範例命令所建立的通道會將事件傳送至兩個事件資料存放區，以它們在 `--destinations` 參數的 `Location` 屬性中的 ID 表示。`--destinations`、`--name` 和 `--source` 是必要參數。若要從 CloudTrail 合作夥伴擷取事件，請將合作夥伴的名稱指定為 `--source` 的值。若要從外部您自己的應用程式擷取事件 AWS，請將 指定`Custom`為 的值`--source`。

   ```
   aws cloudtrail create-channel \
       --region us-east-1 \
       --destinations '[{"Type": "EVENT_DATA_STORE", "Location": "EXAMPLEf852-4e8f-8bd1-bcf6cEXAMPLE"}, {"Type": "EVENT_DATA_STORE", "Location": "EXAMPLEg922-5n2l-3vz1- apqw8EXAMPLE"}]'
       --name my-partner-channel \
       --source $partnerSourceName \
   ```

   在 **create-channel** 命令的回應中，複製新通道的 ARN。您需要 ARN 才能在後續步驟中執行 `put-resource-policy` 和 `put-audit-events` 命令。

1.  執行 **put-resource-policy** 命令，將資源政策連接至通道。資源政策是 JSON 政策文件，這些文件會指出指定的主體可對資源執行哪些動作以及相關條件。在通道的資源政策中定義為主體的帳戶可以呼叫 `PutAuditEvents` API 以傳送事件。
**注意**  
如果您沒有為通道建立資源政策，則只有通道擁有者可以在通道上呼叫 `PutAuditEvents` API。

   政策所需的資訊取決於整合類型。
   + 對於方向整合，CloudTrail 要求政策包含合作夥伴 AWS 的帳戶 IDs，並要求您輸入合作夥伴提供的唯一外部 ID。當您使用 CloudTrail 主控台建立整合時，CloudTrail 會自動將合作夥伴 AWS 的帳戶 IDs 新增至資源政策。請參閱[合作夥伴的文件](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/query-event-data-store-integration.html#cloudtrail-lake-partner-information#lake-integration-partner-documentation)，了解如何取得政策所需的 AWS 帳號。
   + 對於解決方案整合，您必須指定至少一個 AWS 帳戶 ID 作為委託人，並且可以選擇輸入外部 ID 以防止混淆代理人。

   資源政策的需求如下：
   + 政策中定義的資源 ARN 必須與政策所連接的通道 ARN 相符。
   +  政策僅包含一個動作：cloudtrail-data:PutAuditEvents 
   +  政策至少包含一個陳述式。政策最多可以有 20 個陳述式。
   +  每個陳述式至少包含一個主體。陳述式最多可以有 50 個主體。

   ```
   aws cloudtrail put-resource-policy \
       --resource-arn "channelARN" \
       --policy "{
       "Version": "2012-10-17",		 	 	 
       "Statement":
       [
           {
               "Sid": "ChannelPolicy",
               "Effect": "Allow",
               "Principal":
               {
                   "AWS":
                   [
                       "arn:aws:iam::111122223333:root",
                       "arn:aws:iam::444455556666:root",
                       "arn:aws:iam::123456789012:root"
                   ]
               },
               "Action": "cloudtrail-data:PutAuditEvents",
               "Resource": "arn:aws:cloudtrail:us-east-1:777788889999:channel/EXAMPLE-80b5-40a7-ae65-6e099392355b",
               "Condition":
               {
                   "StringEquals":
                   {
                       "cloudtrail:ExternalId": "UniqueExternalIDFromPartner"
                   }
               }
           }
       ]
   }"
   ```

   如需資源政策的詳細資訊，請參閱[AWS CloudTrail 資源型政策範例](security_iam_resource-based-policy-examples.md)。

1. 執行 [https://docs.aws.amazon.com/awscloudtraildata/latest/APIReference/API_PutAuditEvents.html](https://docs.aws.amazon.com/awscloudtraildata/latest/APIReference/API_PutAuditEvents.html) API，將您的活動事件擷取到 CloudTrail 中。您將需要 CloudTrail 要新增的事件承載。將事件擷取到 CloudTrail 之前，請確定事件承載中沒有任何敏感或個人識別資訊。請注意，`PutAuditEvents` API 使用 `cloudtrail-data` CLI 端點，而不是 `cloudtrail` 端點。

   下列範例顯示如何使用 **put-audit-events** CLI 命令。**--audit-events** 和 **--channel-arn** 是必要參數。如果在資源政策中定義了外部 ID，則需要 **--external-id** 參數。您需要在前一步驟中建立的通道 ARN。**--audit-events** 的值為事件物件的 JSON 陣列。`--audit-events` 包含來自事件的必要 ID、必要的事件承載 (作為 `EventData` 的值)，以及[選用總和檢查碼](#lake-cli-integration-checksum.title) (可在擷取至 CloudTrail 後協助驗證事件完整性)。

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

   以下是包含兩個事件範例的範例命令。

   ```
   aws cloudtrail-data put-audit-events \
   --channel-arn arn:aws:cloudtrail:us-east-1:123456789012:channel/EXAMPLE8-0558-4f7e-a06a-43969EXAMPLE \
   --external-id UniqueExternalIDFromPartner \
   --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 --external-id $UniqueExternalIDFromPartner --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\":\"12.34.56.78\",\"recipientAccountId\":\"152089810396\"}",
           "id": "1"
         }
      ]
   }
   ```

您可以執行 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudtrail/get-channel.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudtrail/get-channel.html) 命令，確認整合是否正常運作，以及 CloudTrail 是否正確地從來源擷取事件。**get-channel** 的輸出顯示 CloudTrail 接收到事件的最新時間戳記。

```
aws cloudtrail get-channel --channel arn:aws:cloudtrail:us-east-1:01234567890:channel/EXAMPLE8-0558-4f7e-a06a-43969EXAMPLE
```

## (選用) 計算總和檢查碼值
<a name="lake-cli-integration-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
```

命令會傳回總和檢查碼。下列是 範例。

```
EXAMPLEDHjkI8iehvCUCWTIAbNYkOgO/t0YNw+7rrQE=
```

總和檢查碼值會成為 `PutAuditEvents` 請求中的 `EventDataChecksum` 值。如果總和檢查碼與所提供事件的總和檢查碼不相符，CloudTrail 就會拒絕事件並顯示 `InvalidChecksum` 錯誤。