View a markdown version of this page

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

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

High-level 命令工作流程

此工作流程显示设备如何与 AWS IoT Device Management 命令交互。所有 HTTP API 请求都使用 Sigv4 凭据进行签名。

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

创建和管理命令

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

  1. 创建命令资源

    从命令中心或使用 CreateCommand API 创建命令。

  2. 指定有效载荷

    提供任何格式的有效负载。指定内容类型以确保正确的设备解释。

    对于带有有效负载模板的动态命令，最终负载将在运行时使用您提供的参数生成。模板仅支持 JSON 格式，但生成的负载可以作为 JSON 或 CBOR 发送。

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

    创建后更新显示名称和描述。不再需要时将命令标记为已过时，或将其永久删除。要修改负载信息，请创建新命令。

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

选择目标设备并配置 MQTT 主题以接收命令和发布响应。

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

    选择目标设备来接收和执行命令。对已注册的设备使用事物名称，对未注册的设备使用客户端 ID。有关更多信息，请参阅 目标设备注意事项。

  2. 配置 AWS IoT 设备政策

    配置 IAM 策略，授予接收执行和发布更新的权限。IAM 策略示例有关政策示例，请参见。

  3. 建立 MQTT 连接

    将设备连接到消息代理并订阅请求和响应主题。设备需要iot:Connect许可。使用 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>字段。要获取负载格式，我们建议您使用 MQTT5 从 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. 在目标设备上启动命令执行

    从 C ommand Hub 开始执行，或者将 StartCommandExecution API 与您的账户特定终端节点一起使用。仅iot:Data-ATS用于双栈 (IPv4/IPv6) 或 IPv4 iot:Jobs。

    API 将负载发布到命令请求主题。

    注意

    如果设备处于离线状态并使用 MQTT 持久会话，则命令将在消息代理处等待。当设备在超时之前重新连接时，它可以处理命令并发布结果。如果超时到期，则执行超时，有效负载将被丢弃。

  2. 更新命令执行的结果

    设备使用基于 UpdateCommandExecution MQTT 的 API 接收负载、处理命令、执行指定操作并向命令响应主题发布结果。如果订阅了接受和拒绝的主题，则设备会收到确认云服务接受还是拒绝了响应。

    根据您在请求主题中指定的内容，<devices>可以是事物或客户端，<DeviceID>可以是您的 AWS IoT 事物名称或 MQTT 客户端 ID。

    注意

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

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

    从 AWS IoT 控制台或使用检索执行结果GetCommandExecution。设备必须将结果发布到命令响应主题以获取最新信息。查看其他详细信息，包括上次更新时间、结果和完成时间。

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

订阅命令事件，以便在执行状态发生变化时收到通知。有关命令执行事件的详细信息，包括事件消息格式和负载属性，请参阅命令执行事件。

  1. 创建主题规则

    订阅命令事件主题以获取状态更改通知。创建主题规则，使用 AWS IoT 控制台或创建一个 AWS IoT 规则，将设备数据路由到其他 AWS IoT 服务 AWS Lambda，如 Amazon SQS 和 AWS Step Functions。

    在此示例中，将 <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
}