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

# 實作 AWS.DiscoverDevices 操作
<a name="discover-devices-op"></a>

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

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

![\[AWS.DiscoverDevices 工作流程\]](http://docs.aws.amazon.com/zh_tw/iot-mi/latest/devguide/images/device-discovery-workflow.png)


**AWS.DiscoverDevices 工作流程**

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

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

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

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

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

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

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

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

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

1. 接著，您的 C2C 連接器將使用 AWS 帳戶 登入資料和操作參數設定為 "DEVICE\$1DISCOVERY"`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。

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

1. 如果您的 C2C 連接器傳送`DEVICE_DISCOVERY`操作事件，並將 `statusCode` 參數更新為 200，則受管整合會通知客戶裝置探索工作流程完成。
**重要**  
如有需要，步驟 7 到 11 可以在步驟 6 之前進行。例如，如果您的第三方平台具有 API 來列出最終使用者裝置，則可以在 C2C 連接器 Lambda 回應一般 ACK `SendConnectorEvent`之前，使用 傳送 DEVICE\$1DISCOVERY 事件。

## 裝置探索的 C2C 連接器需求
<a name="connector-device-discovery-requirements"></a>

以下清單概述 C2C 連接器的要求，以促進成功的裝置探索。
+ C2C 連接器 Lambda 可以處理來自 AWS IoT Device Management 受管整合的裝置探索請求訊息，並處理`AWS.DiscoverDevices`操作。
+ 您的 C2C 連接器可以使用 AWS 帳戶 用於註冊連接器的 憑證，透過 SigV4 呼叫 AWS IoT Device Management APIs 的受管整合。

## 裝置探索程序
<a name="device-discovery-process"></a>

下列步驟概述使用 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"
        }
     }
     ```

1. 連接器認可探索：

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

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

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

   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\$1DEVICES 事件建構CapabilityReport
<a name="capability-report-discover-devices"></a>

如上述定義的事件結構所示，做為 `AWS.DiscoverDevices`操作回應的 DISCOVER\$1DEVICES 事件中所報告的每個裝置，都需要 CapbilityReport 來描述對應的裝置功能。`CapabilityReport` 會以符合事項的格式告知 AWS IoT Device Management 裝置功能的受管整合。下列欄位必須在 ` CapabilityReport ` 中提供：
+ `nodeId`、字串：包含下列項目之裝置節點的識別符 `endpoints`
+ `version`、字串：此裝置節點的版本，由連接器開發人員設定
+ `endpoints`、List<Cluster>：此裝置端點支援的事項資料模型 AWS 實作清單。
  + `id`、字串：連接器開發人員設定的端點識別符
  + `deviceTypes`、List<String>：此端點擷取的裝置類型清單，即「攝影機」。
  + `clusters`、List<Cluster>：此端點支援的事項資料模型 AWS 實作清單。
    + `id`、字串：依事項標準定義的叢集識別符。
    + `revision`、整數：依事項標準定義的叢集修訂編號。
    + `attributes`、Map<String、Object>：屬性識別符及其對應目前裝置狀態值的映射，具有 事件標準定義的識別符和有效值。
      + `id`、字串：Matter Data Model AWS 實作定義的屬性 ID。
      + `value`、物件：屬性 ID 所定義之屬性的目前值。'value' 的類型可能會根據 屬性而變更。每個屬性的 `value` 欄位都是選用的，只有在連接器 Lambda 可以在探索期間判斷目前狀態時才應包含。
    + `commands`，List<String>：依事項標準所定義，支援此叢集的命令 IDs 清單。
    + `events`、List<String>：依事項標準所定義，支援此叢集的事件 IDs 清單。

如需目前支援的功能清單及其對應的[AWS 事項資料模型實作，](matter-data-model.md)請參閱最新版本的資料模型文件。