实施 AWS。 SendCommand 操作 - 的托管集成 AWS IoT Device Management
执行设备命令的 C2C 连接器要求解释 AWS 中包含的 “终端节点”。 SendCommand 请求

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

实施 AWS。 SendCommand 操作

该AWS.SendCommand操作允许 AWS IoT Device Management 的托管集成通过 AWS 客户将最终用户启动的命令发送到您的资源服务器。您的资源服务器可能支持多种类型的设备，其中每种类型都有自己的响应模型。命令执行是一个异步过程，其中 AWS IoT Device Management 的托管集成发送带有 “TraceID” 的命令执行请求，您的连接器将包含在通过 “API” SendConnectorEvent 发送回托管集成的命令响应中。AWS IoT Device Management 的托管集成期望资源服务器返回一个确认已收到命令的响应，但不一定表示命令已执行。

下图说明了命令执行流程，并举例说明了最终用户尝试打开房屋灯光的示例：

设备命令执行工作流程
设备命令执行工作流程

  1. 最终用户使用 AWS 客户的应用程序发送开灯的命令。

  2. 客户将命令信息与最终用户的设备信息传递给 AWS IoT Device Management 的托管集成。

  3. 托管集成会生成 “TraceID”，您的连接器将在将命令响应发送回服务时使用它。

  4. AWS IoT Device Management 的托管集成使用AWS.SendCommand操作界面向您的连接器发送命令请求。

    1. 此接口定义的有效载荷包括设备标识符、以 Matter 形式制定的设备命令endpoints/clusters/commands、最终用户的访问令牌以及其他必需的参数。

  5. 您的连接器存储traceId要包含在命令响应中的内容。

    1. 您的连接器会将托管集成命令请求转换为资源服务器的相应格式。

  6. 您的连接器UserId从提供的最终用户的访问令牌中获取，并将其与命令相关联。

    1. 要UserId么使用单独的调用从您的资源服务器中检索，要么从 JWT 和类似令牌中提取访问令牌。

    2. 实现取决于您的资源服务器和访问令牌的详细信息。

  7. 您的连接器调用资源服务器以 “打开” 最终用户的灯。

  8. 资源服务器与设备交互。

    1. 连接器中继到资源服务器已下发命令的 AWS IoT IoT Device Management 托管集成，并以 ACK 作为初始同步命令响应进行响应。

    2. 然后，托管集成将其中继回客户应用程序。

  9. 设备开灯后，您的资源服务器会捕获该设备事件。

  10. 您的资源服务器将设备事件发送到连接器。

  11. 您的连接器将资源服务器生成的设备事件转换为托管集成 DEVICE_COMMAND_RESPONSE 事件操作类型。

  12. 您的连接器调用 SendConnectorEvent API，操作为 “DEVICE_COMMAND_RESPONSE”。

    1. 它会在初始请求中附上由 AWS IoT Device Management 托管集成traceId提供的内容。

  13. 托管集成会通知客户有关最终用户的设备状态变化。

  14. 客户通知最终用户设备灯已亮起。

    注意

    您的资源服务器配置决定了处理失败的设备命令请求和响应消息的逻辑。这包括对命令使用相同的 referenceId 进行消息重试尝试。

执行设备命令的 C2C 连接器要求

以下列表概述了 C2C 连接器的要求，以促进设备命令的成功执行。

  • C2C 连接器 Lambda 可以AWS.SendCommand处理来自 AWS IoT Device Management 托管集成的操作请求消息。

  • 您的 C2C 连接器必须跟踪发送到您的资源服务器的命令，并将其映射到相应的 “TraceID”。

  • 您可以使用用于注册 C2C 连接器的 AWS 凭证通过 Sigv4 调用 AWS IoT Device Management 服务 API 的 AWS 账户 托管集成。

  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，其中连接器向 AWS IoT 设备管理服务的托管集成发送 ACK）。

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

  3. 连接器发送设备命令响应事件（请参阅上图中的步骤 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”
                }            
 		]
        }]
    }
}
    注意

    在通过 API 收到相应的 DEVICE_COMMAND_RESPONSE 事件之前，由于命令执行而导致的设备状态变化不会反映在 AWS IoT Device Management 的托管集成中。 SendConnectorEvent 这意味着，在托管集成收到前面步骤 3 的事件之前，无论您的连接器调用响应是否表示成功，都不会更新设备状态。

解释 AWS 中包含的 “终端节点”。 SendCommand 请求

托管集成将使用设备发现期间报告的设备功能来确定设备可以接受哪些命令。每个设备功能都是通过 AWS 实现物质数据模型进行建模的；因此，所有传入的命令都将从给定集群中的 “commands” 字段派生。您的连接器负责解析 “端点” 字段，确定相应的 Matter 命令，然后对其进行翻译，以便正确的命令到达设备。通常，这意味着将 Matter 数据模型转换为相关的 API 请求。

执行命令后，您的连接器将确定由物质数据模型的 AWS 实现定义的哪些 “属性” 因此发生了变化。然后，这些更改将通过 API 发送的 API DEVICE_COMMAND_RESPONSE 事件报告给 AWS IoT Device Management 的托管集成。SendConnectorEvent

考虑以下示例负载中包含的 “端点” 字段：AWS.SendCommand

          "endpoints": [{
              "id": "1",    
              "clusters": [{
                  "id": "0x0202",
                  "commands": [{
                      "0xff01": 
                          {
                              "0x0000": "3”
                  		}
                  }]
              }]
          }]
通过此对象，连接器可以确定以下内容：

  1. 设置终端节点和集群信息：

    1. 将端点设置id为 “1”。

      注意

      如果设备定义了多个端点，例如单个集群（例如On/Off) can control multiple capabilities (i.e. turn a light on/off as well as turning a strobe on/off），则使用此 ID 将命令路由到正确的功能。

    2. 将集群设置id为 “0x0202”（风扇控制集群）。

  2. 设置命令信息：

    1. 将命令标识符设置为 “0xff01”（更新状态命令由定义）。 AWS

    2. 使用请求中提供的值更新包含的属性标识符。

  3. 更新属性：

    1. 将属性标识符设置为 “0x0000”（风扇控制集FanMode 群的属性）。

    2. 将属性值设置为 “3”（高风扇速度）。

托管集成定义了两种 “自定义” 命令类型，这些类型不是由物质数据模型的 AWS 实现严格定义的： ReadState 和 UpdateState 命令。要获取和设置 Matter 定义的集群属性，托管集成将向您的连接器发送一个AWS.SendCommand请求，其中包含与 UpdateState (id: 0xff01) 或 ReadState (id: 0xff02) IDs 相关的命令，以及必须更新或读取的相应属性参数。对于设置为可变（可更新）或可检索（可读取）的属性，可以为任何设备类型调用这些命令，这些属性可以从相应的 Matter 数据模型 AWS 实现中调用。