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

# 使用 AWS IoT 記錄 OTA API 呼叫 AWS CloudTrail
<a name="iot-using-cloudtrail-afr"></a>

FreeRTOS 已與 CloudTrail 整合，這項服務會擷取 AWS IoT OTA API 呼叫，並將日誌檔案交付至您指定的 Amazon S3 儲存貯體。CloudTrail 會擷取從程式碼到 OTA API APIs AWS IoT 呼叫。使用 CloudTrail 所收集的資訊，您可以判斷向 OTA AWS IoT 提出的請求、提出請求的來源 IP 地址、提出請求的人員、提出請求的時間等。

如需 CloudTrail 的相關詳細資訊，包括如何設定與啟用，請參閱[https://docs.aws.amazon.com/awscloudtrail/latest/userguide/](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/)。

## CloudTrail 中的 FreeRTOS 資訊
<a name="aws-iot-info-in-cloudtrail-afr"></a>

當 AWS 您的帳戶中啟用 CloudTrail 記錄時，對 AWS IoT OTA 動作發出的 API 呼叫會在 CloudTrail 日誌檔案中進行追蹤，並在其中與其他 AWS 服務記錄一起寫入。CloudTrail 會根據期間與檔案大小，決定何時建立與寫入新檔案。

CloudTrail 會記錄下列 AWS IoT OTA 控制平面動作：
+ [CreateStream](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateStream.html)
+ [DescribeStream](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeStream.html)
+ [ListStreams](https://docs.aws.amazon.com/iot/latest/apireference/API_ListStreams.html)
+ [UpdateStream](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateStream.html)
+ [DeleteStream](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteStream.html)
+ [CreateOTAUpdate](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateOTAUpdate.html)
+ [GetOTAUpdate](https://docs.aws.amazon.com/iot/latest/apireference/API_GetOTAUpdate.html)
+ [ListOTAUpdates](https://docs.aws.amazon.com/iot/latest/apireference/API_ListOTAUpdates.html)
+ [DeleteOTAUpdate](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteOTAUpdate.html)

**注意**  
AWS IoT CloudTrail 不會記錄 OTA 資料平面動作 （裝置端）。使用 CloudWatch 監控這些項目。

每個日誌項目都會包含產生要求之人員的資訊。日誌記錄中的使用者身分資訊，可協助您判斷下列事項：
+ 該請求是否使用根或 IAM 使用者憑證提出。
+ 提出該請求時，是否使用了特定角色或聯合身分使用者的暫時安全憑證。
+ 請求是否由其他 AWS 服務提出。

如需詳細資訊，請參閱 AWS IoT OTA API 參考中的 [CloudTrail userIdentity Element](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html).OTA 動作。 [AWS IoT](https://docs.aws.amazon.com/iot/latest/apireference)

您可以視需要將日誌檔案存放在 Amazon S3 儲存貯體中，但您也可以定義 Amazon S3 生命週期規則來自動封存或刪除日誌檔案。您的日誌檔案預設使用 Amazon S3 伺服器端加密 (SSE) 加密。

如果您想要在日誌檔案交付時收到通知，您可以設定 CloudTrail 來發佈 Amazon SNS 通知。如需詳細資訊，請參閱[設定 CloudTrail 的 Amazon SNS 通知](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/getting_notifications_top_level.html)。

您也可以將多個 AWS 區域和多個 AWS 帳戶的 AWS IoT OTA 日誌檔案彙總到單一 Amazon S3 儲存貯體。

如需詳細資訊，請參閱[從多個區域接收 CloudTrail 日誌檔案](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-receive-logs-from-multiple-accounts.html)和[從多個帳戶接收 CloudTrail 日誌檔案](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-receive-logs-from-multiple-accounts.html)。

## 了解 FreeRTOS 日誌檔案項目
<a name="understanding-aws-iot-entries-afr"></a>

CloudTrail 日誌檔案可以包含一或多個日誌項目。每一項目均列出多個 JSON 格式的事件。一個日誌項目為任何來源提出的單一請求，並包含請求動作、請求的日期和時間、請求參數等資訊。日誌項目並非公有 API 呼叫的有序堆疊追蹤，因此不會以任何特定順序顯示。

下列範例顯示 CloudTrail 日誌項目，示範從呼叫 `CreateOTAUpdate`動作的日誌。

```
{
    "eventVersion": "1.05",
    "userIdentity": {
        "type": "IAMUser",
        "principalId": "EXAMPLE",
        "arn": "arn:aws:iam::{{your_aws_account}}:user/{{your_user_id}}",
        "accountId": "{{your_aws_account}}",
        "accessKeyId": "{{your_access_key_id}}",
        "userName": "{{your_username}}",
        "sessionContext": {
            "attributes": {
                "mfaAuthenticated": "false",
                "creationDate": "2018-08-23T17:27:08Z"
            }
        },
        "invokedBy": "apigateway.amazonaws.com"
    },
    "eventTime": "2018-08-23T17:27:19Z",
    "eventSource": "iot.amazonaws.com",
    "eventName": "CreateOTAUpdate",
    "awsRegion": "{{your_aws_region}}",
    "sourceIPAddress": "apigateway.amazonaws.com",
    "userAgent": "apigateway.amazonaws.com",
    "requestParameters": {
        "targets": [
            "arn:aws:iot:{{your_aws_region}}:{{your_aws_account}}:thing/Thing_CMH"
        ],
        "roleArn": "arn:aws:iam::{{your_aws_account}}:role/Role_FreeRTOSJob",
        "files": [
            {
                "fileName": "/sys/mcuflashimg.bin",
                "fileSource": {
                    "fileId": 0,
                    "streamId": "{{your_stream_id}}"
                },
                "codeSigning": {
                    "awsSignerJobId": "{{your_signer_job_id}}"
                }
            }
        ],
        "targetSelection": "SNAPSHOT",
        "otaUpdateId": "FreeRTOSJob_CMH-23-1535045232806-92"
    },
    "responseElements": {
        "otaUpdateArn": "arn:aws:iot:{{your_aws_region}}:{{your_aws_account}}:otaupdate/FreeRTOSJob_CMH-23-1535045232806-92",
        "otaUpdateStatus": "CREATE_PENDING",
        "otaUpdateId": "FreeRTOSJob_CMH-23-1535045232806-92"
    },
    "requestID": "c9649630-a6f9-11e8-8f9c-e1cf2d0c9d8e",
    "eventID": "ce9bf4d9-5770-4cee-acf4-0e5649b845c0",
    "eventType": "AwsApiCall",
    "recipientAccountId": "{{recipient_aws_account}}"
}
```