實作 AWS.SendCommand 操作 - 的受管整合 AWS IoT Device Management
裝置命令執行的 C2C 連接器需求解譯 AWS.SendCommand 請求中包含的事項「端點」

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

實作 AWS.SendCommand 操作

AWS.SendCommand 此操作允許 AWS IoT Device Management 的受管整合，透過 AWS 客戶將最終使用者啟動的命令傳送至您的資源伺服器。您的資源伺服器可能支援多種類型的裝置，其中每種類型都有自己的回應模型。命令執行是一種非同步程序，其中 AWS IoT Device Management 的受管整合會使用 `traceId` 傳送命令執行的請求，您的連接器會將此請求包含在透過 `SendConnectorEvent` API 傳回至受管整合的命令回應中。AWS IoT Device Management 的受管整合預期資源伺服器會傳回確認收到該命令的回應，但不一定表示該命令已執行。

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

裝置命令執行工作流程
裝置命令執行工作流程

  1. 最終使用者傳送命令，以使用 AWS 客戶的應用程式開啟光源。

  2. 客戶將命令資訊轉送至 AWS IoT Device Management 的受管整合與最終使用者的裝置資訊。

  3. 受管整合會產生 "traceId"，您的連接器會在將命令回應傳回服務時使用。

  4. AWS IoT Device Management 的 受管整合會使用 AWS.SendCommand操作界面，將命令請求傳送至您的連接器。

    1. 此界面定義的承載包含裝置識別符、建構為事項endpoints/clusters/commands的裝置命令、最終使用者的存取權杖，以及其他必要的參數。

  5. 連接器會存放traceId要包含在命令回應中的 。

    1. 連接器會將受管整合命令請求轉譯為資源伺服器的適當格式。

  6. 連接器UserId會從提供的最終使用者的存取權杖取得，並將其與 命令建立關聯。

    1. 在 JWT 和類似字符的情況下， UserId 可能會使用單獨的呼叫從您的資源伺服器擷取，或從存取字符中擷取。

    2. 實作取決於您的資源伺服器和存取字符詳細資訊。

  7. 連接器會將資源伺服器呼叫「開啟」最終使用者的光源。

  8. 資源伺服器會與裝置互動。

    1. 連接器會轉送至資源伺服器已交付命令的 AWS IoT Device Management 受管整合，並以 ACK 做為初始同步命令回應。

    2. 受管整合接著會將其轉送回客戶應用程式。

  9. 裝置開啟燈光後，資源伺服器會擷取該裝置事件。

  10. 您的資源伺服器會將裝置事件傳送至連接器。

  11. 連接器會將資源伺服器產生的裝置事件轉換為受管整合 DEVICE_COMMAND_RESPONSE 事件操作類型。

  12. 連接器會呼叫操作為 "DEVICE_COMMAND_RESPONSE" 的 SendConnectorEvent API。

    1. 它會在初始請求中連接 AWS IoT Device Management 的受管整合traceId所提供的 。

  13. 受管整合會通知客戶有關最終使用者的裝置狀態變更。

  14. 客戶通知最終使用者裝置指示燈已開啟。

    注意

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

裝置命令執行的 C2C 連接器需求

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

  • C2C 連接器 Lambda 可以處理來自 AWS IoT Device Management 受管整合AWS.SendCommand的操作請求訊息。

  • 您的 C2C 連接器必須追蹤傳送至資源伺服器的命令，並將其映射至適當的 `traceId`。

  • 您可以使用 AWS 帳戶 用於註冊 C2C 連接器的 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”
                  		}
                  }]
              }]
          }]
     }
  }

  2. C2C 連接器 ACK 命令 （請參閱先前圖表中的步驟 7，其中連接器會將 ACK 傳送至 AWS IoT Device Management Service 的受管整合）。

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

  3. 連接器傳送 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”
                }            
 		]
        }]
    }
}
    注意

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

解譯 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. 設定端點和叢集資訊：

    1. 將端點id設定為 "1"。

      注意

      如果裝置定義多個端點，讓單一叢集 （例如開啟/關閉） 可以控制多個功能 （即開啟/關閉燈光，以及開啟/關閉頻閃），則會使用此 ID 將命令路由至正確的功能。

    2. 將叢集id設定為 "0x0202" （風扇控制叢集）。

  2. 設定命令資訊：

    1. 將命令識別符設定為 "0xff01" （更新狀態命令由 定義 AWS)。

    2. 使用請求中提供的值更新包含的屬性識別符。

  3. 更新 屬性：

    1. 將屬性識別符設為 "0x0000" (FanMode 屬性的風扇控制叢集）。

    2. 將屬性值設定為 "3" （高風扇速度）。

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