翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# AWS.DiscoverDevices オペレーションを実装する
デバイス検出は、エンドユーザーが所有する物理デバイスのリストを、 Managed Integrations for で管理されているエンドユーザーデバイスのデジタル表現に合わせます AWS IoT Device Management。これは、エンドユーザーが所有するデバイスで AWS 顧客が実行します。OAuth 2.0 の場合、これはアカウントのリンクが完了した後に発生します。一般認可の場合、これはアカウントの関連付けの作成後に発生する可能性があります。
デバイス検出は、 の AWS IoT Device Management Managed Integrations がコネクタを呼び出してデバイス検出リクエストを開始する非同期プロセスです。C2C コネクタは、Managed Integrations によって生成された参照識別子 ( と呼ばれる`deviceDiscoveryId`) を使用して、検出されたエンドユーザーデバイスのリストを非同期的に返します AWS IoT Device Management。
次の図は、エンドユーザーと マネージド統合間のデバイス検出ワークフローを示しています AWS IoT Device Management。
1. **顧客がデバイス検出を開始する** - 顧客はエンドユーザーに代わってデバイス検出プロセスを開始します。
1. **マネージド統合は参照 ID を生成します**。 のマネージド統合は、お客様が生成した AWS デバイス検出リクエスト`deviceDiscoveryId`に対して という参照識別子 AWS IoT Device Management を生成します。
1. **デバイス検出リクエストの送信** - Managed Integrations for は、認可情報 (OAuth アクセストークンまたは AWS Secrets Manager リファレンス) や を含む `AWS.DiscoverDevices`オペレーションインターフェイスを使用して、デバイス検出リクエストを C2C コネクタ AWS IoT Device Management に送信します`deviceDiscoveryId`。
1. **Connector ストア deviceDiscoveryId** - `DEVICE_DISCOVERY`イベント`deviceDiscoveryId`に含めるコネクタストア。このイベントには、検出されたエンドユーザーのデバイスのリストも含まれ、`DEVICE_DISCOVERY`イベントとして `SendConnectorEvent` API AWS IoT Device Management を使用して の Managed Integrations に送信する必要があります。
1. **コネクタがリソースサーバーを呼び**出す - C2C コネクタはリソースサーバーを呼び出して、エンドユーザーが所有するすべてのデバイスを取得します。
1. **Connector は ACK で応答**します - C2C コネクタ Lambda は Lambda 呼び出し (`invokeFunction`) に応答し、ACK 応答は Managed Integrations for に返され AWS IoT Device Management、`AWS.DiscoverDevices`オペレーションの初期応答として機能します。Managed Integrations for は、お客様が開始したデバイス検出プロセスに ACK を使用してお客様に AWS IoT Device Management 通知します。
1. **リソースサーバーがデバイスリストを返**す - リソースサーバーは、エンドユーザーが所有および運用するデバイスのリストを送信します。
1. **デバイス形式を変換**する - コネクタは、各エンドユーザーデバイスを を含む AWS IoT Device Management 必要なデバイス形式の Managed Integrations に変換`ConnectorDeviceName`し`ConnectorDeviceId`、各デバイスの機能レポートを作成します。
1. **UserId** の提供 - C2C コネクタは、`UserId`検出されたデバイスの所有者も提供します。デバイスリストの一部として、またはリソースサーバーの実装に応じて別の呼び出しで、リソースサーバーから取得できます。
1. **SendConnectorEvent API を呼び出す** - 次に、C2C コネクタは認証情報を使用し、オペレーションパラメータを「DEVICE\_DISCOVERY」に設定 AWS アカウント して`SendConnectorEvent`、SigV4 経由で AWS IoT Device Management API の Managed Integrations を呼び出します。の Managed Integrations に送信されたデバイスのリスト内の各デバイスは、`connectorDeviceId`、、 `connectorDeviceName`などのデバイス固有のパラメータで表 AWS IoT Device Management されます`capabilityReport`。
+ リソースサーバーのレスポンスに基づいて、それに応じて マネージド統合 AWS IoT Device Management に通知する必要があります。
+ たとえば、リソースサーバーにエンドユーザーの検出されたデバイスのリストに対するページ分割レスポンスがある場合、ポーリングごとに `statusCode`パラメータを にして、個々の`DEVICE_DISCOVERY`オペレーションイベントを送信できます`3xx`。デバイス検出がまだ進行中の場合は、ステップ 5、6、7 を繰り返します。
1. **マネージド統合はお客様に通知します**。 のマネージド統合 AWS IoT Device Management は、検出されたエンドユーザーのデバイスについてお客様に通知を送信します。
1. **完了通知** - C2C コネクタが `statusCode`パラメータを 200 の値で更新して`DEVICE_DISCOVERY`オペレーションイベントを送信すると、 の AWS IoT Device Management Managed Integrations はデバイス検出ワークフローの完了をお客様に通知します。
**重要**
必要に応じて、ステップ 7～11 をステップ 6 の前に実行できます。たとえば、サードパーティープラットフォームにエンドユーザーのデバイスを一覧表示する API がある場合、C2C コネクタ Lambda が一般的な ACK で応答`SendConnectorEvent`する前に、DEVICE\_DISCOVERY イベントを で送信できます。
次のリストは、デバイス検出を成功させるための C2C コネクタの要件の概要を示しています。
+ C2C コネクタ Lambda は、 の Managed Integrations からのデバイス検出リクエストメッセージを処理 AWS IoT Device Management して、 `AWS.DiscoverDevices`オペレーションを処理できます。
+ C2C コネクタは、コネクタの登録 AWS アカウント に使用される の認証情報を使用して、SigV4 経由で Managed Integrations for AWS IoT Device Management APIs を呼び出すことができます。
**ステップ 1: マネージドインテグレーションがデバイス検出をトリガーする**
認可タイプに応じて、次のいずれかの JSON ペイロード`DiscoverDevices`を使用して 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: コネクタがデバイス検出イベントを送信する**
次の 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\_DEVICES イベントの CapabilityReport を作成する
上記のイベント構造に示すように、 DISCOVER\_DEVICES イベントで報告されたすべてのデバイスは、`AWS.DiscoverDevices`オペレーションへの応答として機能し、対応するデバイスの機能を記述するために CapbilityReport が必要です。CapabilityReport」は、AWS IoT Device Management デバイス機能のマネージド統合を Matter 準拠の形式で指示します。
+ `nodeId`、文字列: 以下を含むデバイスノードの識別子 `endpoints`
+ `version`、文字列: コネクタ開発者によって設定されたこのデバイスノードのバージョン
+ `endpoints`、List: このデバイスエンドポイントでサポートされている Matter データモデルの AWS 実装のリスト。
+ `id`、文字列: コネクタ開発者によって設定されたエンドポイント識別子
+ `deviceTypes`、List: このエンドポイントがキャプチャするデバイスタイプのリスト、つまり「カメラ」。
+ `clusters`、List: このエンドポイントがサポートする Matter データモデルの AWS 実装のリスト。
+ `id`、文字列: Matter 標準で定義されているクラスター識別子。
+ `revision`、整数: Matter 標準で定義されているクラスターリビジョン番号。
+ `attributes`、Map: 属性識別子とそれに対応する現在のデバイス状態値のマップ。識別子と有効な値は問題標準で定義されています。
+ `id`、文字列: Matter データモデルの AWS 実装で定義される属性 ID。
+ `value`、オブジェクト: 属性 ID で定義された属性の現在の値。「値」のタイプは、属性によって異なる場合があります。`value` フィールドは各属性に対してオプションであり、検出中にコネクタ Lambda が現在の状態を判断できる場合にのみ含める必要があります。
+ `commands`、List: Matter 標準で定義されているように、このクラスターをサポートしているコマンド IDs のリスト。
+ `events`、List: Matter 標準で定義されているように、このクラスターでサポートされているイベント IDs のリスト。
サポートされている機能の現在のリストと [AWS Matter Data Model の対応する実装](matter-data-model.md)については、Data Model ドキュメントの最新リリースを参照してください。