實作 AWS.SendCommand 操作

AWS.SendCommand 操作可讓的受管整合，透過 AWS 客戶將最終使用者啟動的 AWS IoT Device Management 命令傳送至您的資源伺服器。您的資源伺服器可能支援多種類型的裝置，其中每種類型都有自己的回應模型。

命令執行是一種非同步程序，其中的受管整合會使用 AWS IoT Device Management 傳送命令執行的請求traceId，您的連接器將包含在 AWS IoT Device Management 透過 SendConnectorEvent API 傳回的受管整合的命令回應中。的受管整合 AWS IoT Device Management 預期資源伺服器會傳回回應，確認收到該命令，但不一定表示該命令已執行。

裝置命令執行工作流程

下圖說明命令執行流程，其中包含最終使用者嘗試開啟其房屋燈光的範例：

工作流程步驟

最終使用者傳送命令 - 最終使用者傳送命令，以使用 AWS 客戶的應用程式開啟光源。
客戶轉送命令 - 客戶將命令資訊轉送至的受管整合， AWS IoT Device Management 其中包含最終使用者的裝置資訊。
受管整合會產生 traceId - 的受管整合 AWS IoT Device Management 會產生 "traceId"，供連接器在將命令回應傳回服務時使用。
傳送至連接器的命令請求 - 的受管整合會使用 AWS.SendCommand操作界面，將命令請求 AWS IoT Device Management 傳送至您的連接器。
- 此界面定義的承載包含裝置識別符、建構為事項endpoints/clusters/commands的裝置命令、最終使用者的存取權杖，以及其他必要的參數。
連接器存放 traceId - 您的連接器存放traceId要包含在命令回應中的。
- 連接器會將 AWS IoT Device Management 命令請求的受管整合轉譯為資源伺服器的適當格式。
連接器取得 UserId - 連接器UserId從提供的最終使用者的存取權杖取得，並將其與命令建立關聯。
- 在 JWT 和類似字符的情況下， UserId 可能會使用單獨的呼叫從您的資源伺服器擷取，或從存取字符中擷取。
- 實作取決於您的資源伺服器和存取權杖詳細資訊。
連接器呼叫資源伺服器 - 您的連接器呼叫資源伺服器到「開啟」最終使用者的光源。
資源伺服器與裝置互動 - 資源伺服器與裝置互動。
- 連接器會轉送至資源伺服器已交付命令 AWS IoT Device Management 的受管整合，並以 ACK 做為初始同步命令回應。
- 的受管整合 AWS IoT Device Management 接著會轉送回客戶應用程式。
裝置執行命令 - 裝置開啟燈光後，資源伺服器會擷取該裝置事件。
資源伺服器傳送裝置事件 - 您的資源伺服器傳送裝置事件到連接器。
連接器轉換事件 - 連接器會將資源伺服器產生的裝置事件轉換為 AWS IoT Device Management DEVICE_COMMAND_RESPONSE 事件操作類型的受管整合。
連接器呼叫 SendConnectorEvent - 您的連接器呼叫操作為 "DEVICE_COMMAND_RESPONSE" 的 SendConnectorEvent API。
- 它會在初始請求 AWS IoT Device Management 中連接 Managed Integrations for traceId提供的。
受管整合會通知客戶 - 適用於的受管整合會 AWS IoT Device Management 通知客戶有關最終使用者的裝置狀態變更。
客戶通知最終使用者 - 客戶通知最終使用者裝置指示燈已開啟。

注意

您的資源伺服器組態會決定處理失敗裝置命令請求和回應訊息的邏輯。這包括使用命令的相同 referenceId 進行訊息重試嘗試。

Device Command 執行的 C2C 連接器需求

下列清單概述 C2C 連接器的要求，以促進成功的裝置命令執行。

C2C 連接器 Lambda 可以處理來自 AWS IoT Device Management 受管整合AWS.SendCommand的操作請求訊息。
您的 C2C 連接器必須追蹤傳送至資源伺服器的命令，並將其映射至適當的 `traceId`。
您可以使用 AWS 帳戶用於註冊 C2C 連接器的 AWS 登入資料，透過 SigV4 呼叫 AWS IoT Device Management 服務 API 的受管整合。

命令執行程序

步驟 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 連接器 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”
                }            
 		]
        }]
    }
}

注意

在透過 SendConnectorEvent API 收到對應的 DEVICE_COMMAND_RESPONSE 事件 AWS IoT Device Management 之前，的受管整合中不會反映因命令執行而變更的裝置狀態。這表示在的受管整合 AWS IoT Device Management 收到先前步驟 3 的事件之前，無論您的連接器調用回應是否表示成功，裝置狀態都不會更新。

重要

除非裝置已確認實際套用狀態變更，否則請勿在 DEVICE_COMMAND_RESPONSE 承載中包含屬性。沒有屬性的 DEVICE_COMMAND_RESPONSE 可做為確認命令已分派給第三方，並導致 DEVICE_COMMAND 通知。若要報告裝置上已更新屬性值，請傳送具有更新屬性的個別 DEVICE_EVENT。此區別可防止命令顯示為成功的誤報，但裝置從未收到狀態變更，例如裝置最近中斷連線時。

解譯 AWS.SendCommand 請求中包含的事項「端點」

受管整合將使用裝置探索期間回報的裝置功能，來判斷裝置可接受哪些命令。每個裝置功能都會透過事項資料模型的 AWS 實作進行建模；因此，所有傳入的命令都會衍生自指定叢集中的 `commands` 欄位。您的連接器必須負責剖析 `endpoints` 欄位、判斷對應的事項命令，以及翻譯成正確的命令到達裝置。一般而言，這表示將事項資料模型轉換為相關的 API 請求。

執行命令後，您的連接器接著會判斷事項資料模型 AWS 實作定義的哪些 `attributes` 已因此變更。然後，這些變更會透過使用 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 的 Fan Control Cluster 屬性）。
2. 將屬性值設定為 "3" （高風扇速度）。

受管整合已定義兩種「自訂」命令類型，這些類型並非由事項資料模型的 AWS 實作嚴格定義：ReadState 和 UpdateState 命令。若要取得和設定事項定義的叢集屬性，受管整合會傳送AWS.SendCommand請求給您的連接器，其中包含與 UpdateState (id： 0xff01) 或 ReadState (id： 0xff02) 相關的命令 IDs，以及必須更新或讀取的屬性對應參數。對於從Matter Data Model 的對應 AWS 實作中設定為可變（可更新）或可擷取（可讀取）的屬性，可以針對任何裝置類型叫用這些命令。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

實作 AWS.DiscoverDevices 操作

使用 SendConnectorEvent API 傳送裝置事件