高级命令工作流程 - AWS IoT Core
创建和管理命令选择目标并订阅主题启动和监控命令执行（可选）启用命令事件通知

高级命令工作流程

以下步骤概述了您的设备与 AWS IoT Device Management 命令之间的命令工作流程。当您使用任何命令 HTTP API 操作时，请求使用 Sigv4 凭证进行签名。

AWS IoT Device Management 设备命令高级工作流程概述。

创建和管理命令

要为您的设备创建和管理命令，请执行以下步骤。

  1. 创建命令资源

    在将命令发送到您的设备之前，请从 AWS IoT 控制台的命令中心或使用 CreateCommand 控制面板 API 操作创建命令资源。

  2. 指定有效载荷

    创建命令时，您必须为命令提供有效载荷。有效载荷内容可以使用您选择的任何格式。为确保设备正确解释有效载荷，我们建议您同时指定有效载荷内容类型。

  3. （可选）管理已创建的命令

    创建命令后，您可以更新命令的显示名称和描述。如果您不再打算使用某个命令，也可以将其标记为已弃用，或将其从您的账户中完全删除。如果要修改有效载荷信息，必须创建一个新命令并上传新的有效载荷文件。

为您的命令选择目标设备并订阅 MQTT 主题

为准备命令工作流程，请选择您的目标设备并指定 AWS IoT 保留的 MQTT 主题以接收命令和发布响应消息。

  1. 为您的命令选择目标设备

    为准备命令工作流程，请选择将接收命令并执行指定操作的目标设备。目标设备可以是您在 AWS IoT 注册表中注册的 AWS IoT 事物，或者，如果您的设备尚未向 AWS IoT 注册，则可以使用 MQTT 客户端 ID 指定。有关更多信息，请参阅 目标设备注意事项。

  2. 配置物联网设备策略

    在您的设备可以接收命令执行并发布更新之前，它必须使用授予执行这些操作权限的 IAM 策略。有关可根据您的设备是注册为 AWS IoT 事物还是指定为 MQTT 客户端 ID 而使用的示例策略，请参阅 IAM 策略示例。

  3. 建立 MQTT 连接

    为准备您的设备使用命令功能，您的设备必须首先连接到消息代理并订阅请求和响应主题。您的设备必须被允许执行 iot:Connect 操作才能连接到 AWS IoT Core 并与消息代理建立 MQTT 连接。要查找您的 AWS 账户 的数据面板端点，请使用 DescribeEndpoint API 或 describe-endpoint CLI 命令，如下所示。

    aws iot describe-endpoint --endpoint-type iot:Data-ATS

    运行此命令将返回账户特定的数据面板端点，如下所示。

    account-specific-prefix.iot.region.amazonaws.com
  4. 订阅命令主题

    建立连接后，您的设备可以随后订阅命令请求主题。当您创建命令并在目标设备上启动命令执行时，消息代理会将有效载荷消息发布到请求主题。然后，您的设备可以接收有效载荷消息并处理命令。

    （可选）您的设备也可以订阅这些命令响应主题（accepted 或 rejected）以接收指示云服务是接受还是拒绝设备响应的消息。

    在此示例中：

    • <device> 与 thing 或 client，具体取决于您目标设备是已注册为物联网事物，还是指定为 MQTT 客户端。

    • <DeviceID> 与您目标设备的唯一标识符。此 ID 可以是唯一的 MQTT 客户端 ID 或事物名称。

    注意

    如果有效载荷类型不是 JSON 或 CBOR，则命令请求主题中可能不存在 <PayloadFormat> 字段。要获取有效载荷格式，我们建议您使用 MQTT 5 从 MQTT 消息头中获取格式信息。有关更多信息，请参阅 命令主题。

    $aws/commands/<devices>/<DeviceID>/executions/+/request/<PayloadFormat>
$aws/commands/<devices>/<DeviceID>/executions/+/response/accepted/<PayloadFormat>
$aws/commands/<devices>/<DeviceID>/executions/+/response/rejected/<PayloadFormat>

