本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 實作 AWS.DiscoverDevices 操作 裝置探索會將最終使用者擁有的實體裝置清單與 Managed Integrations 中維護的那些最終使用者裝置的數位表示法保持一致 AWS IoT Device Management。它由 AWS 客戶在最終使用者擁有的裝置上執行。對於 OAuth 2.0，這會在帳戶連結完成後發生。對於一般授權，這可能會在建立帳戶關聯之後發生。 裝置探索是一種非同步程序，其中 的 AWS IoT Device Management 受管整合會呼叫連接器來啟動裝置探索請求。C2C 連接器會傳回受管整合針對 產生的參考識別符 （稱為 `deviceDiscoveryId`)，以非同步方式傳回探索到的最終使用者裝置清單 AWS IoT Device Management。 下圖說明最終使用者與 受管整合之間的裝置探索工作流程 AWS IoT Device Management： ![AWS.DiscoverDevices 工作流程](https://docs.aws.amazon.com/zh_tw/iot-mi/latest/devguide/images/device-discovery-workflow.png) 1. **客戶啟動裝置探索** - 客戶代表最終使用者啟動裝置探索程序。 1. **受管整合會產生參考 ID** - 的 受管整合 AWS IoT Device Management 會產生名為 的 AWS 參考識別符，`deviceDiscoveryId`用於客戶產生的裝置探索請求。 1. **已傳送裝置探索請求** - 的受管整合會使用 `AWS.DiscoverDevices`操作介面將裝置探索請求 AWS IoT Device Management 傳送至 C2C 連接器，包括授權資訊 (OAuth 存取權杖或 AWS Secrets Manager 參考） 以及 `deviceDiscoveryId`。 1. **連接器存放 deviceDiscoveryId** - `deviceDiscoveryId`要包含在`DEVICE_DISCOVERY`事件中的連接器存放區。此事件也會包含已探索的最終使用者裝置清單，而且必須以 `SendConnectorEvent` API 做為`DEVICE_DISCOVERY`事件傳送至 AWS IoT Device Management 的 受管整合。 1. **連接器呼叫資源伺服器** - 您的 C2C 連接器應呼叫資源伺服器，以擷取最終使用者擁有的所有裝置。 1. **連接器以 ACK 回應** - 您的 C2C 連接器 Lambda 以 ACK 回應 Lambda 呼叫 (`invokeFunction`) 傳回受管整合 AWS IoT Device Management，做為`AWS.DiscoverDevices`操作的初始回應。的受管整合會透過 ACK AWS IoT Device Management 通知客戶其啟動的裝置探索程序。 1. **資源伺服器會傳回裝置清單** - 您的資源伺服器會將最終使用者擁有和操作的裝置清單傳送給您。 1. **轉換裝置格式** - 連接器會將每個最終使用者裝置轉換為 AWS IoT Device Management 所需的裝置格式的受管整合，包括每個裝置的 `ConnectorDeviceId``ConnectorDeviceName`和 功能報告。 1. **提供 UserId** - C2C 連接器也提供`UserId`探索的裝置擁有者。視您的資源伺服器實作而定，它可能會在裝置清單或個別通話中從資源伺服器擷取。 1. **呼叫 SendConnectorEvent API** - 接著，您的 C2C 連接器將使用 AWS 帳戶 登入資料和操作參數設定為 "DEVICE\_DISCOVERY"`SendConnectorEvent`，透過 SigV4 呼叫 AWS IoT Device Management API 的受管整合 。傳送至 Managed Integrations for 的裝置清單中的每個裝置 AWS IoT Device Management 都會以裝置特定的參數表示`connectorDeviceName`，例如 `connectorDeviceId`、 和 `capabilityReport`。 + 根據您的資源伺服器回應，您需要相應地通知 的 AWS IoT Device Management 受管整合。 + 例如，如果您的資源伺服器對最終使用者探索的裝置清單有分頁回應，則對於每個輪詢，您可以使用 `statusCode` 參數 傳送個別`DEVICE_DISCOVERY`操作事件`3xx`。如果您的裝置探索仍在進行中，請重複步驟 5、6 和 7。 1. **受管整合會通知客戶** - 的 受管整合會 AWS IoT Device Management 向客戶傳送有關發現最終使用者裝置的通知。 1. **完成通知** - 如果您的 C2C 連接器傳送`DEVICE_DISCOVERY`操作事件，並將 `statusCode` 參數更新為 200，則 AWS IoT Device Management 的受管整合將通知客戶裝置探索工作流程完成。 **重要** 如有需要，步驟 7 到 11 可以在步驟 6 之前進行。例如，如果您的第三方平台具有可列出最終使用者裝置的 API，則可以在 C2C 連接器 Lambda 回應一般 ACK `SendConnectorEvent`之前，使用 傳送 DEVICE\_DISCOVERY 事件。 下列清單概述 C2C 連接器的要求，以促進裝置探索成功： + C2C 連接器 Lambda 可以處理來自 受管整合的裝置探索請求訊息， AWS IoT Device Management 並處理 `AWS.DiscoverDevices`操作。 + 您的 C2C 連接器可以使用 AWS 帳戶 用於註冊連接器的 憑證，透過 SigV4 呼叫 Managed Integrations AWS IoT Device Management APIs。 **步驟 1：受管整合觸發裝置探索** 根據授權類型，`DiscoverDevices`使用下列其中一個 JSON 承載將 POST 請求傳送至 ： **OAuth 2.0 請求：** ``` /DiscoverDevices { "header": { "auth": { "token": "ashriu32yr97feqy7afsaf", "type": "OAuth2.0" } }, "payload": { "operationName": "AWS.DiscoverDevices", "operationVersion": "1.0", "connectorId": "{{Your-Connector-Id}}", "deviceDiscoveryId": "12345678", "connectorDeviceIdList": [] } } ``` **注意** `connectorDeviceIdList` 參數是選用的篩選條件，可讓您指定要探索的裝置 IDs 清單。當空白 (`[]`) 時，將探索與帳戶相關聯的所有裝置。填入特定裝置 IDs 時，探索回應中只會包含這些裝置。 **一般授權請求：** ``` /DiscoverDevices { "header": { "auth": { "secretsManager": { "arn": "string", "versionId": "string" }, "type": "GeneralAuthorization" } }, "payload": { "operationName": "AWS.DiscoverDevices", "operationVersion": "1.0", "connectorId": "{{Your-Connector-Id}}", "deviceDiscoveryId": "12345678", "connectorDeviceIdList": [] } } ``` **注意** `connectorDeviceIdList` 參數是選用的篩選條件，可讓您指定要探索的裝置 IDs 清單。當空白 (`[]`) 時，將探索與帳戶相關聯的所有裝置。填入特定裝置 IDs 時，探索回應中只會包含這些裝置。 **一般授權請求：** ``` /DiscoverDevices { "header": { "auth": { "secretsManager": { "arn": "string", "versionId": "string" }, "type": "GeneralAuthorization" } }, "payload": { "operationName": "AWS.DiscoverDevices", "operationVersion": "1.0", "connectorId": "{{Your-Connector-Id}}", "deviceDiscoveryId": "12345678", "connectorDeviceIdList": [] } } ``` **注意** `connectorDeviceIdList` 參數是選用的篩選條件，可讓您指定要探索的裝置 IDs 清單。當空白 (`[]`) 時，將探索與帳戶相關聯的所有裝置。填入特定裝置 IDs 時，探索回應中只會包含這些裝置。 **步驟 2：連接器確認探索** 連接器會傳送包含下列 JSON 回應的確認： ``` { "header": { "responseCode":200 }, "payload": { "responseMessage": "Discovering devices for discovery-job-id '12345678' with connector-id `Your-Connector-Id`" } } ``` **步驟 3：連接器傳送裝置探索事件** `/connector-event/{{{your_connector_id}}}` 使用下列 JSON 承載將 POST 請求傳送至 ： ``` AWS API - /SendConnectorEvent URI – POST /connector-event/{your_connector_id} { "UserId": "6109342", "Operation": "DEVICE_DISCOVERY", "OperationVersion": "1.0", "StatusCode": 200, "DeviceDiscoveryId": "12345678", "ConnectorId": "Your_connector_Id", "Message": "Device discovery for discovery-job-id '12345678' successful", "Devices": [ { "ConnectorDeviceId": "Your_Device_Id_1", "ConnectorDeviceName": "Your-Device-Name", "CapabilityReport": { "nodeId":"1", "version":"1.0.0", "endpoints":[{ "id":"1", "deviceTypes":["Camera"], "clusters":[{ "id":"0x0006", "revision":1, "attributes":[{ "id":"0x0000", }], "commands":["0x00","0x01"], "events":["0x00"] }] }] } } ] } ``` ## 為探索的裝置填入品牌和模型 您的 C2C 連接器可以選擇性地在`DEVICE_DISCOVERY`事件中包含每個裝置的`DeviceMetadata`物件，以報告裝置的品牌和模型。這些值接著會在 [ListDiscoveredDevices](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_ListDiscoveredDevices.html#API_ListDiscoveredDevices_ResponseSyntax) 和 [ListManagedThings](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_ListManagedThings.html#API_ListManagedThings_ResponseSyntax) 回應中傳回。 在每個裝置項目和映射中包含`DeviceMetadata`物件： + `DeviceMetadata.Brand` （字串） → `Brand` + `DeviceMetadata.Model` （字串） → `Model` 下列範例顯示`DeviceMetadata`包含 的裝置項目： ``` { "ConnectorDeviceId": "Your_Device_Id_1", "ConnectorDeviceName": "Your-Device-Name", "CapabilityReport": { ... }, "DeviceMetadata": { "Brand": "ExampleBrand", "Model": "ExampleModel-X1" } } ``` 這兩個索引鍵都是區分大小寫的字串。如果您省略 `DeviceMetadata`、省略個別索引鍵，或提供非字串值，則擷取裝置時無法使用對應的欄位。 ## 為 DISCOVER\_DEVICES 事件建構CapabilityReport 如上述定義的事件結構所示，做為 `AWS.DiscoverDevices`操作回應的 DISCOVER\_DEVICES 事件中所報告的每個裝置，都需要 CapbilityReport 來描述對應的裝置功能。`CapabilityReport` 會以符合事項的格式告知 AWS IoT Device Management 裝置功能的受管整合。 + `nodeId`、字串：包含下列項目之裝置節點的識別符 `endpoints` + `version`、字串：此裝置節點的版本，由連接器開發人員設定 + `endpoints`、List：此裝置端點支援的事項資料模型 AWS 實作清單。 + `id`、字串：連接器開發人員設定的端點識別符 + `deviceTypes`，List：此端點擷取的裝置類型清單，即 "Camera"。 + `clusters`、List：此端點支援的事項資料模型 AWS 實作清單。 + `id`、字串：依事項標準定義的叢集識別符。 + `revision`、整數：Matter 標準所定義的叢集修訂編號。 + `attributes`、Map：屬性識別符及其對應目前裝置狀態值的映射，具有 事件標準定義的識別符和有效值。 + `id`、字串： 主題資料模型 AWS 實作所定義的屬性 ID。 + `value`、物件：屬性 ID 所定義之屬性的目前值。'value' 的類型可能會根據 屬性而變更。每個屬性的 `value` 欄位都是選用的，只有在連接器 Lambda 可以在探索期間判斷目前狀態時，才應包含此欄位。 + `commands`，List：依事項標準所定義，支援此叢集的命令 IDs 清單。 + `events`、List：依事項標準所定義，支援此叢集的事件 IDs 清單。 如需支援的 功能及其對應[AWS 實作的最新清單，](matter-data-model.md)請參閱 Data Model 文件的最新版本。