本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 实施 AWS.DiscoverDevices 操作
设备发现会将最终用户拥有的物理设备列表与托管集成中维护的最终用户设备的数字表示形式保持一致。 AWS IoT Device Management它由 AWS 客户在最终用户拥有的设备上执行。对于 OAuth 2.0，这种情况发生在账户关联完成之后。对于一般授权，这可能发生在创建账户关联之后。
设备发现是一个异步过程，其中托管集成 AWS IoT Device Management 调用连接器来启动设备发现请求。C2C 连接器异步返回已发现的最终用户设备列表，其中包含托管集成为生成的参考标识符（称为`deviceDiscoveryId`）。 AWS IoT Device Management
下图说明了最终用户与托管集成之间的设备发现工作流程： AWS IoT Device Management
1. **客户启动设备发现**-客户代表最终用户启动设备发现流程。
1. **托管集成生成参考 ID**-托管集成，用于 AWS IoT Device Management 生成一个参考标识符，该标识符调`deviceDiscoveryId`用客户生成的设备发现请求。 AWS
1. **设备发现请求已发送**-的托管集成使用`AWS.DiscoverDevices`操作界面向 C2C 连接器 AWS IoT Device Management 发送设备发现请求，包括授权信息（OAuth 访问令牌或 AWS Secrets Manager 引用）以及. `deviceDiscoveryId`
1. **连接器存储设备 DiscoveryId**-您的连接器存储`deviceDiscoveryId`以包含在`DEVICE_DISCOVERY`活动中。此事件还将包含已发现的最终用户设备的列表，并且必须发送到托管集成，才能将 `SendConnectorEvent` API 作为`DEVICE_DISCOVERY`事件发送。 AWS IoT Device Management
1. **连接器调用资源服务器**-您的 C2C 连接器应调用资源服务器以获取最终用户拥有的所有设备。
1. **连接器以 ACK 响应**-您的 C2C 连接器 Lambda 响应 Lambda 调用 `invokeFunction` ()，向托管集成的 ACK 响应作为操作 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” 的操作参数通过 Sigv4 调用 AWS IoT Device Management API 的托管集成。`SendConnectorEvent`发送到托管集成的设备列表中的每台设备都 AWS IoT Device Management 将由设备特定的参数表示`connectorDeviceId`，例如`connectorDeviceName`、和 a。`capabilityReport`
+ 根据您的资源服务器响应，您需要 AWS IoT Device Management 相应地通知托管集成。
+ 例如，如果您的资源服务器为最终用户对已发现的设备列表进行了分页响应，则可以为每次轮询发送一个单独的`DEVICE_DISCOVERY`操作事件，`statusCode`参数为。`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 连接器可以使用用于注册连接器的凭据通过 Sigv4 调用 AWS IoT Device Management API 的 AWS 账户 托管集成。
**步骤 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`参数是一个可选筛选器，允许您指定要发现的设备 ID 列表。如果为空 (`[]`)，则会发现与该账户关联的所有设备。填充特定的设备 ID 后，发现响应中将仅包含这些设备。
**一般授权请求：**
```
/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`参数是一个可选筛选器，允许您指定要发现的设备 ID 列表。如果为空 (`[]`)，则会发现与该账户关联的所有设备。填充特定的设备 ID 后，发现响应中将仅包含这些设备。
**一般授权申请：**
```
/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`参数是一个可选筛选器，允许您指定要发现的设备 ID 列表。如果为空 (`[]`)，则会发现与该账户关联的所有设备。填充特定的设备 ID 后，发现响应中将仅包含这些设备。
**步骤 2：连接器确认发现**
连接器发送带有以下 JSON 响应的确认：
```
{
"header": {
"responseCode":200
},
"payload": {
"responseMessage": "Discovering devices for discovery-job-id '12345678' with connector-id `Your-Connector-Id`"
}
}
```
**步骤 3：连接器发送设备发现事件**
使用以下 JSON 负载`/connector-event/{{{your_connector_id}}}`向发送 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\_D CapabilityReport EVICES 事件构造一个
如上面定义的事件结构所示，在 DISCOVER\_DEVICES 事件中报告的每台设备作为对`AWS.DiscoverDevices`操作的响应，都需要 CapbilityReport 来描述相应设备的功能。`CapabilityReport`以符合 Matter 的格式表示 AWS IoT Device Management 设备功能的托管集成。
+ `nodeId`，字符串：包含以下内容的设备节点的标识符 `endpoints`
+ `version`，String：此设备节点的版本，由连接器开发者设置
+ `endpoints`，列表：此设备端点支持的案件数据模型 AWS 实现列表。
+ `id`，字符串：连接器开发者设置的端点标识符
+ `deviceTypes`，列表：此端点捕获的设备类型列表，即 “摄像头”。
+ `clusters`，列表：此端点支持的物质数据模型的 AWS 实现列表。
+ `id`，字符串：Matter 标准定义的集群标识符。
+ `revision`，整数：Matter 标准定义的聚类修订号。
+ `attributes`， 地图：属性标识符及其对应的当前设备状态值的映射，标识符和有效值由问题标准定义。
+ `id`，字符串：案件数据模型的 AWS 实现所定义的属性 ID。
+ `value`，对象：由属性 ID 定义的属性的当前值。“值” 的类型可以根据属性而变化。该`value`字段对于每个属性都是可选的，只有当您的连接器 lambda 可以在发现期间确定当前状态时，才应包含该字段。
+ `commands`，列表：按照 Matter 标准的定义，此集群支持的命令 ID 列表。
+ `events`，列表：根据 Matter 标准的定义，此集群支持的事件 ID 列表。
有关[物质数据模型支持的功能及其相应AWS 实现的](matter-data-model.md)当前列表，请参阅最新版本的数据模型文档。