为目标设备启动和监控命令执行

创建命令并指定命令的目标后，您可以通过执行以下步骤在目标设备上开始执行。

  1. 在目标设备上启动命令执行

    从 AWS IoT 控制台的命令中心或使用 StartCommandExecution 数据面板 API 与您的账户特定端点在目标设备上启动命令执行。如果您使用双栈端点（IPv4 和 IPv6），请使用 iot:Data-ATS。iot:Jobs 端点仅适用于 IPv4。

    API 将有效载荷消息发布到设备已订阅的上述命令请求主题。

    注意

    如果在命令从云端发送时设备离线，并且它使用 MQTT 持久会话，则命令会在消息代理处等待。如果设备在超时持续时间之前重新上线，并且它已订阅命令请求主题，则设备可以处理命令并将结果发布到命令响应主题。如果设备在超时持续时间之前没有重新上线，则命令执行将超时，并且有效载荷消息可能会过期并被消息代理丢弃。

  2. 更新命令执行的结果

    设备现在接收有效载荷消息，可以处理命令并执行指定的操作，然后使用 UpdateCommandExecution API 将命令执行的结果发布到以下命令响应主题。如果您的设备订阅了命令接受和拒绝响应主题，它将收到一条消息，指示响应是被云服务接受还是拒绝。

    根据您在请求主题中的指定方式，<devices> 可以是事物或客户端，<DeviceID> 可以是您的物联网事物名称或 MQTT 客户端 ID。

    注意

    在命令响应主题中，<PayloadFormat> 只能是 JSON 或 CBOR。

    $aws/commands/<devices>/<DeviceID>/executions/<ExecutionId>/response/<PayloadFormat>
  3. （可选）检索命令执行结果

    要检索命令执行的结果，您可以从 AWS IoT 控制台查看命令历史记录，或使用 GetCommandExecution 控制面板 API 操作。要获取最新信息，您的设备必须已将命令执行结果发布到命令响应主题。您还可以获取有关执行数据的附加信息，例如最后更新时间、执行结果以及执行完成时间。

（可选）启用命令事件通知

您可以订阅命令事件，以便在命令执行状态更改时接收通知。以下步骤显示如何订阅命令事件，然后处理它们。

  1. 创建主题规则

    您可以订阅命令事件主题，并在命令执行状态更改时接收通知。您还可以创建主题规则，将设备处理的数据路由到规则支持的其他 AWS IoT 服务，例如 AWS Lambda、Amazon SQS 和 AWS Step Functions。您可以使用 AWS IoT 控制台或 CreateTopicRule AWS IoT Core 控制面板 API 操作创建主题规则。有关更多信息，请参阅 创建 AWS IoT 规则。

    在此示例中，将 <CommandID> 替换为您要接收通知的命令的标识符，并将 <CommandExecutionStatus> 替换为命令执行的状态。

    $aws/events/commandExecution/<CommandID>/<CommandExecutionStatus>
    注意

    要接收所有命令和命令执行状态的通知，您可以使用通配符并订阅以下主题。

    $aws/events/commandExecution/+/#
  2. 接收和处理命令事件

    如果您在上一步中创建了主题规则来订阅命令事件，那么您可以管理收到的命令推送通知，并基于这些服务构建应用程序。

以下代码显示了您将收到的命令事件通知的示例有效载荷。

{
    "executionId": "2bd65c51-4cfd-49e4-9310-d5cbfdbc8554",
    "status":"FAILED",
    "statusReason": {
         "reasonCode": "DEVICE_TOO_BUSY",
         "reasonDescription": ""
    },
    "eventType": "COMMAND_EXECUTION",
    "commandArn":"arn:aws:iot:us-east-1:123456789012:command/0b9d9ddf-e873-43a9-8e2c-9fe004a90086",
    "targetArn":"arn:aws:iot:us-east-1:123456789012:thing/5006c3fc-de96-4def-8427-7eee36c6f2bd",
    "timestamp":1717708862107
}