デバイスコマンド実行の C2C コネクタ要件 AWS.SendCommand リクエストに含まれる問題「エンドポイント」の解釈

AWS.SendCommand オペレーションを実装する

このAWS.SendCommandオペレーションにより、AWS IoT Device Management のマネージド統合は、エンドユーザーが開始したコマンドを AWS 顧客経由でリソースサーバーに送信できます。リソースサーバーは、複数のタイプのデバイスをサポートする場合があります。各タイプには独自のレスポンスモデルがあります。コマンド実行は、AWS IoT Device Management のマネージド統合がtraceId」でコマンド実行のリクエストを送信する非同期プロセスです。このリクエストは、コネクタがSendConnectorEvent」 API を介してマネージド統合に返送されるコマンドレスポンスに含めます。AWS IoT Device Management のマネージド統合は、リソースサーバーがコマンドが受信されたことを確認するレスポンスを返すことを期待しますが、必ずしもコマンドが実行されたことを示すわけではありません。

次の図は、エンドユーザーが家の照明をオンにしようとする例を含むコマンド実行フローを示しています。

デバイスコマンド実行ワークフロー

エンドユーザーは、 AWS 顧客のアプリケーションを使用して照明をオンにするコマンドを送信します。
顧客は、AWS IoT Device Management のマネージド統合にコマンド情報をエンドユーザーのデバイス情報と中継します。
マネージド統合は、コマンドレスポンスをサービスに送り返すときにコネクタが使用する「traceId」を生成します。
AWS IoT Device Management のマネージド統合は、 AWS.SendCommandオペレーションインターフェイスを使用して、コマンドリクエストをコネクタに送信します。
1. このインターフェイスで定義されるペイロードは、デバイス識別子、 Matter endpoints/clusters/commandsとして定式化されたデバイスコマンド、エンドユーザーのアクセストークン、およびその他の必須パラメータで構成されます。
コネクタは、コマンドレスポンスに含まれる traceId を保存します。
1. コネクタは、マネージド統合コマンドリクエストをリソースサーバーの適切な形式に変換します。
コネクタは、提供されたエンドユーザーのアクセストークンUserIdから取得し、コマンドに関連付けます。
1. は、別の呼び出しを使用してリソースサーバーから取得するか、JWT および同様のトークンの場合はアクセストークンから抽出UserIdできます。
2. 実装は、リソースサーバーとアクセストークンの詳細によって異なります。
コネクタは、リソースサーバーを「ターンオン」エンドユーザーのライトに呼び出します。
リソースサーバーはデバイスとやり取りします。
1. コネクタは、リソースサーバーがコマンドを配信した AWS IoT Device Management のマネージド統合にリレーし、最初の同期コマンドレスポンスとして ACK で応答します。
2. マネージド統合は、それをカスタマーアプリケーションに中継します。
デバイスがライトをオンにすると、そのデバイスイベントはリソースサーバーによってキャプチャされます。
リソースサーバーは、デバイスイベントをコネクタに送信します。
コネクタは、リソースサーバーによって生成されたデバイスイベントをマネージド統合 DEVICE_COMMAND_RESPONSE イベントオペレーションタイプに変換します。
コネクタは、オペレーションを「DEVICE_COMMAND_RESPONSE」として SendConnectorEvent API を呼び出します。
1. 最初のリクエストで AWS IoT Device Management のマネージド統合によってtraceId提供されるをアタッチします。
マネージド統合は、エンドユーザーのデバイス状態の変更について顧客に通知します。
お客様は、デバイスのライトがオンになったことをエンドユーザーに通知します。

注記
リソースサーバー設定によって、失敗したデバイスコマンドのリクエストおよびレスポンスメッセージを処理するロジックが決まります。これには、コマンドに同じ referenceId を使用したメッセージの再試行が含まれます。

デバイスコマンド実行の C2C コネクタ要件

次のリストは、デバイスコマンドの実行を成功させるための C2C コネクタの要件の概要を示しています。

C2C コネクタ Lambda は、AWS IoT Device Management のマネージド統合からのAWS.SendCommandオペレーションリクエストメッセージを処理できます。
C2C コネクタは、リソースサーバーに送信されたコマンドを追跡し、適切なtraceId」にマッピングする必要があります。
C2C コネクタの登録 AWS アカウントに使用される AWS 認証情報を使用して、SigV4 経由で AWS IoT Device Management サービス API のマネージド統合を呼び出すことができます。

マネージド統合は、コネクタにコマンドを送信します (前の図のステップ 4 を参照）。


/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”
                  		}
                  }]
              }]
          }]
     }
  }

C2C コネクタ ACK コマンド (コネクタが AWS IoT Device Management Service のマネージド統合に ACK を送信する前の図のステップ 7 を参照）。


{
     "header":{
          "responseCode":200
     },
     "payload":{
          "responseMessage": "Successfully received send-command request for connector 'Your-Connector-Id' and connector-device-id 'Your_Device_Id'" 
     }
  }

コネクタは Device Command Response イベントを送信します (前の図のステップ 11 を参照）。


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. エンドポイントをid「1」に設定します。
  
  注記
  デバイスが複数のエンドポイントを定義し、単一のクラスター (オン/オフなど) が複数の機能を制御できる場合 (ライトのオン/オフ、ストロボのオン/オフなど）、この ID はコマンドを正しい機能にルーティングするために使用されます。
2. クラスターをid「0x0202」 (ファンコントロールクラスター) に設定します。
コマンド情報を設定します。
1. コマンド識別子を「0xff01」 ( で定義される状態の更新コマンド) に設定します AWS。
2. 含まれている属性識別子を、リクエストで指定された値で更新します。
属性を更新します。
1. 属性識別子を「0x0000」 (ファンコントロールクラスターのFanMode 属性) に設定します。
2. 属性値を「3」 (高速ファン速度) に設定します。

マネージド統合では、Matter データモデルの AWS 実装で厳密に定義されていない 2 つの「カスタム」コマンドタイプ、ReadState コマンドと UpdateState コマンドが定義されています。Matter で定義されたクラスター属性を取得して設定するために、マネージド統合は UpdateState (id: 0xff01) または ReadState (id: 0xff02) に関連するコマンド IDs と、更新または読み取りが必要な属性の対応するパラメータを含むAWS.SendCommandリクエストをコネクタに送信します。これらのコマンドは、 Matter データモデルの対応する AWS 実装から変更可能 (更新可能) または取得可能 (読み取り可能) に設定された属性の任意のデバイスタイプに対して呼び出すことができます。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

AWS.DiscoverDevices オペレーションを実装する

SendConnectorEvent API を使用してデバイスイベントを送信する