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

AWS.SendCommand オペレーションにより、 の Managed Integrations AWS IoT Device Management は、エンドユーザーが開始したコマンドを AWS 顧客経由でリソースサーバーに送信できます。リソースサーバーは、複数のタイプのデバイスをサポートする場合があります。各タイプには独自のレスポンスモデルがあります。

コマンド実行は、 の Managed Integrations が でコマンド実行のリクエスト AWS IoT Device Management を送信する非同期プロセスです。このリクエストはtraceId、コネクタが SendConnectorEvent API AWS IoT Device Management 経由で の Managed Integrations に返送されるコマンドレスポンスに含まれます。Managed Integrations for は、リソースサーバーがコマンドが受信されたことを確認するレスポンスを返すことを AWS IoT Device Management 期待しますが、そのコマンドが実行されたことを示すとは限りません。

Device Command 実行ワークフロー

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

ワークフローのステップ

Device Command Execution の C2C コネクタ要件

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

コマンド実行プロセス

ステップ 1: マネージド統合がコネクタにコマンドを送信する

認可タイプに応じて、次のいずれかのペイロードを使用して POST リクエストを送信します。

OAuth 2.0 リクエスト:

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

一般的な認可リクエスト:

/Send-Command
{
     "header": {
          "auth": {
              "secretsManager": {
                  "arn": "string",
                  "versionId": "string"
              },
              "type": "GeneralAuthorization"
          }
     },
     "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"
                  		}
                  }]
              }]
          }]
     }
}

ステップ 2: C2C Connector ACK コマンド

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

ステップ 3: コネクタがデバイスコマンドレスポンスイベントを送信する

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

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

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