本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 事件訊息 本節包含更新或變更物件或任務 AWS IoT 時， 發佈的訊息相關資訊。如需可讓您建立偵測器以監控裝置操作失敗或變更，以及在發生時觸發動作 AWS IoT Events 的服務相關資訊，請參閱 [AWS IoT Events](https://aws.amazon.com/iot-events)。 ## 如何產生事件訊息 AWS IoT 會在發生特定事件時發佈事件訊息。例如，在新增、更新或刪除事物時，由登錄檔產生的事件。每個事件都會觸發傳送一則事件訊息。事件訊息會透過具 JSON 承載的 MQTT 發佈。承載內容取決於事件的類型。 **注意** 事件訊息保證會發佈一次。事件訊息也有可能發佈超過一次。事件訊息的順序無法保證。 ### 接收事件訊息的政策 若要接收事件訊息，您的裝置必須使用適當的政策，允許它連線到 AWS IoT 裝置閘道並訂閱 MQTT 事件主題。您也必須訂閱合適的主題篩選條件。 以下為接收生命週期事件所需的政策範例： **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Subscribe", "iot:Receive" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:/$aws/events/*" ] } ] } ``` ## 啟用 的事件 AWS IoT 在預留主題的訂閱者可以接收訊息之前，您必須從 或使用 API AWS 管理主控台 或 CLI 啟用事件訊息。如需不同選項管理的事件訊息資訊，請參閱[AWS IoT 事件組態設定表](#iot-events-settings-table)。 + 若要啟用事件訊息，請前往 AWS IoT 主控台[的設定](https://console.aws.amazon.com//iot/home#/settings)索引標籤，然後在**事件型訊息**區段中選擇**管理事件**。您可以指定要管理的事件。 + 若要透過使用 API 或 CLI 來控制要發佈的事件類型，請呼叫 [UpdateEventConfigurations](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateEventConfigurations.html) API 或使用 **update-event-configurations** CLI 命令。例如： ``` aws iot update-event-configurations --event-configurations "{\"THING\":{\"Enabled\": true}}" ``` **注意** 所有引號 (") 都會與反斜線 (\$1) 一起逸出。 您可以透過呼叫 [DescribeEventConfigurations](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeEventConfigurations.html) API 或使用 **describe-event-configurations** CLI 命令來取得目前的事件設定。例如： ``` aws iot describe-event-configurations ``` ** AWS IoT 事件組態設定資料表** | 事件類別 (AWS IoT 主控台：設定：事件型訊息） | `eventConfigurations` 金鑰值 (AWS CLI/API) | 事件訊息主題 | | --- | --- | --- | | *(只能使用 AWS CLI/API 進行設定)* | `CA_CERTIFICATE` | `$aws/events/certificates/registered/caCertificateId` | | *(只能使用 AWS CLI/API 進行設定)* | `CERTIFICATE` | `$aws/events/presence/connected/clientId` | | *(只能使用 AWS CLI/API 進行設定)* | `CERTIFICATE` | `$aws/events/presence/disconnected/clientId` | | *(只能使用 AWS CLI/API 進行設定)* | `CERTIFICATE` | `$aws/events/subscriptions/subscribed/clientId` | | *(只能使用 AWS CLI/API 進行設定)* | `CERTIFICATE` | `$aws/events/subscriptions/unsubscribed/clientId` | | 任務完成，取消 | `JOB` | `$aws/events/job/jobID/canceled` | | 任務完成，取消 | `JOB` | `$aws/events/job/jobID/cancellation_in_progress` | | 任務完成，取消 | `JOB` | `$aws/events/job/jobID/completed` | | 任務完成，取消 | `JOB` | `$aws/events/job/jobID/deleted` | | 任務完成，取消 | `JOB` | `$aws/events/job/jobID/deletion_in_progress` | | 任務執行：成功、失敗、拒絕、取消、移除 | `JOB_EXECUTION` | `$aws/events/jobExecution/jobID/canceled` | | 任務執行：成功、失敗、拒絕、取消、移除 | `JOB_EXECUTION` | `$aws/events/jobExecution/jobID/deleted` | | 任務執行：成功、失敗、拒絕、取消、移除 | `JOB_EXECUTION` | `$aws/events/jobExecution/jobID/failed` | | 任務執行：成功、失敗、拒絕、取消、移除 | `JOB_EXECUTION` | `$aws/events/jobExecution/jobID/rejected` | | 任務執行：成功、失敗、拒絕、取消、移除 | `JOB_EXECUTION` | `$aws/events/jobExecution/jobID/removed` | | 任務執行：成功、失敗、拒絕、取消、移除 | `JOB_EXECUTION` | `$aws/events/jobExecution/jobID/succeeded` | | 任務執行：成功、失敗、拒絕、取消、移除 | `JOB_EXECUTION` | `$aws/events/jobExecution/jobID/timed_out` | | 物件：建立，更新，刪除 | `THING` | `$aws/events/thing/thingName/created` | | 物件：建立，更新，刪除 | `THING` | `$aws/events/thing/thingName/updated` | | 物件：建立，更新，刪除 | `THING` | `$aws/events/thing/thingName/deleted` | | 物件群組：新增、移除 | `THING_GROUP` | `$aws/events/thingGroup/thingGroupName/created` | | 物件群組：新增、移除 | `THING_GROUP` | `$aws/events/thingGroup/thingGroupName/updated` | | 物件群組：新增、移除 | `THING_GROUP` | `$aws/events/thingGroup/thingGroupName/deleted` | | 物件群組階層：新增、移除 | `THING_GROUP_HIERARCHY` | `$aws/events/thingGroupHierarchy/thingGroup/parentThingGroupName/childThingGroup/childThingGroupName/added` | | 物件群組階層：新增、移除 | `THING_GROUP_HIERARCHY` | `$aws/events/thingGroupHierarchy/thingGroup/parentThingGroupName/childThingGroup/childThingGroupName/removed` | | 物件群組成員資格：新增、移除 | `THING_GROUP_MEMBERSHIP` | `$aws/events/thingGroupMembership/thingGroup/thingGroupName/thing/thingName/added` | | 物件群組成員資格：新增、移除 | `THING_GROUP_MEMBERSHIP` | `$aws/events/thingGroupMembership/thingGroup/thingGroupName/thing/thingName/removed` | | 物件類型：建立、更新、刪除 | `THING_TYPE` | `$aws/events/thingType/thingTypeName/created` | | 物件類型：建立、更新、刪除 | `THING_TYPE` | `$aws/events/thingType/thingTypeName/updated` | | 物件類型：建立、更新、刪除 | `THING_TYPE` | `$aws/events/thingType/thingTypeName/deleted` | | 物件類型關聯：新增、移除 | `THING_TYPE_ASSOCIATION` | `$aws/events/thingTypeAssociation/thing/thingName/thingType/thingTypeName/added` `$aws/events/thingTypeAssociation/thing/thingName/thingType/thingTypeName/removed` | # 登錄檔事件 該登錄檔可能會在建立、更新或刪除物件、物件類型和物件群組時發佈事件訊息。不過，這些事件預設為無法使用。如需如何開啟這些事件的詳細資訊，請參閱 [啟用 的事件 AWS IoT](iot-events.md#iot-events-enable)。 **Topics** + [物件事件](#registry-events-thing) + [物件類型事件](#registry-events-thingtype) + [物件群組事件](#registry-events-thinggroup) ## 物件事件 **建立/更新/刪除的物件** 該登錄檔會在建立、更新或刪除事物時發佈以下事件訊息： + `$aws/events/thing/thingName/created` + `$aws/events/thing/thingName/updated` + `$aws/events/thing/thingName/deleted` 訊息包含的承載範例如下： ``` { "eventType" : "THING_EVENT", "eventId" : "f5ae9b94-8b8e-4d8e-8c8f-b3266dd89853", "timestamp" : 1234567890123, "operation" : "CREATED|UPDATED|DELETED", "accountId" : "123456789012", "thingId" : "b604f69c-aa9a-4d4a-829e-c480e958a0b5", "thingName" : "MyThing", "versionNumber" : 1, "thingTypeName" : null, "attributes": { "attribute3": "value3", "attribute1": "value1", "attribute2": "value2" } } ``` 承載包含以下屬性： eventType 設定為「THING\$1EVENT」。 eventId 獨特的事件 ID (字串)。 timestamp 事件發生時的 UNIX 時間戳記。 operation 觸發事件的操作。有效的值如下： + CREATED (已建立) + UPDATED (已更新) + DELETED accountId 您的 AWS 帳戶 ID。 thingId 建立、更新或刪除的物件之 ID。 thingName 建立、更新或刪除的物件之名稱。 versionNumber 建立、更新或刪除的物件之版本。物件建立時，此值設定為 1。物件更新時，此值會增加 1。 thingTypeName 與物件關聯的物件類型 (若存在)。否則為 `null`。 屬性 與物件關聯的名稱/值對之集合。 ## 物件類型事件 **Topics** + [物件類型Created/Updated/Deprecated/Undeprecated/Deleted](#registry-events-thingtype-crud) + [關聯事物類型或取消關聯事物](#registry-events-thingtype-assoc) ### 物件類型Created/Updated/Deprecated/Undeprecated/Deleted 當物件類型建立、更新、棄用、取消棄用或刪除時，登錄檔會發佈下列事件訊息： + `$aws/events/thingType/thingTypeName/created` + `$aws/events/thingType/thingTypeName/updated` + `$aws/events/thingType/thingTypeName/deleted` 訊息包含的承載範例如下： ``` { "eventType" : "THING_TYPE_EVENT", "eventId" : "8827376c-4b05-49a3-9b3b-733729df7ed5", "timestamp" : 1234567890123, "operation" : "CREATED|UPDATED|DELETED", "accountId" : "123456789012", "thingTypeId" : "c530ae83-32aa-4592-94d3-da29879d1aac", "thingTypeName" : "MyThingType", "isDeprecated" : false|true, "deprecationDate" : null, "searchableAttributes" : [ "attribute1", "attribute2", "attribute3" ], "propagatingAttributes": [ { "userPropertyKey": "key", "thingAttribute": "model" }, { "userPropertyKey": "key", "connectionAttribute": "iot:ClientId" } ], "description" : "My thing type" } ``` 承載包含以下屬性： eventType 設定為「THING\$1TYPE\$1EVENT」。 eventId 獨特的事件 ID (字串)。 timestamp 事件發生時的 UNIX 時間戳記。 operation 觸發事件的操作。有效的值如下： + CREATED (已建立) + UPDATED (已更新) + DELETED accountId 您的 AWS 帳戶 ID。 thingTypeId 正在建立、更新、棄用或刪除的物件類型的 ID。 thingTypeName 正在建立、更新、棄用或刪除的物件類型名稱。 isDeprecated 如果指定物件類型已棄用，則為 `true`。否則為 `false`。 deprecationDate 棄用物件類型的 UNIX 時間戳記。 searchableAttributes 與可用於搜尋的物件類型關聯之名稱/值對集合。 propagatingAttributes 傳播屬性的清單。傳播屬性可以包含物件屬性、連線屬性和使用者屬性金鑰。如需詳細資訊，請參閱[新增訊息擴充的傳播屬性](https://docs.aws.amazon.com//iot/latest/developerguide/thing-types-propagating-attributes.html)。 description 物件類型描述。 ### 關聯事物類型或取消關聯事物 當事物類型與事物關聯或取消關聯時，登錄檔會發佈以下事件訊息。 + `$aws/events/thingTypeAssociation/thing/thingName/thingType/typeName/added` + `$aws/events/thingTypeAssociation/thing/thingName/thingType/typeName/removed` 以下是 `added` 承載的範例。`removed` 訊息的承載類似。 ``` { "eventId" : "87f8e095-531c-47b3-aab5-5171364d138d", "eventType" : "THING_TYPE_ASSOCIATION_EVENT", "operation" : "ADDED", "thingId" : "b604f69c-aa9a-4d4a-829e-c480e958a0b5", "thingName": "myThing", "thingTypeName" : "MyThingType", "timestamp" : 1234567890123, } ``` 承載包含以下屬性： eventId 獨特的事件 ID (字串)。 eventType 設定為 "THING\$1TYPE\$1ASSOCIATION\$1EVENT"。 operation 觸發事件的操作。有效的值如下： + ADDED + REMOVED thingId 類型關聯已變更的物件 ID。 thingName 類型關聯已變更的物件名稱。 thingTypeName 與物件相關聯或不再相關聯的物件類型。 timestamp 事件發生時的 UNIX 時間戳記。 ## 物件群組事件 **Topics** + [建立/更新/刪除物件群組](#registry-events-thinggroup-crud) + [從事物群組新增或移除的事物](#registry-events-thinggroup-addremove) + [從事物群組新增或移除的事物群組](#registry-events-thinggroup-adddelete) ### 建立/更新/刪除物件群組 登錄檔會在建立、更新或刪除事物群組時發佈以下事件訊息。 + `$aws/events/thingGroup/groupName/created` + `$aws/events/thingGroup/groupName/updated` + `$aws/events/thingGroup/groupName/deleted` 以下是 `updated` 承載的範例。`created` 和 `deleted` 訊息的承載類似。 ``` { "eventType": "THING_GROUP_EVENT", "eventId": "8b9ea8626aeaa1e42100f3f32b975899", "timestamp": 1603995417409, "operation": "UPDATED", "accountId": "571EXAMPLE833", "thingGroupId": "8757eec8-bb37-4cca-a6fa-403b003d139f", "thingGroupName": "Tg_level5", "versionNumber": 3, "parentGroupName": "Tg_level4", "parentGroupId": "5fce366a-7875-4c0e-870b-79d8d1dce119", "description": "New description for Tg_level5", "rootToParentThingGroups": [ { "groupArn": "arn:aws:iot:us-west-2:571EXAMPLE833:thinggroup/TgTopLevel", "groupId": "36aa0482-f80d-4e13-9bff-1c0a75c055f6" }, { "groupArn": "arn:aws:iot:us-west-2:571EXAMPLE833:thinggroup/Tg_level1", "groupId": "bc1643e1-5a85-4eac-b45a-92509cbe2a77" }, { "groupArn": "arn:aws:iot:us-west-2:571EXAMPLE833:thinggroup/Tg_level2", "groupId": "0476f3d2-9beb-48bb-ae2c-ea8bd6458158" }, { "groupArn": "arn:aws:iot:us-west-2:571EXAMPLE833:thinggroup/Tg_level3", "groupId": "1d9d4ffe-a6b0-48d6-9de6-2e54d1eae78f" }, { "groupArn": "arn:aws:iot:us-west-2:571EXAMPLE833:thinggroup/Tg_level4", "groupId": "5fce366a-7875-4c0e-870b-79d8d1dce119" } ], "attributes": { "attribute1": "value1", "attribute3": "value3", "attribute2": "value2" }, "dynamicGroupMappingId": null } ``` 承載包含以下屬性： eventType 設定為「THING\$1GROUP\$1EVENT」。 eventId 獨特的事件 ID (字串)。 timestamp 事件發生時的 UNIX 時間戳記。 operation 觸發事件的操作。有效的值如下： + CREATED (已建立) + UPDATED (已更新) + DELETED accountId 您的 AWS 帳戶 ID。 thingGroupId 建立、更新或刪除的物件群組之 ID。 thingGroupName 建立、更新或刪除的物件群組之名稱。 versionNumber 物件群組版本。物件群組建立時，此值設定為 1。物件群組更新時，此值會增加 1。 parentGroupName 父事物群組名稱 (若有的話)。 parentGroupId 父事物群組 ID (若有的話)。 description 物件群組描述。 rootToParentThingGroups 關於父物件群組的一系列資訊。每個父物件群組都有一個元素，從根物件群組開始，一直到物件群組的父項。每個項目都包含物件群組的 `groupArn` 和 `groupId`。 屬性 與物件群組關聯的名稱/值對之集合。 ### 從事物群組新增或移除的事物 該登錄檔會在事物新增至事物群組，或從事物群組移除時發佈以下事件訊息。 + `$aws/events/thingGroupMembership/thingGroup/thingGroupName/thing/thingName/added` + `$aws/events/thingGroupMembership/thingGroup/thingGroupName/thing/thingName/removed` 訊息包含的承載範例如下： ``` { "eventType" : "THING_GROUP_MEMBERSHIP_EVENT", "eventId" : "d684bd5f-6f6e-48e1-950c-766ac7f02fd1", "timestamp" : 1234567890123, "operation" : "ADDED|REMOVED", "accountId" : "123456789012", "groupArn" : "arn:aws:iot:ap-northeast-2:123456789012:thinggroup/MyChildThingGroup", "groupId" : "06838589-373f-4312-b1f2-53f2192291c4", "thingArn" : "arn:aws:iot:ap-northeast-2:123456789012:thing/MyThing", "thingId" : "b604f69c-aa9a-4d4a-829e-c480e958a0b5", "membershipId" : "8505ebf8-4d32-4286-80e9-c23a4a16bbd8" } ``` 承載包含以下屬性： eventType 設定為「THING\$1GROUP\$1MEMBERSHIP\$1EVENT」。 eventId 事件 ID。 timestamp 事件發生時的 UNIX 時間戳記。 operation 當物件新增到物件群組時，`ADDED`。當物件從物件群組移除時，`REMOVED`。 accountId 您的 AWS 帳戶 ID。 groupArn 物件群組的 ARN。 groupId 群組的 ID。 thingArn 物件群組新增或移除之物件的 ARN。 thingId 物件群組新增或移除之物件的 ID。 membershipId 代表物件和物件群組之間關係的 ID。當您在物件群組新增物件，就會產生此值。 ### 從事物群組新增或移除的事物群組 當一個事物群組新增至另一個事物群組，或從另一個事物群組中移除事物群組時，登錄檔都會發佈以下事件訊息。 + `$aws/events/thingGroupHierarchy/thingGroup/parentThingGroupName/childThingGroup/childThingGroupName/added` + `$aws/events/thingGroupHierarchy/thingGroup/parentThingGroupName/childThingGroup/childThingGroupName/removed` 訊息包含的承載範例如下： ``` { "eventType" : "THING_GROUP_HIERARCHY_EVENT", "eventId" : "264192c7-b573-46ef-ab7b-489fcd47da41", "timestamp" : 1234567890123, "operation" : "ADDED|REMOVED", "accountId" : "123456789012", "thingGroupId" : "8f82a106-6b1d-4331-8984-a84db5f6f8cb", "thingGroupName" : "MyRootThingGroup", "childGroupId" : "06838589-373f-4312-b1f2-53f2192291c4", "childGroupName" : "MyChildThingGroup" } ``` 承載包含以下屬性： eventType 設定為「THING\$1GROUP\$1HIERARCHY\$1EVENT」。 eventId 事件 ID。 timestamp 事件發生時的 UNIX 時間戳記。 operation 當物件新增到物件群組時，`ADDED`。當物件從物件群組移除時，`REMOVED`。 accountId 您的 AWS 帳戶 ID。 thingGroupId 父物件群組的 ID。 thingGroupName 父物件群組的名稱。 childGroupId 子物件群組的 ID。 childGroupName 子物件群組的名稱。 # 任務事件 當 AWS IoT 任務待定、完成或取消，以及當裝置在執行任務時回報成功或失敗時，任務服務會發佈至 MQTT 通訊協定上的預留主題。藉由訂閱這些主題，裝置或管理及監控應用程式就能夠追蹤任務的狀態。 **如何啟用任務事件** 來自 AWS IoT Jobs 服務的回應訊息不會透過訊息代理程式傳遞，也無法由其他用戶端或規則訂閱。若要訂閱任務活動相關的訊息，請使用 `notify` 和 `notify-next` 主題。如需任務主題的詳細資訊，請參閱 [任務主題](reserved-topics.md#reserved-topics-job)。 若要收到任務更新的通知，請使用 AWS 管理主控台或使用 API 或 CLI 來啟用這些任務事件。如需詳細資訊，請參閱[啟用 的事件 AWS IoT](iot-events.md#iot-events-enable)。 **任務事件的運作方式** 由於取消和刪除任務可能需要一些時間，系統會傳送兩個訊息來表示請求開始和結束。例如，當取消請求開始時，系統會將訊息傳送到 `$aws/events/job/jobID/cancellation_in_progress` 主題。當取消請求完成時，系統會將訊息傳送到 `$aws/events/job/jobID/canceled` 主題。 任務刪除請求的程序亦同。管理及監控應用程式可以藉由訂閱這些主題，以追蹤任務的狀態。如需發佈與訂閱 MQTT 主題的詳細資訊，請參閱 [裝置通訊協定](protocols.md)。 **任務事件類型** 下列範例顯示不同類型的任務事件： **完成/取消/刪除的任務** 當任務完成、取消、刪除或正在取消或刪除時， AWS IoT 任務服務會在 MQTT 主題上發佈訊息： + `$aws/events/job/jobID/completed` + `$aws/events/job/jobID/canceled` + `$aws/events/job/jobID/deleted` + `$aws/events/job/jobID/cancellation_in_progress` + `$aws/events/job/jobID/deletion_in_progress` `completed` 訊息包含的承載範例如下： ``` { "eventType": "JOB", "eventId": "7364ffd1-8b65-4824-85d5-6c14686c97c6", "timestamp": 1234567890, "operation": "completed", "jobId": "27450507-bf6f-4012-92af-bb8a1c8c4484", "status": "COMPLETED", "targetSelection": "SNAPSHOT|CONTINUOUS", "targets": [ "arn:aws:iot:us-east-1:123456789012:thing/a39f6f91-70cf-4bd2-a381-9c66df1a80d0", "arn:aws:iot:us-east-1:123456789012:thinggroup/2fc4c0a4-6e45-4525-a238-0fe8d3dd21bb" ], "description": "My Job Description", "completedAt": 1234567890123, "createdAt": 1234567890123, "lastUpdatedAt": 1234567890123, "jobProcessDetails": { "numberOfCanceledThings": 0, "numberOfRejectedThings": 0, "numberOfFailedThings": 0, "numberOfRemovedThings": 0, "numberOfSucceededThings": 3 } } ``` `canceled` 訊息包含的承載範例如下。 ``` { "eventType": "JOB", "eventId": "568d2ade-2e9c-46e6-a115-18afa1286b06", "timestamp": 1234567890, "operation": "canceled", "jobId": "4d2a531a-da2e-47bb-8b9e-ff5adcd53ef0", "status": "CANCELED", "targetSelection": "SNAPSHOT|CONTINUOUS", "targets": [ "arn:aws:iot:us-east-1:123456789012:thing/Thing0-947b9c0c-ff10-4a80-b4b3-cd33d0145a0f", "arn:aws:iot:us-east-1:123456789012:thinggroup/ThingGroup1-95c644d5-1621-41a6-9aa5-ad2de581d18f" ], "description": "My job description", "createdAt": 1234567890123, "lastUpdatedAt": 1234567890123 } ``` `deleted` 訊息包含的承載範例如下。 ``` { "eventType": "JOB", "eventId": "568d2ade-2e9c-46e6-a115-18afa1286b06", "timestamp": 1234567890, "operation": "deleted", "jobId": "4d2a531a-da2e-47bb-8b9e-ff5adcd53ef0", "status": "DELETED", "targetSelection": "SNAPSHOT|CONTINUOUS", "targets": [ "arn:aws:iot:us-east-1:123456789012:thing/Thing0-947b9c0c-ff10-4a80-b4b3-cd33d0145a0f", "arn:aws:iot:us-east-1:123456789012:thinggroup/ThingGroup1-95c644d5-1621-41a6-9aa5-ad2de581d18f" ], "description": "My job description", "createdAt": 1234567890123, "lastUpdatedAt": 1234567890123, "comment": "Comment for this operation" } ``` `cancellation_in_progress` 訊息包含的承載範例如下： ``` { "eventType": "JOB", "eventId": "568d2ade-2e9c-46e6-a115-18afa1286b06", "timestamp": 1234567890, "operation": "cancellation_in_progress", "jobId": "4d2a531a-da2e-47bb-8b9e-ff5adcd53ef0", "status": "CANCELLATION_IN_PROGRESS", "targetSelection": "SNAPSHOT|CONTINUOUS", "targets": [ "arn:aws:iot:us-east-1:123456789012:thing/Thing0-947b9c0c-ff10-4a80-b4b3-cd33d0145a0f", "arn:aws:iot:us-east-1:123456789012:thinggroup/ThingGroup1-95c644d5-1621-41a6-9aa5-ad2de581d18f" ], "description": "My job description", "createdAt": 1234567890123, "lastUpdatedAt": 1234567890123, "comment": "Comment for this operation" } ``` `deletion_in_progress` 訊息包含的承載範例如下： ``` { "eventType": "JOB", "eventId": "568d2ade-2e9c-46e6-a115-18afa1286b06", "timestamp": 1234567890, "operation": "deletion_in_progress", "jobId": "4d2a531a-da2e-47bb-8b9e-ff5adcd53ef0", "status": "DELETION_IN_PROGRESS", "targetSelection": "SNAPSHOT|CONTINUOUS", "targets": [ "arn:aws:iot:us-east-1:123456789012:thing/Thing0-947b9c0c-ff10-4a80-b4b3-cd33d0145a0f", "arn:aws:iot:us-east-1:123456789012:thinggroup/ThingGroup1-95c644d5-1621-41a6-9aa5-ad2de581d18f" ], "description": "My job description", "createdAt": 1234567890123, "lastUpdatedAt": 1234567890123, "comment": "Comment for this operation" } ``` **任務執行結束狀態** 當裝置將任務執行更新為終端機狀態時， AWS IoT 任務服務會發佈訊息： + `$aws/events/jobExecution/jobID/succeeded` + `$aws/events/jobExecution/jobID/failed` + `$aws/events/jobExecution/jobID/rejected` + `$aws/events/jobExecution/jobID/canceled` + `$aws/events/jobExecution/jobID/timed_out` + `$aws/events/jobExecution/jobID/removed` + `$aws/events/jobExecution/jobID/deleted` 訊息包含的承載範例如下： ``` { "eventType": "JOB_EXECUTION", "eventId": "cca89fa5-8a7f-4ced-8c20-5e653afb3572", "timestamp": 1234567890, "operation": "succeeded|failed|rejected|canceled|removed|timed_out", "jobId": "154b39e5-60b0-48a4-9b73-f6f8dd032d27", "thingArn": "arn:aws:iot:us-east-1:123456789012:myThing/6d639fbc-8f85-4a90-924d-a2867f8366a7", "status": "SUCCEEDED|FAILED|REJECTED|CANCELED|REMOVED|TIMED_OUT", "statusDetails": { "key": "value" } } ``` # 命令執行事件 AWS IoT 當命令執行變更狀態時， 會將事件訊息發佈至 MQTT 主題。您可以使用這些事件來監控命令執行進度，並建置可回應狀態變更的應用程式。 **命令執行事件主題** 命令執行事件會發佈至下列 MQTT 主題： ``` $aws/events/commandExecution/commandId/status ``` 其中： + `commandId` 是 命令的識別符。 + `status` 是命令執行的狀態。有效值為：`CREATED`、`IN_PROGRESS`、`SUCCEEDED`、`FAILED`、`REJECTED`、`TIMED_OUT`。 若要接收所有命令和所有狀態的通知，請使用萬用字元訂閱下列主題： ``` $aws/events/commandExecution/+/# ``` **命令執行事件訊息** 當命令執行狀態變更時， 會將事件訊息 AWS IoT 發佈至對應的 MQTT 主題。訊息包含的承載範例如下： ``` { "executionId": "2bd65c51-4cfd-49e4-9310-d5cbfdbc8554", "status": "FAILED", "statusReason": { "reasonCode": "DEVICE_TOO_BUSY", "reasonDescription": "" }, "eventType": "COMMAND_EXECUTION", "commandArn": "arn:aws:iot:us-east-1:123456789012:command/0b9d9ddf-e873-43a9-8e2c-9fe004a90086", "targetArn": "arn:aws:iot:us-east-1:123456789012:thing/5006c3fc-de96-4def-8427-7eee36c6f2bd", "timestamp": 1717708862107 } ``` 承載包含以下屬性： **executionId** 命令執行的唯一識別符 （字串）。 **status** 命令執行的狀態。有效值為：`CREATED`、`IN_PROGRESS`、`SUCCEEDED`、`FAILED`、`REJECTED`、`TIMED_OUT`。 **statusReason** 如果可用，則包含狀態額外資訊的物件。包含 `reasonCode`和 `reasonDescription` 欄位。 **eventType** 設定為 "COMMAND\$1EXECUTION"。 **commandArn** 命令的 Amazon Resource Name (ARN)。 **targetArn** 命令執行的目標裝置 （物件或用戶端） 的 ARN。 **timestamp** 事件發生時的 UNIX 時間戳記。 # 生命週期事件 AWS IoT 可以在 MQTT 主題上發佈生命週期事件。預設情況下，這些事件可用且無法停用。 **注意** 生命週期的訊息可能不會按照順序傳送。您可能會收到重複的訊息。 `thingName` 只有在用戶端使用[獨家物件](exclusive-thing.md)功能連線時，才會包含 。 **Topics** + [連線/中斷連線事件](#connect-disconnect) + [連線嘗試失敗事件](#connect-authfailure-event) + [訂閱/取消訂閱事件](#subscribe-unsubscribe-events) ## 連線/中斷連線事件 **注意** 使用 AWS IoT Device Management 機群索引，您可以搜尋物件、執行彙總查詢，並根據物件連線/中斷連線事件建立動態群組。如需詳細資訊，請參閱[機群索引](https://docs.aws.amazon.com//iot/latest/developerguide/iot-indexing.html)。 AWS IoT 當用戶端連線或中斷連線時， 會將訊息發佈至下列 MQTT 主題： + `$aws/events/presence/connected/clientId`：用戶端已連接到訊息代理程式。 + `$aws/events/presence/disconnected/clientId`：用戶端已與訊息代理程式中斷連線。 以下為發佈至 `$aws/events/presence/connected/clientId` 主題之連線/中斷連線訊息所包含的 JSON 元素。 **clientId** 連線或中斷連線之用戶端的用戶端 ID。 包含 \$1 或 \$1 的用戶端 ID 不會收到生命週期事件。 **thingName** 您的 IoT 物件名稱。只有在用戶端使用[獨佔物件](exclusive-thing.md)功能進行連線時，`thingName`才會包含 。 **clientInitiatedDisconnect** 如果用戶端已啟動中斷連線，則為 True。否則為 false。僅在中斷連線訊息中發現。 **disconnectReason** 用戶端中斷連線的原因。僅在中斷連線訊息中發現。下表包含有效值，以及代理程式是否會在連線中斷時傳送 [Last Will and Testament (LWT) 訊息](mqtt.md#mqtt-lwt)。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot/latest/developerguide/life-cycle-events.html) 1如果裝置在收到此錯誤之前有作用中的連線。 2若要防止 Last Will and Testament (LWT) 訊息，請將 `preventWillMessage=true` 設定為覆寫 `DeleteConnection` API 的預設 LWT 傳送行為。 **eventType** 事件的類型。有效值為 `connected` 或 `disconnected`。 **ipAddress** 連線用戶端的 IP 地址。這可以是 IPv4 或 IPv6 格式。僅在連線訊息中發現。 **principalIdentifier** 用於身分驗證的憑證。對於 TLS 交互身分驗證憑證，此為憑證 ID。對於其他連線，此為 IAM 憑證。 **sessionIdentifier** 在工作階段生命週期內 AWS IoT 存在於 中的全域唯一識別符。 **timestamp** 事件發生的約略時間。 **versionNumber** 生命週期事件的版本號碼。這是每個用戶端 ID 連線的依序遞增長整數值。訂閱者戶可以使用版本號碼來推斷生命週期事件的順序。 用戶端連線的連線和中斷連線訊息具有相同的版本號碼。 版本號碼可能會略過值，並且每個事件並不保證會以 1 為值持續增加。 如果用戶端約一小時未連線，則版本號碼將重設為 0。若為持久工作階段，當用戶端中斷連線時間超過為持久工作階段所設的存留時間 (TTL) 後，版本號碼將重設為 0。 連線訊息具有以下結構。 ``` { "clientId": "186b5", "thingName": "exampleThing", "timestamp": 1573002230757, "eventType": "connected", "sessionIdentifier": "00000000-0000-0000-0000-000000000000", "principalIdentifier": "12345678901234567890123456789012", "ipAddress": "192.0.2.0", "versionNumber": 0 } ``` 中斷連線訊息具有以下結構。 ``` { "clientId": "186b5", "thingName": "exampleThing", "timestamp": 1573002340451, "eventType": "disconnected", "sessionIdentifier": "00000000-0000-0000-0000-000000000000", "principalIdentifier": "12345678901234567890123456789012", "clientInitiatedDisconnect": true, "disconnectReason": "CLIENT_INITIATED_DISCONNECT", "versionNumber": 0 } ``` ### 處理用戶端中斷連線 最佳實務是一律為生命週期事件實作等待狀態，包括 [Last Will and Testament (LWT) 訊息](mqtt.md)。收到中斷連線的訊息時，您的程式碼會等待一段時間並驗證裝置是否仍然離線，才採取動作。使用 [SQS 延遲佇列](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-delay-queues.html)是執行此操作的其中一種方法。當用戶端收到 LWT 或生命週期事件時，您可以將訊息加入佇列 (例如，5 秒鐘)。當該訊息變為可用並由 Lambda 或其他服務進行處理時，您可以在進行下一個動作前，先檢查該裝置是否仍處於離線狀態。 ## 連線嘗試失敗事件 AWS IoT 當用戶端未獲授權進行連線或設定最後一個遺囑和見證，且用戶端未獲授權發佈至最後一個遺囑主題時， 會將訊息發佈至下列 MQTT 主題。 ``` $aws/events/presence/connect_failed/clientId ``` 以下是發佈至`$aws/events/presence/connect_failed/clientId`主題的連線授權訊息中包含的 JSON 元素清單。 **clientId** 嘗試且無法連線之用戶端的用戶端 ID。 包含 \$1 或 \$1 的用戶端 ID 不會收到生命週期事件。 **thingName** 您的 IoT 物件名稱。只有在用戶端使用[獨家物件](exclusive-thing.md)功能進行連線時，`thingName`才會包含 。 **timestamp** 事件發生的約略時間。 **eventType** 事件的類型。有效值為 `connect_failed`。 **connectFailureReason** 連線失敗的原因。有效值為 `AUTHORIZATION_FAILED`。 **principalIdentifier** 用於身分驗證的憑證。對於 TLS 交互身分驗證憑證，此為憑證 ID。對於其他連線，此為 IAM 憑證。 **sessionIdentifier** 在工作階段生命週期內 AWS IoT 存在於 中的全域唯一識別符。 **ipAddress** 連線用戶端的 IP 地址。這可以是 IPv4 或 IPv6 格式。僅在連線訊息中發現。 連線失敗訊息具有下列結構。 ``` { "clientId": "186b5", "thingName": "exampleThing", "timestamp": 1460065214626, "eventType": "connect_failed", "connectFailureReason": "AUTHORIZATION_FAILED", "principalIdentifier": "12345678901234567890123456789012", "sessionIdentifier": "00000000-0000-0000-0000-000000000000", "ipAddress" : "192.0.2.0" } ``` ## 訂閱/取消訂閱事件 AWS IoT 當用戶端訂閱或取消訂閱 MQTT 主題時， 會將訊息發佈至下列 MQTT 主題： ``` $aws/events/subscriptions/subscribed/clientId ``` 或 ``` $aws/events/subscriptions/unsubscribed/clientId ``` 其中 `clientId` 是連線至 AWS IoT 訊息代理程式的 MQTT 用戶端 ID。 發佈至此主題的訊息具有以下結構： ``` { "clientId": "186b5", "thingName": "exampleThing", "timestamp": 1460065214626, "eventType": "subscribed" | "unsubscribed", "sessionIdentifier": "00000000-0000-0000-0000-000000000000", "principalIdentifier": "12345678901234567890123456789012", "topics" : ["foo/bar","device/data","dog/cat"] } ``` 以下為發佈至 `$aws/events/subscriptions/subscribed/clientId` 和 `$aws/events/subscriptions/unsubscribed/clientId` 主題之訂閱與取消訂閱訊息所包含的 JSON 元素。 clientId 訂閱或取消訂閱之用戶端的用戶端 ID。 包含 \$1 或 \$1 的用戶端 ID 不會收到生命週期事件。 thingName 您的 IoT 物件名稱。只有在用戶端使用[獨家物件](exclusive-thing.md)功能進行連線時，`thingName`才會包含 。 eventType 事件的類型。有效值為 `subscribed` 或 `unsubscribed`。 principalIdentifier 用於身分驗證的憑證。對於 TLS 交互身分驗證憑證，此為憑證 ID。對於其他連線，此為 IAM 憑證。 sessionIdentifier 在工作階段生命週期內 AWS IoT 存在於 中的全域唯一識別符。 timestamp 事件發生的約略時間。 topics 用戶端已訂閱的一系列 MQTT 主題。 **注意** 生命週期的訊息可能不會按照順序傳送。您可能會收到重複的訊息。