翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# AWS.SendCommand オペレーションを実装する
この`AWS.SendCommand`オペレーションにより、AWS IoT Device Management のマネージド統合は、エンドユーザーが開始したコマンドを AWS 顧客経由でリソースサーバーに送信できます。リソースサーバーは、複数のタイプのデバイスをサポートする場合があります。各タイプには独自のレスポンスモデルがあります。コマンド実行は、AWS IoT Device Management のマネージド統合がtraceId」でコマンド実行のリクエストを送信する非同期プロセスです。このリクエストは、コネクタがSendConnectorEvent」 API を介してマネージド統合に返送されるコマンドレスポンスに含めます。AWS IoT Device Management の マネージド統合では、リソースサーバーがコマンドが受信されたことを確認するレスポンスを返すことを想定していますが、必ずしもコマンドが実行されたことを示すとは限りません。
次の図は、エンドユーザーが家の照明をオンにしようとする例を含むコマンド実行フローを示しています。
**デバイスコマンド実行ワークフロー**
1. エンドユーザーは、 AWS 顧客のアプリケーションを使用して照明をオンにするコマンドを送信します。
1. 顧客は、エンドユーザーのデバイス情報を使用して、AWS IoT Device Management のマネージド統合にコマンド情報を中継します。
1. マネージド統合は、コマンドレスポンスをサービスに送り返すときにコネクタが使用する「traceId」を生成します。
1. AWS IoT Device Management の マネージド統合は、 `AWS.SendCommand`オペレーションインターフェイスを使用してコマンドリクエストをコネクタに送信します。
1. このインターフェイスで定義されるペイロードは、デバイス識別子、 Matter endpoints/clusters/commandsとして定式化されたデバイスコマンド、エンドユーザーのアクセストークン、およびその他の必須パラメータで構成されます。
1. コネクタは、コマンドレスポンスに含まれる `traceId` を保存します。
1. コネクタは、マネージド統合コマンドリクエストをリソースサーバーの適切な形式に変換します。
1. コネクタは、提供されたエンドユーザーのアクセストークン`UserId`から取得し、 コマンドに関連付けます。
1. `UserId` は、別の呼び出しを使用してリソースサーバーから取得するか、JWT および同様のトークンの場合はアクセストークンから抽出できます。
1. 実装は、リソースサーバーとアクセストークンの詳細によって異なります。
1. コネクタは、リソースサーバーを「ターンオン」エンドユーザーのライトに呼び出します。
1. リソースサーバーはデバイスとやり取りします。
1. コネクタは、リソースサーバーが コマンドを配信した AWS IoT Device Management のマネージド統合にリレーし、最初の同期コマンドレスポンスとして ACK で応答します。
1. マネージド統合は、それをカスタマーアプリケーションに中継します。
1. デバイスがライトをオンにすると、そのデバイスイベントはリソースサーバーによってキャプチャされます。
1. リソースサーバーは、デバイスイベントをコネクタに送信します。
1. コネクタは、リソースサーバーによって生成されたデバイスイベントをマネージド統合 DEVICE\_COMMAND\_RESPONSE イベントオペレーションタイプに変換します。
1. コネクタは、 オペレーションを「DEVICE\_COMMAND\_RESPONSE」として `SendConnectorEvent` API を呼び出します。
1. 最初のリクエストで AWS IoT Device Management のマネージド統合によって`traceId`提供される をアタッチします。
1. マネージド統合は、エンドユーザーのデバイス状態の変化を顧客に通知します。
1. お客様は、デバイスのライトがオンになったことをエンドユーザーに通知します。
**注記**
リソースサーバー設定によって、失敗したデバイスコマンドのリクエストおよびレスポンスメッセージを処理するロジックが決まります。これには、コマンドに同じ referenceId を使用したメッセージの再試行が含まれます。
## デバイスコマンド実行の C2C コネクタ要件
次のリストは、デバイスコマンドの実行を成功させるための C2C コネクタの要件の概要を示しています。
+ C2C コネクタ Lambda は、AWS IoT Device Management のマネージド統合からの`AWS.SendCommand`オペレーションリクエストメッセージを処理できます。
+ C2C コネクタは、リソースサーバーに送信されたコマンドを追跡し、適切なtraceId」にマッピングする必要があります。
+ C2C コネクタの登録 AWS アカウント に使用される AWS 認証情報を使用して、SigV4 経由で AWS IoT Device Management サービス API の マネージド統合を呼び出すことができます。
1. マネージド統合は、コネクタにコマンドを送信します (前の図のステップ 4 を参照）。
1.
```
/Send-Command
{
"header": {
"auth": {
"token": "ashriu32yr97feqy7afsaf",
"type": "OAuth2.0"
}
},
"payload": {
"operationName": "AWS.SendCommand",
"operationVersion": "1.0",
"connectorId": "{{Your-Connector-Id}}",
"connectorDeviceId": "{{Your_Device_Id}}",
"traceId": "traceId-3241u78123419",
"endpoints": [{
"id": "1",
"clusters": [{
"id": "0x0202",
"commands": [{
"0xff01":
{
"0x0000": "3”
}
}]
}]
}]
}
}
```
1. C2C コネクタ ACK コマンド (コネクタが AWS IoT Device Management Service のマネージド統合に ACK を送信する前の図のステップ 7 を参照）。
1.
```
{
"header":{
"responseCode":200
},
"payload":{
"responseMessage": "Successfully received send-command request for connector '{{Your-Connector-Id}}' and connector-device-id '{{Your_Device_Id}}'"
}
}
```
1. コネクタは Device Command Response イベントを送信します (前の図のステップ 11 を参照）。
1.
```
AWS-API: /SendConnectorEvent
URI: POST /connector-event/{{{Your-Connector-Id}}}
{
"UserId": "End-User-Id",
"Operation": "DEVICE_COMMAND_RESPONSE",
"OperationVersion": "1.0",
"StatusCode": 200,
"Message": “Example message”,
"ConnectorDeviceId": "{{Your_Device_Id}}",
"TraceId": "traceId-3241u78123419",
"MatterEndpoint": {
"id": "1",
"clusters": [{
"id": "0x0202",
"attributes": [
{
"0x0000": “3”
}
],
"commands": [
"0xff01":
{
"0x0000": "3”
}
]
}]
}
}
```
**注記**
コマンド実行の結果としてのデバイス状態の変更は、対応する DEVICE\_COMMAND\_RESPONSE イベントが SendConnectorEvent API を介して受信されるまで、AWS IoT Device Management のマネージド統合に反映されません。つまり、マネージド統合が前のステップ 3 からイベントを受信するまで、コネクタ呼び出しレスポンスが成功を示すかどうかにかかわらず、デバイスの状態は更新されません。
## AWS.SendCommand リクエストに含まれる問題「エンドポイント」の解釈
マネージド統合では、デバイス検出中に報告されたデバイス機能を使用して、デバイスが受け入れることができるコマンドを決定します。すべてのデバイス機能は Matter データモデルの AWS 実装によってモデル化されるため、すべての受信コマンドは特定のクラスター内の「 コマンド」フィールドから取得されます。コネクタは、「endpoints」フィールドを解析し、対応する Matter コマンドを決定し、正しいコマンドがデバイスに到達するように変換する責任があります。通常、これは Matter データモデルを関連する API リクエストに変換することを意味します。
コマンドが実行されると、コネクタは Matter Data Model の AWS 実装によって定義されたどの「属性」が結果として変更されたかを決定します。これらの変更は、API で送信された API DEVICE\_COMMAND\_RESPONSE イベントを介して AWS IoT Device Management のマネージド統合に報告されます`SendConnectorEvent`。
次の`AWS.SendCommand`ペイロードの例に含まれている「endpoints」フィールドを考えてみましょう。
```
"endpoints": [{
"id": "1",
"clusters": [{
"id": "0x0202",
"commands": [{
"0xff01":
{
"0x0000": "3”
}
}]
}]
}]
```
**このオブジェクトから、コネクタは以下を判断できます。**
1. エンドポイントとクラスター情報を設定します。
1. エンドポイントを`id`「1」に設定します。
**注記**
デバイスが複数のエンドポイントを定義し、単一のクラスター (オン/オフなど) が複数の機能を制御できる場合 (ライトのオン/オフ、ストロボのオン/オフなど）、この ID はコマンドを正しい機能にルーティングするために使用されます。
1. クラスターを「0x0202」 (ファンコントロールクラスター) `id`に設定します。
1. コマンド情報を設定します。
1. コマンド識別子を「0xff01」 ( で定義される状態の更新コマンド) に設定します AWS。
1. 含まれている属性識別子を、リクエストで指定された値で更新します。
1. 属性を更新します。
1. 属性識別子を「0x0000」 (ファンコントロールクラスターのFanMode 属性) に設定します。
1. 属性値を「3」 (高速ファン) に設定します。
マネージド統合では、Matter データモデルの AWS 実装で厳密に定義されていない 2 つの「カスタム」コマンドタイプ、ReadState コマンドと UpdateState コマンドが定義されています。Matter で定義されたクラスター属性を取得して設定するために、マネージド統合は UpdateState (id: 0xff01) または ReadState (id: 0xff02) に関連するコマンド IDs と、更新または読み取りが必要な属性の対応するパラメータを含む`AWS.SendCommand`リクエストをコネクタに送信します。これらのコマンドは、 Matter Data Model の対応する AWS 実装から変更可能 (更新可能) または取得可能 (読み取り可能) に設定された属性の任意のデバイスタイプに対して呼び出すことができます。