實作 AWS.DiscoverDevices 操作 - 的受管整合 AWS IoT Device Management
裝置探索的 C2C 連接器需求裝置探索程序建構CapabilityReport

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

實作 AWS.DiscoverDevices 操作

裝置探索會將最終使用者擁有的實體裝置清單與 AWS IoT Device Management 受管整合中維護的那些最終使用者裝置的數位表示法保持一致。只有在使用者與 AWS IoT Device Management 的受管整合之間完成帳戶連結之後， AWS 客戶才會在最終使用者擁有的裝置上執行。裝置探索是一種非同步程序，其中 AWS IoT Device Management 的受管整合會呼叫連接器來啟動裝置探索請求。C2C 連接器會傳回由受管整合產生的與參考識別碼 （稱為 deviceDiscoveryId) 非同步的探索最終使用者裝置清單。

下圖說明最終使用者與 AWS IoT Device Management 受管整合之間的裝置探索工作流程：

AWS.DiscoverDevices 工作流程
AWS.DiscoverDevices 工作流程

  1. 客戶代表最終使用者啟動裝置探索程序。

  2. 的受管整合會deviceDiscoveryId針對客戶產生的裝置探索請求 AWS IoT Device Management 產生名為 的 AWS 參考識別符。

  3. 的受管整合會使用 AWS.DiscoverDevices操作介面將裝置探索請求 AWS IoT Device Management 傳送至 C2C 連接器，包括accessToken最終使用者的有效 OAuth 以及 deviceDiscoveryId。

  4. 您的連接器存放deviceDiscoveryId區要包含在DEVICE_DISCOVERY事件中。此事件也會包含探索到的最終使用者裝置清單，而且必須以DEVICE_DISCOVERY事件SendConnectorEvent形式傳送至 AWS IoT Device Management 的受管整合。

  5. 您的 C2C 連接器應呼叫資源伺服器，以擷取最終使用者擁有的所有裝置。

  6. 您的 C2C 連接器 Lambda 會使用 ACK 回應來回應 Lambda 呼叫 (invokeFunction)，以傳回 AWS IoT Device Management 的受管整合，做為AWS.DiscoverDevices操作的初始回應。受管整合會通知客戶其已啟動裝置探索程序的 ACK。

  7. 您的資源伺服器會將最終使用者擁有和操作的裝置清單傳送給您。

  8. 連接器會將每個最終使用者裝置轉換為 AWS IoT Device Management 所需裝置格式的受管整合，包括每個裝置的 ConnectorDeviceIdConnectorDeviceName和 功能報告。

  9. C2C 連接器也UserId提供探索的裝置擁有者。視您的資源伺服器實作而定，它可能會在裝置清單或個別通話中從您的資源伺服器擷取。

  10. 接著，您的 C2C 連接器將使用 AWS 帳戶 登入資料和操作參數設定為 "DEVICE_DISCOVERY"SendConnectorEvent，透過 SigV4 呼叫 AWS IoT Device Management API 的受管整合。傳送至 AWS IoT Device Management 受管整合之裝置清單中的每個裝置都會以裝置特定參數表示connectorDeviceName，例如 connectorDeviceId、 和 capabilityReport。

    1. 根據您的資源伺服器回應，您需要相應地通知 AWS IoT Device Management 的受管整合。

      例如，如果您的資源伺服器對最終使用者的探索裝置清單具有分頁回應，則對於每個輪詢，您可以使用 statusCode 參數 傳送個別DEVICE_DISCOVERY操作事件3xx。如果您的裝置探索仍在進行中，請重複步驟 5、6 和 7。

  11. 的受管整合 AWS IoT Device Management 會將發現最終使用者裝置的通知傳送給客戶。

  12. 如果您的 C2C 連接器傳送DEVICE_DISCOVERY操作事件，並將 statusCode 參數更新為 200，則受管整合會通知客戶裝置探索工作流程完成。

    重要

    如有需要，步驟 7 到 11 可以在步驟 6 之前進行。例如，如果您的第三方平台具有 API 來列出最終使用者裝置，則可以在 C2C 連接器 Lambda 回應一般 ACK SendConnectorEvent之前，使用 傳送 DEVICE_DISCOVERY 事件。

裝置探索的 C2C 連接器需求

以下清單概述 C2C 連接器的要求，以促進成功的裝置探索。

  • C2C 連接器 Lambda 可以處理來自 AWS IoT Device Management 受管整合的裝置探索請求訊息，並處理AWS.DiscoverDevices操作。

  • 您的 C2C 連接器可以使用 AWS 帳戶 用於註冊連接器的 憑證，透過 SigV4 呼叫 AWS IoT Device Management APIs 的受管整合。

裝置探索程序

下列步驟概述使用 C2C 連接器的裝置探索程序，以及 AWS IoT Device Management 的受管整合。

裝置探索程序

  1. 受管整合會觸發裝置探索：

    1. DiscoverDevices 使用下列 JSON 承載將 POST 請求傳送至 ：

      /DiscoverDevices
{
   "header": {
        "auth": {                 
            "token": "ashriu32yr97feqy7afsaf",  
            "type": "OAuth2.0"
        }
   },
   "payload": {
        "operationName": "AWS.DiscoverDevices",
        "operationVersion": "1.0",
        "connectorId": "Your-Connector-Id",
        "deviceDiscoveryId": "12345678"
   }
}

  2. 連接器認可探索：

    1. 連接器會傳送包含下列 JSON 回應的確認：

      {
     "header": {
          "responseCode":200
     },
     "payload": {
          "responseMessage": "Discovering devices for discovery-job-id '12345678' with connector-id `Your-Connector-Id`"
     }
}

  3. 連接器會傳送裝置探索事件：

    1. /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"]
 				}]
 			}]
 		} 
        }
    ]
}

建構 DISCOVER_DEVICES 事件的 CapabilityReport

如上述定義的事件結構所示，DISCOVER_DEVICES 事件中報告的每個裝置，做為對 AWS.DiscoverDevices操作的回應，都需要 CapbilityReport 來描述對應的裝置功能。`CapabilityReport` 會以符合事項的格式告知 AWS IoT Device Management 裝置功能的受管整合。下列欄位必須在 ` CapabilityReport ` 中提供：

  • nodeId、字串：包含下列項目之裝置節點的識別符 endpoints

  • version、字串：此裝置節點的版本，由連接器開發人員設定

  • endpoints、List<Cluster>：此裝置端點支援的事項資料模型 AWS 實作清單。

    • id、字串：連接器開發人員設定的端點識別符

    • deviceTypes，List<String>：此端點擷取的裝置類型清單，即 "Camera"。

    • clusters、List<Cluster>：此端點支援的事項資料模型 AWS 實作清單。

      • id、字串：依事項標準定義的叢集識別符。

      • revision、整數：Matter 標準所定義的叢集修訂編號。

      • attributes、Map<String、Object>：屬性識別符及其對應目前裝置狀態值的映射，具有 事件標準定義的識別符和有效值。

        • id、字串： 主題資料模型 AWS 實作所定義的屬性 ID。

        • value、物件：屬性 ID 所定義之屬性的目前值。'value' 的類型可能會根據 屬性而變更。每個屬性的 value 欄位都是選用的，只有在連接器 Lambda 可以在探索期間判斷目前狀態時，才應包含此欄位。

      • commands、List<String>：依事項標準所定義，支援此叢集的命令 IDs 清單。

      • events、List<String>：依事項標準所定義，支援此叢集的事件 IDs 清單。

如需支援的 功能及其對應AWS 實作的最新清單，請參閱 Data Model 文件的最新版本。