本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # AWS IoT Device Management 命令 **重要** 本文档介绍如何在 [AWS IoT Device Management中使用命令功能](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command-concepts.html#command-iot-namespace)。有关为 AWS IoT FleetWise使用此功能的信息，请参阅[远程命令](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-commands.html)。 您全权负责以安全且符合适用法律的方式部署命令。有关您责任的更多信息，请参阅 [AWS IoT 服务的AWS 服务条款](https://aws.amazon.com/service-terms/)。 使用 AWS IoT Device Management 命令将指令从云端发送到连接到的设备 AWS IoT。命令一次只能针对一台设备，可用于低延迟、高吞吐量的应用程序，例如检索设备端日志或启动设备状态更改。 该*命令*是可重复使用的资源，由管理 AWS IoT Device Management。它包含在发布到设备之前应用的配置。您可以为特定用例预定义一组命令，例如打开灯泡或解锁车门。 AWS IoT 命令功能使您能够： + 使用静态或动态负载创建可重复使用的命令模板，然后在特定设备上执行这些模板。 + 目标设备注册为 AWS IoT 事物或未注册的 MQTT 客户端。 + 在同一台设备上同时运行多个命令。 + 启用事件通知并在设备处理命令时跟踪执行状态。 以下主题向您展示如何创建命令、将其发送到设备以及检索设备报告的状态。 **Topics** + [快速入门](iot-commands-quickstart.md) + [命令概念和状态](iot-remote-command-concepts.md) + [高级命令工作流程](iot-remote-command-workflow.md) + [创建和管理命令](iot-remote-command-create-manage.md) + [启动和监控命令执行](iot-remote-command-execution-start-monitor.md) + [弃用命令资源](iot-remote-command-deprecate.md) # 快速入门 完成以下步骤以发送您的第一个命令： 1. **先决条件**-确保您已登录 IoT Core、连接到 IoT Core 的设备、Commands API 操作的 IAM 权限以及设备上安装的 MQTT 客户端库。 1. **创建命令**-使用静态负载或指定设备操作的有效载荷模板定义命令。请参阅[创建命令资源](iot-remote-command-create-manage.md#iot-remote-command-create)。 1. **识别您的设备**-将您的设备注册为物联网设备或记下其 MQTT 客户端 ID。请参阅[目标设备注意事项](iot-remote-command-execution-start-monitor.md#iot-command-execution-target)。 1. **配置权限**-设置 IAM 策略，允许您的设备接收命令和发布响应。 1. **订阅主题**-将您的设备配置为订阅命令请求和响应主题。请参阅[为您的命令选择目标设备并订阅 MQTT 主题](iot-remote-command-workflow.md#command-choose-target)。 1. **执行命令**-在目标设备上开始执行命令。请参阅[启动命令执行启动命令执行（控制台）启动命令执行 (AWS CLI)](iot-remote-command-execution-start-monitor.md#iot-remote-command-execution-start)。 **常见用例：** + *远程诊断*-检索日志、运行诊断、检查设备运行状况 + *配置更新*-更改设置、更新参数、切换功能 + *设备控制*-Lock/unlock, power on/off，模式更改 # 命令概念和状态 使用 AWS IoT 命令将指令从云端发送到连接的设备。要使用此功能，请执行以下操作： 1. 创建一条包含在设备上运行所需的配置的有效载荷的命令。 1. 指定将接收有效负载并执行操作的目标设备。 1. 在目标设备上执行命令并检索状态信息。要对问题进行故障排除，请参阅 CloudWatch 日志。 有关工作流的更多信息，请参阅 [高级命令工作流程](iot-remote-command-workflow.md)。 **Topics** + [命令关键概念](#iot-command-concepts) + [命令状态](#iot-command-states) + [命令执行状态](#iot-command-execution-status) ## 命令关键概念 以下关键概念可帮助您理解命令功能。在本文档中，术语的使用始终如一： + *命令*-定义设备指令的可重复使用的模板 + *执行*-在设备上运行的命令的实例 + *事物名称*-在 IoT 注册表中注册的设备的标识符 + *客户端 ID*-未注册设备的 MQTT 标识符 + P@@ *ayload*-发送到设备的指令数据 + *主题*-用于命令通信的 MQTT 通道 **命令** 命令是以 MQTT 消息的形式从云端发送到您的物联网设备的指令。收到有效载荷后，设备会处理指令并采取相应的操作，例如修改配置设置、传输传感器读数或上传日志。然后，设备将结果返回到云端，从而实现远程监控和控制。 **命名空间** 创建命令时，请指定其命名空间。对于 AWS IoT Device Management 命令，请使用默认`AWS-IoT`命名空间并提供有效负载或 PayloadTemplate。对于 AWS IoT FleetWise 命令，请使用`AWS-IoT-FleetWise`命名空间。有关更多信息，请参阅《*AWS IoT FleetWise 开发人员指南*》中的[远程命令](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-commands.html)。 **有效载荷** 创建命令时，请提供用于定义设备必须执行的操作的静态负载。有效载荷可以使用任何支持的格式。为确保设备正确解释有效负载，我们建议指定有效负载格式类型。使用该 MQTT5 协议的设备可以遵循 MQTT 标准来识别格式。JSON 或 CBOR 的格式指示器可在命令请求主题中找到。 **有效载荷模板** 负载模板定义了带有占位符的命令有效负载，这些占位符会根据您提供的参数值在运行时生成不同的负载。例如，与其为不同的温度值创建单独的负载，不如创建一个带有温度占位符的模板并在执行期间指定该值。这样就无需维护多个相似的有效载荷。 **目标设备** 要执行命令，请使用目标设备的事物名称（对于注册的设备 AWS IoT）或 MQTT 客户端 ID（对于未注册的设备）来指定目标设备。客户端 ID 是在用于连接设备的[MQTT](mqtt.md)协议中定义的唯一标识符 AWS IoT。有关更多信息，请参阅 [目标设备注意事项](iot-remote-command-execution-start-monitor.md#iot-command-execution-target)。 **命令主题** 在执行命令之前，设备必须订阅命令请求主题。当您执行命令时，会将有关此主题的有效负载发送到设备。执行后，设备会将结果和状态发布到命令响应主题。有关更多信息，请参阅 [命令主题](reserved-topics.md#reserved-topics-commands)。 **命令执行** 执行是在目标设备上运行的命令的实例。当您开始执行时，有效负载将传送到设备并生成一个唯一的执行 ID。设备执行命令并向报告进度。 AWS IoT设备端逻辑决定执行行为和向保留主题报告的状态。 ### 参数值条件 使用负载模板创建命令时，请在执行前定义值条件以验证参数值。值条件可确保参数满足要求，防止无效执行。 **按[CommandParameterValue](https://docs.aws.amazon.com//iot/latest/apireference/API_CommandParameterValue.html)类型划分的支持的运算符** **数值类型（整数、长整型、双精度、无符号长整型）** + `EQUALS`-值必须等于指定的数字 + `NOT_EQUALS`-值不得等于指定的数字 + `GREATER_THAN`-值必须大于指定的数字 + `GREATER_THAN_EQUALS`-值必须大于或等于指定的数字 + `LESS_THAN`-值必须小于指定数字 + `LESS_THAN_EQUALS`-值必须小于或等于指定数字 + `IN_RANGE`-值必须在指定范围内（含） + `NOT_IN_RANGE`-值必须超出指定范围（含） + `IN_SET`-值必须与指定数字之一匹配 + `NOT_IN_SET`-值不得与任何指定数字匹配 **字符串类型（字符串）** + `EQUALS`-值必须等于指定的字符串 + `NOT_EQUALS`-值不得等于指定的字符串 + `IN_SET`-值必须与指定字符串之一匹配 + `NOT_IN_SET`-值不得与任何指定字符串匹配 **布尔类型** + 不支持值条件 **二进制类型** + 不支持值条件 **示例：温度控制命令** ``` { "commandId": "SetTemperature", "namespace": "AWS-IoT", "payloadTemplate": "{\"temperature\": \"${aws:iot:commandexecution::parameter:temperature}\"}", "parameters": [ { "name": "temperature", "type": "INTEGER", "valueConditions": [ { "comparisonOperator": "IN_RANGE", "operand": { "numberRange": { "min": "60", "max": "80" } } } ] } ] } ``` 在此示例中，`temperature`参数必须介于 60 和 80（含）之间。值超出此范围的执行请求验证失败。 **注意** 值条件是在调用 [StartCommandExecution API](https://docs.aws.amazon.com//iot/latest/apireference/API_iot-jobs-data_StartCommandExecution.html) 时评估的。验证失败会返回错误并阻止执行创建。 ### 参数值优先级和评估 使用有效负载模板开始执行命令时，将使用以下优先级解析参数值： 1. **执行请求参数**-`StartCommandExecution` 请求中提供的值具有最高优先级 1. **命令默认值**-如果执行请求中未提供参数，`defaultValue`则使用该参数的默认值 1. **无值**-如果两者均未提供，则执行失败，因为这是生成执行请求所需的参数 值条件是在创建执行之前，根据上面根据优先级派生的最终参数值进行评估的。如果验证失败，则执行请求将返回错误。 **示例： SetTemperature 带有 `defaultValue`** ``` { "parameters": [ { "name": "temperature", "type": "INTEGER", "defaultValue": {"I": 72}, "valueConditions": [ { "comparisonOperator": "IN_RANGE", "operand": {"numberRange": {"min": "60", "max": "80"}} } ] } ] } ``` 开始执行时： + 如果您在请求`"temperature": {"I": 75}`中提供，则使用 75 + 如果省略温度参数，则使用默认值 72 + 两个值均根据范围条件 [60,80] 进行验证 ## 命令状态 您的命令 AWS 账户 可以处于以下三种状态之一：“*可*用”、“*已弃用*” 或 “*待删除*”。 **可用** 成功创建后，命令将处于 “可用” 状态，可以在设备上执行。 **已弃用** 当不再需要时，将命令标记为已弃用。已弃用的命令无法启动新的执行，但待执行会继续完成。要启用新的执行，请将命令恢复到 “可用” 状态。 **待删除** 将命令标记为删除时，如果不推荐使用的命令超过最大超时时间（默认值：12 小时），则该命令将被自动删除。此操作是永久性的。如果在超时时间内未被弃用或弃用，则该命令将进入待删除状态，并在超时到期后被删除。 ## 命令执行状态 当您在目标设备上开始执行时，它会进入`CREATED`状态，并且可以根据设备报告过渡到其他状态。您可以检索状态信息并跟踪执行情况。 **注意** 您可以在一台设备上同时运行多个命令。使用并发控制来限制每台设备的执行次数并防止过载。有关每台设备的最大并发执行次数，请参阅[AWS IoT Device Management 命令配额](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#commands-limits)。 下表显示了执行状态及其基于执行进度的转换。 **命令执行状态和来源** | 命令执行状态 | 由设备/云端发起？ | 是否为终端执行？ | 允许的状态转换 | | --- | --- | --- | --- | | CREATED | 云 | 否 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot/latest/developerguide/iot-remote-command-concepts.html) | | IN\$1PROGRESS | 设备 | 否 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot/latest/developerguide/iot-remote-command-concepts.html) | | TIMED\$1OUT | 设备和云 | 否 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot/latest/developerguide/iot-remote-command-concepts.html) | | SUCCEEDED | 设备 | 是 | 不适用 | | FAILED | 设备 | 是 | 不适用 | | REJECTED | 设备 | 是 | 不适用 | 设备可以随时使用命令保留的 MQTT 主题发布状态和结果更新。为了提供更多上下文，设备可以在`statusReason`对象中使用`reasonCode`和`reasonDescription`字段。 下图显示了执行状态的转换。 ![\[该图显示了命令执行状态如何在各种状态之间转换。\]](http://docs.aws.amazon.com/zh_cn/iot/latest/developerguide/images/command-execution-status-transitions.png) **注意** 当在超时时间内 AWS IoT 检测到设备没有响应时，它会将其设置`TIMED_OUT`为临时状态，允许重试和状态更改。如果您的设备明确报告`TIMED_OUT`，则此状态将变为终端状态，无需进一步转换。有关更多信息，请参阅 [非终端命令执行](#iot-command-execution-status-nonterminal)。 以下各节描述了终端和非终端执行及其状态。 **Topics** + [非终端命令执行](#iot-command-execution-status-nonterminal) + [终端命令执行](#iot-command-execution-status-terminal) ### 非终端命令执行 如果执行可以接受来自设备的更新，则该执行是非终止的。非终止执行被视为处于*活动状态*。以下状态为非终端状态： + **CREATED** 当您从 AWS IoT 控制台开始执行或使用 `StartCommandExecution` API 时，成功的请求会将状态更改为`CREATED`。从此状态开始，执行可以过渡到任何其他非终端或终端状态。 + **进行中** 收到有效载荷后，设备可以开始执行指令并执行指定的操作。执行时，设备可以发布对命令响应主题的响应并将状态更新为`IN_PROGRESS`。从开始`IN_PROGRESS`，执行可以过渡到任何终端或非终端状态，除外`CREATED`。 **注意** `UpdateCommandExecution`API 可以多次调用，`IN_PROGRESS`状态为状态。使用`statusReason`对象指定其他执行细节。 + **超时** 云端和设备都可以触发此状态。由于以下原因，处于`CREATED`或`IN_PROGRESS`状态`TIMED_OUT`的执行可能会更改为： + 发送命令后，计时器启动。如果设备在指定的持续时间内没有响应，则云的状态会更改为`TIMED_OUT`。在这种情况下，执行是非终止的。 + 设备可以将状态改写为任何终端状态，或者报告超时并将状态设置为`TIMED_OUT`。在这种情况下，状态保持不变`TIMED_OUT`，但`StatusReason`对象字段会根据设备信息而变化。执行变为终止。 有关更多信息，请参阅 [超时值和 `TIMED_OUT` 执行状态](iot-remote-command-execution-start-monitor.md#iot-command-execution-timeout-status)。 ### 终端命令执行 当执行不再接受来自设备的更新时，该执行将变为终止。以下状态是终端的。执行可以从任何非终端状态转换为终端状态：`CREATED``IN_PROGRESS`、或。`TIMED_OUT` + **SUCCEEDED** 如果设备成功完成执行，它可以发布对命令响应主题的响应并将状态更新为`SUCCEEDED`。 + **FAILED** 当设备无法完成执行时，它可以发布对命令响应主题的响应并将状态更新为`FAILED`。使用`statusReason`对象或 CloudWatch 日志中的`reasonCode`和`reasonDescription`字段对故障进行故障排除。 + **REJECTED** 当设备收到无效或不兼容的请求时，它可以调用带有状态`UpdateCommandExecution`的 API `REJECTED`。使用`statusReason`对象或 CloudWatch 日志中的`reasonCode`和`reasonDescription`字段对问题进行故障排除。 # 高级命令工作流程 此工作流程显示设备如何与 AWS IoT Device Management 命令交互。所有 HTTP API 请求都使用 [Sigv4 凭据](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html)进行签名。 ![\[AWS IoT Device Management 设备命令高级工作流程概述。\]](http://docs.aws.amazon.com/zh_cn/iot/latest/developerguide/images/device-command-workflow.png) **Topics** + [创建和管理命令](#command-create-command) + [为您的命令选择目标设备并订阅 MQTT 主题](#command-choose-target) + [为目标设备启动和监控命令执行](#command-command-executions) + [（可选）启用命令事件通知](#iot-remote-command-commands-notifications) ## 创建和管理命令 要为您的设备创建和管理命令，请执行以下步骤。 1. **创建命令资源** 从[命令中心](https://console.aws.amazon.com/iot/home#/commandHub)或使用 [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html)API 创建命令。 1. **指定有效载荷** 提供任何格式的有效载荷。指定内容类型以确保设备解释正确。 对于带有有效载荷模板的动态命令，将在运行时使用您提供的参数生成最终有效负载。模板仅支持 JSON 格式，但生成的负载可以作为 JSON 或 CBOR 发送。 1. **（可选）管理已创建的命令** 创建后更新显示名称和描述。不再需要时将命令标记为已弃用，或者将其永久删除。要修改负载信息，请创建新命令。 ## 为您的命令选择目标设备并订阅 MQTT 主题 选择您的目标设备并配置 MQTT 主题以接收命令和发布响应。 1. **为您的命令选择目标设备** 选择要接收和执行命令的目标设备。对于已注册的设备，使用事物名称，对未注册的设备使用客户端 ID。有关更多信息，请参阅 [目标设备注意事项](iot-remote-command-execution-start-monitor.md#iot-command-execution-target)。 1. **配置 AWS IoT 设备策略** 配置 IAM 策略，授予接收执行和发布更新的权限。[IAM 策略示例](iot-remote-command-execution-start-monitor.md#iot-remote-command-execution-update-policy)有关策略示例，请参阅。 1. **建立 MQTT 连接** 将设备连接到消息代理并订阅请求和响应主题。设备需要`iot:Connect`许可。使用 `DescribeEndpoint` API 或 `describe-endpoint` CLI 命令查找您的数据平面终端节点： ``` aws iot describe-endpoint --endpoint-type iot:Data-ATS ``` 运行此命令将返回账户特定的数据面板端点，如下所示。 ``` account-specific-prefix.iot.region.amazonaws.com ``` 1. **订阅命令主题** 订阅命令请求主题。当您开始执行时，消息代理会将有效负载发布到此主题。您的设备接收并处理该命令。 （可选）订阅响应主题（`accepted`或`rejected`），以接收云服务接受还是拒绝设备响应的确认信息。 在此示例中： + *``* 与 `thing` 或 `client`，具体取决于您目标设备是已注册为物联网事物，还是指定为 MQTT 客户端。 + *``* 与您目标设备的唯一标识符。此 ID 可以是唯一的 MQTT 客户端 ID 或事物名称。 **注意** 如果有效负载类型不是 JSON 或 CBOR，则命令请求主题中可能不存在该**字段。要获取有效负载格式，我们建议您使用 MQTT5 从 MQTT 消息标头中获取格式信息。有关更多信息，请参阅 [命令主题](reserved-topics.md#reserved-topics-commands)。 ``` $aws/commands///executions/+/request/ $aws/commands///executions/+/response/accepted/ $aws/commands///executions/+/response/rejected/ ``` ## 为目标设备启动和监控命令执行 创建命令并指定命令的目标后，您可以通过执行以下步骤在目标设备上开始执行。 1. **在目标设备上启动命令执行** 从 C [ommand Hub](https://console.aws.amazon.com/iot/home#/commandHub) 开始执行，或者将 `StartCommandExecution` API 与您的账户专用端点一起使用。`iot:Data-ATS`用于双堆栈 (IPv4/IPv6) 或 IPv4 仅`iot:Jobs`用于双堆栈。 API 将负载发布到命令请求主题。 **注意** 如果设备处于离线状态并使用 MQTT 持久会话，则命令将在消息代理处等待。当设备在超时之前重新连接时，它可以处理命令并发布结果。如果超时到期，则执行超时，有效负载将被丢弃。 1. **更新命令执行的结果** 设备接收负载，处理命令，执行指定操作，并使用基于 `UpdateCommandExecution` MQTT 的 API 将结果发布到命令响应主题。如果订阅了已接受和已拒绝的主题，则设备会收到云服务接受还是拒绝响应的确认信息。 根据您在请求主题中指定的内容，**可以是事物或客户端，**可以是您的 AWS IoT 事物名称或 MQTT 客户端 ID。 **注意** 在命令响应主题中，**只能是 JSON 或 CBOR。 ``` $aws/commands///executions//response/ ``` 1. **（可选）检索命令执行结果** 从 AWS IoT 控制台或使用检索执行结果`GetCommandExecution`。设备必须将结果发布到命令响应主题以获取最新信息。查看其他详细信息，包括上次更新时间、结果和完成时间。 ## （可选）启用命令事件通知 订阅 Commands 事件，以便在执行状态发生变化时收到通知。有关命令执行事件的详细信息，包括事件消息格式和负载属性，请参阅[命令执行事件](command-events.md)。 1. **创建主题规则** 订阅命令事件主题以获取状态变更通知。使用控制台或创建主题规则，将设备数据路由到其他 AWS IoT 服务 AWS Lambda，例如 Amazon SQS 和 AWS Step Functi AWS IoT ons。[创建 AWS IoT 规则](iot-create-rule.md) 在此示例中，将 `` 替换为您要接收通知的命令的标识符，并将 `` 替换为命令执行的状态。 ``` $aws/events/commandExecution// ``` **注意** 要接收所有命令和命令执行状态的通知，您可以使用通配符并订阅以下主题。 ``` $aws/events/commandExecution/+/# ``` 1. **接收和处理命令事件** Manage Commands 使用订阅的事件推送通知和构建应用程序。 以下代码显示了您将收到的命令事件通知的示例有效载荷。 ``` { "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 } ``` # 创建和管理命令 使用 AWS IoT Device Management 命令配置可重复使用的远程操作或向设备发送即时指令。通过 AWS IoT 控制台或使用创建和管理命令 AWS CLI。 **Topics** + [创建命令资源](#iot-remote-command-create) + [检索关于命令的信息](#iot-remote-command-get) + [列出你中的命令 AWS 账户](#iot-remote-command-list) + [更新命令资源](#iot-remote-command-update) + [弃用或恢复命令资源](#iot-remote-command-deprecatecmd) + [删除命令资源](#iot-remote-command-delete) ## 创建命令资源 创建命令时提供以下信息： + **一般信息** 提供唯一的命令 ID，以便在目标设备上运行命令时识别该命令。（可选）指定用于管理的显示名称、描述和标签。 + **有效载荷** 对于静态命令，请提供定义设备操作的负载。指定 Payload 格式类型以便正确解释设备。 有关动态命令，请参阅 Payload 模板属性。 + **有效载荷模板** 对于动态命令，请提供包含占位符和参数的 PayloadTemplate。（可选）提供`defaultValue`和条件。 AWS IoT Device Management 命令会在运行时替换占位符。缺少的参数使用其默认值。所有值都必须满足定义的条件。 支持以下区分大小写的占位符类型： + `${aws:iot:commandexecution::parameter:parameter1}`— 名称`parameter1`为的参数值的占位符。 + `${aws:iot:commandexecution::executionTimeoutSec}`— 运行时提供的命令执行超时参数的占位符。 ### 有效载荷和命令主题 命令保留主题使用基于负载格式类型的格式。 + 对于`application/json`我们的`application/cbor`内容类型，请使用此请求主题： ``` $aws/commands///executions/+/request/ ``` + 对于其他内容类型或未指定格式，请使用此请求主题。有效负载格式显示在 MQTT 消息标头中。 ``` $aws/commands///executions/+/request ``` 无论负载类型如何，命令响应主题都使用`json`或`cbor`格式化。 **必须是`json`或`cbor`： ``` $aws/commands///executions//response/ ``` ### 创建命令资源（控制台） 以下各节介绍了 Payload 格式注意事项和通过控制台创建命令。 **Topics** + [静态命令有效载荷格式](#iot-commands-payload-format) + [动态命令有效载荷格式](#iot-commands-dynamic-payload-format) + [如何创建命令（控制台）](#iot-commands-console-how) #### 静态命令有效载荷格式 有效载荷支持任何不超过 32 KB 的格式。指定 Payload 格式类型以实现安全、正确的设备解释。 使用`type/subtype`格式（例如`application/json`或`application/cbor`）指定负载格式类型。默认值：`application/octet-stream`。有关支持的格式，请参阅[常用 MIME 类型](https://developer.mozilla.org/en-US/docs/Web/HTTP/MIME_types/Common_types)。 #### 动态命令有效载荷格式 PayloadTemplate 必须是有效的 JSON，至少有一个占位符，最多 32 KB。 对于`AwsJsonSubstitution`预处理器， AWS IoT Device Management 命令会根据预处理器配置以 JSON 或 CBOR 格式发送通知。 #### 如何创建命令（控制台） 要从控制台创建命令，请转到 C [ommand Hub](https://console.aws.amazon.com/iot/home#/commandHub) 并按照以下步骤操作： 1. 选择**创建命令**。 1. 指定唯一的命令 ID。 1. （可选）指定显示名称、描述和标签。 1. 上传包含设备操作的 Payload 文件。指定 Payload 格式类型以便正确解释设备。 1. （可选）对于带有占位符的 JSON 负载模板，参数会预先填充到行内表中以供编辑。 1. （可选）配置参数值类型（必填）、默认值和条件。 1. 选择**创建命令**。 ### 创建命令资源（CLI） 使用 [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html)AP [https://docs.aws.amazon.com/cli/latest/reference/iot/create-command.html](https://docs.aws.amazon.com/cli/latest/reference/iot/create-command.html)I 或 CLI 命令创建命令。 **Topics** + [命令有效载荷](#iot-commands-payload) + [IAM 策略示例](#iot-remote-command-create-iam) + [静态命令创建示例](#iot-remote-command-create-example) + [动态命令创建示例](#iot-remote-dynamic-command-create-example) #### 命令有效载荷 提供静态负载或负载模板。静态负载采用 base64 编码。对于负载模板，最终的有效载荷在运行时使用参数值生成。设备处理负载并执行指定的操作。指定 Payload 内容类型以便正确接收设备。 **注意** 命令创建后无法修改有效负载。创建新命令来修改有效负载。 #### IAM 策略示例 在使用此 API 操作之前，请确保您的 IAM 策略授权您对设备执行此操作。以下示例显示一个 IAM 策略，允许用户执行 `CreateCommand` 操作。 在此示例中： + 将 `region` 替换成您的 AWS 区域，例如 `us-east-1`。 + 将 `account-id` 替换成您的 AWS 账户 编号，例如 `123456789012`。 + `command-id`使用您的 AWS IoT 命令 ID 的唯一标识符，例如`LockDoor`。如果您想发送多个命令，可以在 IAM 策略的*资源*部分指定这些命令。 **** ``` { "Version":"2012-10-17", "Statement": { "Action": "iot:CreateCommand", "Effect": "Allow", "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id" } } ``` #### 静态命令创建示例 以下示例显示了如何创建静态命令。根据您的应用程序，进行以下替换： + 将 *``* 替换为命令的唯一标识符。例如，要锁上房屋的门，您可以指定*`LockDoor`*。我们建议您使用 UUID。您也可以使用字母数字字符、“-”和“\$1”。 + （可选）*``* 和 *``*，这些是可选字段，您可以使用它们为命令提供友好名称和有意义的描述，例如 *`Lock the doors of my home`*。 + `namespace`，您可以使用它来指定命令的命名空间。它必须是 `AWS-IoT`。有关使用此功能的信息 AWS IoT FleetWise，请参阅[远程命令](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-commands.html) + `payload` 包含关于您要在运行命令时使用的有效载荷及其内容类型的信息。 ``` aws iot create-command \ --command-id \ --display-name \ --description \ --namespace AWS-IoT \ --payload '{"content":"eyAibWVzc2FnZSI6ICJIZWxsbyBJb1QiIH0=","contentType":"application/json"}' ``` 运行此命令生成一个响应，其中包含命令的 ID 和 ARN（Amazon 资源名称）。例如，如果您在创建期间指定了 `LockDoor` 命令，以下显示运行命令的示例输出。 ``` { "commandId": "LockDoor", "commandArn": "arn:aws:iot:us-east-1:123456789012:command/LockDoor" } ``` #### 动态命令创建示例 以下示例显示了如何创建动态命令。根据您的应用程序，进行以下替换： + 将 *``* 替换为命令的唯一标识符。例如，要设置灯光电源状态，可以指定*`Light_Power_Status`*。我们建议您使用 UUID。您也可以使用字母数字字符、“-”和“\$1”。 + （可选）*``* 和 *``*，这些是可选字段，您可以使用它们为命令提供友好名称和有意义的描述，例如 *`Turn a light ON or OFF`*。 + `namespace`，您可以使用它来指定命令的命名空间。它必须是 `AWS-IoT`。有关使用此功能的信息 AWS IoT FleetWise，请参阅[远程命令](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-commands.html) + `payloadTemplate`包含带有占位符的 JSON 格式的 playoad 模板。 + `preprocessor`包含预处理器的配置，用于确定必须如何处理 PayloadTemplate。 + `mandatoryParameter`包含与 PayloadTemplate 中占位符对应的参数、其类型、默认值和条件。 ``` aws iot create-command \ --command-id Light_Power_Status \ --description "Turn a light ON or OFF" \ --namespace AWS-IoT \ --payload-template '{"powerStatus":"${aws:iot:commandexecution::parameter:powerStatus}"}' \ --preprocessor awsJsonSubstitution={outputFormat=JSON} \ --mandatory-parameters "name=powerStatus, defaultValue={S=OFF}, valueConditions=[{comparisonOperator=IN_SET, operand={strings=['ON','OFF']}}]" ``` 运行此命令生成一个响应，其中包含命令的 ID 和 ARN（Amazon 资源名称）。例如，如果您在创建期间指定了 `Light_Power_Status` 命令，以下显示运行命令的示例输出。 ``` { "commandId": "Light_Power_Status", "commandArn": "arn:aws:iot:us-east-1:123456789012:command/Light_Power_Status" } ``` ## 检索关于命令的信息 创建命令后，您可以从 AWS IoT 控制台和使用 AWS CLI检索关于它的信息。您可以获取以下信息。 + 命令 ID、Amazon 资源名称（ARN）、您为命令指定的任何显示名称和描述。 + 命令状态，指示命令是否可用于在目标设备上运行，或者是否已被弃用或正在删除。 + 您提供的有效负载或负载模板。 + 您提供的预处理器。 + 您提供的必填参数。 + 创建命令和上次更新命令的时间。 ### 检索命令资源（控制台） 要从控制台检索命令，请转到控制台的 AWS IoT C [ommand Hub](https://console.aws.amazon.com/iot/home#/commandHub)，然后选择您创建的命令以查看其详细信息。 除了命令详细信息外，您还可以看到命令历史，它提供关于命令在目标设备上执行的信息。在设备上运行此命令后，您可以在此选项卡上找到关于执行的信息。 ### 检索命令资源（CLI） 使用 [https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommand.html)HTTP 控制平面 API 操作或[https://docs.aws.amazon.com/cli/latest/reference/get-command.html](https://docs.aws.amazon.com/cli/latest/reference/get-command.html) AWS CLI 命令来检索有关命令资源的信息。您必须已经使用 `CreateCommand` API 请求或 `create-command` CLI 创建了命令。 #### IAM 策略示例 在使用此 API 操作之前，请确保您的 IAM 策略授权您对设备执行此操作。以下示例显示一个 IAM 策略，允许用户执行 `GetCommand` 操作。 在此示例中： + 将 `region` 替换成您的 AWS 区域，例如 `us-east-1`。 + 将 `account-id` 替换成您的 AWS 账户 编号，例如 `123456789023`。 + `command-id`使用您的 AWS IoT 唯一命令标识符，例如`LockDoor`或`Light_Power_Status`。如果您想检索多个命令，可以在 IAM 策略的*资源*部分指定这些命令。 **** ``` { "Version":"2012-10-17", "Statement": { "Action": "iot:GetCommand", "Effect": "Allow", "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id" } } ``` #### 检索命令示例 (AWS CLI) 以下示例说明如何使用检索命令的相关信息`get-command` AWS CLI。根据您的应用程序，将 *``* 替换为您要检索信息的命令的标识符。您可以从 `create-command` CLI 的响应中获取此信息。 ``` aws iot get-command --command-id ``` 运行此命令生成一个响应，其中包含关于命令、有效载荷以及它被创建和最后更新时间的信息。它还提供指示命令是否已被弃用或正在删除的信息。 例如，以下代码显示一个示例响应。 ``` { "commandId": "LockDoor", "commandArn": "arn:aws:iot:::command/LockDoor", "namespace": "AWS-IoT", "payload":{ "content": "eyAibWVzc2FnZSI6ICJIZWxsbyBJb1QiIH0=", "contentType": "application/json" }, "createdAt": "2024-03-23T00:50:10.095000-07:00", "lastUpdatedAt": "2024-03-23T00:50:10.095000-07:00", "deprecated": false, "pendingDeletion": false } ``` ## 列出你中的命令 AWS 账户 创建命令后，您可以查看您在账户中创建的命令。在列表中，您可以找到关于以下信息： + 命令 ID，以及您为命令指定的任何显示名称。 + 命令的 Amazon 资源名称（ARN）。 + 命令状态，指示命令是否可用于在目标设备上运行，或者是否已被弃用。 **注意** 列表不显示正在从您的账户中删除的命令。如果命令待删除，您仍然可以使用它们的命令 ID 查看这些命令的详细信息。 + 创建命令和上次更新命令的时间。 ### 列出您账户中的命令（控制台） 在 AWS IoT 控制台中，您可以转到 Comm [and Hub，找到您创建的命令](https://console.aws.amazon.com/iot/home#/commandHub)列表及其详细信息。 ### 列出您账户中的命令（CLI） 要列出您创建的命令，请使用 [https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommands.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommands.html) API 操作或 [https://docs.aws.amazon.com/cli/latest/reference/iot/list-commands.html](https://docs.aws.amazon.com/cli/latest/reference/iot/list-commands.html) CLI。 #### IAM 策略示例 在使用此 API 操作之前，请确保您的 IAM 策略授权您对设备执行此操作。以下示例显示一个 IAM 策略，允许用户执行 `ListCommands` 操作。 在此示例中： + 将 `region` 替换成您的 AWS 区域，例如 `us-east-1`。 + 将 `account-id` 替换成您的 AWS 账户 编号，例如 `123456789012`。 **** ``` { "Version":"2012-10-17", "Statement": { "Action": "iot:ListCommands", "Effect": "Allow", "Resource": "arn:aws:iot:us-east-1:123456789012:command/*" } } ``` #### 列出您账户中的命令示例 以下命令说明如何列出您账户中的命令。 ``` aws iot list-commands --namespace "AWS-IoT" ``` 运行此命令会生成一个响应，其中包含您创建的命令列表、命令的创建时间以及最后更新时间。它还提供命令状态信息，指示命令是否已被弃用或可用于在目标设备上运行。有关不同状态和状态原因的更多信息，请参阅 [命令执行状态](iot-remote-command-concepts.md#iot-command-execution-status)。 ## 更新命令资源 创建命令后，您可以更新命令的显示名称和描述。 **注意** 命令的有效载荷无法更新。要更新此信息或使用修改后的有效载荷，您需要创建一个新命令。 ### 更新命令资源（控制台） 要从控制台更新命令，请转到控制台的 [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) 并执行以下步骤。 AWS IoT 1. 要更新现有命令资源，选择您要更新的命令，然后在**操作**下选择**编辑**。 1. 指定您要使用的显示名称和描述，以及任何作为命令标签的名称-值对。 1. 选择**编辑**以保存具有新设置的命令。 ### 更新命令资源（CLI） 使用[https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateCommand.html)控制平面 API 操作或更新命令资源。[https://docs.aws.amazon.com/cli/latest/reference/iot/update-command.html](https://docs.aws.amazon.com/cli/latest/reference/iot/update-command.html) AWS CLI 使用此 API，您可以： + 编辑您创建的命令的显示名称和描述。 + 弃用命令资源，或恢复已弃用的命令。 #### IAM 策略示例 在使用此 API 操作之前，请确保您的 IAM 策略授权您对设备执行此操作。以下示例显示一个 IAM 策略，允许用户执行 `UpdateCommand` 操作。 在此示例中： + 将 `region` 替换成您的 AWS 区域，例如 `us-east-1`。 + 将 `account-id` 替换成您的 AWS 账户 编号，例如 `123456789012`。 + 将 `command-id` 替换成您的 AWS IoT 唯一命令标识符，例如 `LockDoor`。如果您想检索多个命令，可以在 IAM 策略的*资源*部分指定这些命令。 **** ``` { "Version":"2012-10-17", "Statement": { "Action": "iot:UpdateCommand", "Effect": "Allow", "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id" } } ``` #### 更新关于命令的信息示例 (AWS CLI) 以下示例向您展示如何使用命令更新有关命令的信息。`update-command` AWS CLI 有关如何使用此 API 弃用或恢复命令资源的信息，请参阅 [更新命令资源（CLI）](iot-remote-command-deprecate.md#iot-remote-command-deprecate-cli)。 该示例说明您如何更新命令的显示名称和描述。根据您的应用程序，将 *``* 替换为您要检索信息的命令的标识符。 ``` aws iot update-command \ --command-id --displayname \ --description ``` 运行此命令会生成一个响应，其中包含关于命令的更新信息以及最后更新时间。以下代码显示一个示例请求和响应，用于更新关闭 AC 的命令的显示名称和描述。 ``` aws iot update-command \ --command-id \ --displayname \ --description ``` 运行此命令会生成以下响应。 ``` { "commandId": "LockDoor", "commandArn": "arn:aws:iot:us-east-1:123456789012:command/LockDoor", "displayName": "Secondary lock door", "description": "Locks doors to my home", "lastUpdatedAt": "2024-05-09T23:15:53.899000-07:00" } ``` ## 弃用或恢复命令资源 创建命令后，如果您不再想继续使用该命令，可以将其标记为已弃用。当您弃用一个命令时，所有待处理的命令执行将继续在目标设备上运行，直到它们达到终端状态。一旦命令被弃用，如果您想使用它（例如向目标设备发送新的命令执行），您必须恢复它。 **注意** 您无法编辑已弃用的命令，或为其运行任何新的执行。要在设备上运行新命令，您必须恢复它，以便命令状态更改为“*可用*”。 有关弃用和恢复命令的更多信息及其注意事项，请参阅 [弃用命令资源](iot-remote-command-deprecate.md)。 ## 删除命令资源 如果您不再想使用某个命令，可以将其从您的账户中永久删除。如果删除操作成功： + 如果命令已被弃用的持续时间超过 12 小时的最大超时时间，该命令将被立即删除。 + 如果命令未被弃用，或已被弃用的持续时间短于最大超时时间，该命令将处于 `pending deletion` 状态。它将在最大超时时间 12 小时后自动从您的账户中移除。 **注意** 即使有任何待处理的命令执行，该命令也可能被删除。该命令将处于待删除状态，并将自动从您的账户中移除。 ### 删除命令资源（控制台） 要从控制台删除命令，请转到控制台的 [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) 并执行以下步骤。 AWS IoT 1. 选择要删除的命令，然后在**操作**下选择**删除**。 1. 确认要删除该命令，然后选择**删除**。 该命令将被标记为待删除，并将在 12 小时后从您的账户中永久移除。 ### 删除命令资源（CLI） 使用 `DeleteCommand` HTTP 控制平面 API 操作或`delete-command` AWS CLI 命令删除命令资源。如果删除操作成功，您将看到 HTTP `statusCode` 状态码为 204 或 202，并且该命令将在最大超时持续时间 12 小时后自动从您的账户中删除。在状态码为 204 的情况下，表示该命令已被删除。 #### IAM 策略示例 在使用此 API 操作之前，请确保您的 IAM 策略授权您对设备执行此操作。以下示例显示一个 IAM 策略，允许用户执行 `DeleteCommand` 操作。 在此示例中： + 将 `region` 替换成您的 AWS 区域，例如 `us-east-1`。 + 将 `account-id` 替换成您的 AWS 账户 编号，例如 `123456789012`。 + 将 `command-id` 替换成您的 AWS IoT 唯一命令标识符，例如 `LockDoor`。如果您想检索多个命令，可以在 IAM 策略的*资源*部分指定这些命令。 **** ``` { "Version":"2012-10-17", "Statement": { "Action": "iot:DeleteCommand", "Effect": "Allow", "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id" } } ``` #### 删除命令示例 (AWS CLI) 以下示例说明如何使用该命令删除`delete-command` AWS CLI 命令。根据您的应用程序，将 *``* 替换为要删除的命令的标识符。 ``` aws iot delete-command --command-id ``` 如果 API 请求成功，则该命令会生成状态码 202 或 204。您可以使用 `GetCommand` API 来验证该命令是否已不在您的账户中。 # 启动和监控命令执行 创建命令后，在目标设备上开始执行。设备更新结果并将状态发布到 MQTT 保留主题。从您的账户中检索和监控执行状态。 使用 AWS IoT 控制台启动和监视命令，或 AWS CLI。 **Topics** + [启动命令执行](#iot-remote-command-execution-start) + [更新命令执行的结果](#iot-remote-command-execution-update) + [检索命令执行](#iot-remote-command-execution-get) + [使用 MQTT 测试客户端查看命令更新](#iot-remote-command-execution-update-mqtt) + [列出你的命令执行情况 AWS 账户](#iot-remote-command-execution-list) + [删除命令执行](#iot-remote-command-execution-delete) ## 启动命令执行 **重要** 您全权负责以安全且符合适用法律的方式部署命令。 在开始执行之前，请确保： + 您在 AWS IoT 命名空间中创建了一个包含负载信息的命令。启动执行时，设备会处理 Payload 指令并执行指定的操作。[创建命令资源](iot-remote-command-create-manage.md#iot-remote-command-create)有关命令创建，请参阅。 + 您的设备订阅了 MQTT 保留的命令主题。开始执行时，负载信息会发布到此保留的 MQTT 请求主题： **可以是 Things 或 MQTT 客户端。 **是事物名称或客户端 ID。支持的**值：JSON 和 CBOR。有关更多信息，请参阅 [命令主题](reserved-topics.md#reserved-topics-commands)。 ``` $aws/commands///executions/+/request/ ``` 对于非 JSON/CBOR**，请使用以下命令主题格式： ``` $aws/commands///executions/+/request ``` ### 目标设备注意事项 指定要接收和执行命令的目标设备。对已注册的设备使用事物名称，对未注册的设备使用客户端 ID。收到有效载荷后，设备执行命令并执行指定的操作。 #### AWS IoT 东西 目标设备可以是在注册 AWS IoT 表中注册的事物。这简化了设备搜索和管理。 从 [Connect 设备页面或使用将设备](https://console.aws.amazon.com/iot/home#/connect-overview)注册为事物[https://docs.aws.amazon.com/iot/latest/apireference/API_CreateThing.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateThing.html)。从 Thing [Hub 或使用中查找现有事](https://console.aws.amazon.com/iot/home#/thinghub)物[https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeThing.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeThing.html)。有关注册的详细信息，请参阅[使用注册表管理事物](https://docs.aws.amazon.com/iot/latest/developerguide/thing-registry)。 #### 客户端 ID 对于未注册的设备，请使用客户端 ID。 客户端 ID 是您分配给设备的唯一标识符。它在 MQTT 协议中定义，包含字母数字字符、下划线或破折号。连接的每台设备都 AWS IoT 需要一个唯一的客户端 ID。 **注意** 对于已注册的事物，客户端 ID 可以与事物名称相匹配。 当定位到特定的客户端 ID 时，设备必须 AWS IoT 使用该客户端 ID 进行连接才能接收有效负载。 客户端 ID 是设备在连接时使用的 MQTT 客户端 ID。 AWS IoT Core AWS IoT 使用此 ID 来识别设备并管理连接和订阅。 ### 命令执行超时注意事项 超时指定设备提供执行结果的持续时间（以秒为单位）。 创建执行后，计时器启动。如果设备离线或未能在超时时间内报告结果，则执行超时并显示状态`TIMED_OUT`。 默认值：10 秒。最长：12 小时。 #### 超时值和 `TIMED_OUT` 执行状态 云端和设备都可以报告超时。 发送命令后，计时器启动。如果在超时时间内没有设备响应，则云会将执行状态设置为，并`TIMED_OUT`附带原因代码`$NO_RESPONSE_FROM_DEVICE`。 在以下情况下会发生这种情况： + 设备在执行期间脱机。 + 设备未能在超时时间内完成执行。 + 设备未能在超时时间内报告状态。 在这种情况下，当从云端报告 `TIMED_OUT` 的执行状态时，命令执行是非终端的。您的设备可以发布响应，将状态改写为任何终端状态：`SUCCEEDED``FAILED`、或。`REJECTED`然后，命令执行变为终端，不接受任何进一步的更新。 您的设备还可以通过报告在执行命令时出现超时来更新云端启动的`TIMED_OUT`状态。在这种情况下，命令执行状态保持为`TIMED_OUT`，但会根据设备报告的信息更新`statusReason`对象。然后，命令执行变为终止，并且不接受进一步的更新。 #### 使用 MQTT 持久会话 您可以将 MQTT 持久会话配置为与 AWS IoT Device Management 命令功能配合使用。此功能在诸如您的设备离线并且您希望确保设备在超时持续时间之前重新上线时仍能接收命令并执行指定指令的情况下特别有用。 默认情况下，MQTT 持久会话到期时间设置为 60 分钟。如果您的命令执行超时配置为超过此持续时间的值，则运行时间超过 60 分钟的命令执行可能会被消息代理拒绝并失败。要运行持续时间超过 60 分钟的命令，您可以请求延长持续会话的到期时间。 **注意** 为确保正确使用 MQTT 持久会话功能，请将 Clean Start 标志设置为零。有关更多信息，请参阅 [MQTT 持久会话](https://docs.aws.amazon.com/iot/latest/developerguide/mqtt.html#mqtt-persistent-sessions)。 ### 启动命令执行（控制台） 要开始从控制台运行该命令，请转到控制台的 [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) 页面并执行以下步骤。 AWS IoT 1. 要运行您创建的命令，请选择**运行命令**。 1. 查看有关您创建的命令的信息，包括 MQTT 保留主题和参数（如果适用）。 对于动态命令，请输入参数值或将其保留为默认值。对于没有默认值的参数，您必须提供一个值，以便在此执行过程中发送。 1. 指定要接收和执行命令的目标设备。如果设备已注册，则可以将其指定为 AWS IoT 事物；如果您的设备尚未注册，则使用客户端 ID。 AWS IoT有关更多信息，请参阅 [目标设备注意事项](#iot-command-execution-target)。 1. （可选）为命令配置超时值，该值确定您希望该命令在超时之前运行的持续时间。如果您的命令需要运行超过 60 分钟，您可能必须增加 MQTT 持久会话的过期时间。有关更多信息，请参阅 [命令执行超时注意事项](#iot-command-execution-timeout)。 1. 选择 **Run command（运行命令）**。 ### 启动命令执行 (AWS CLI) 使用 [https://docs.aws.amazon.com/iot/latest/apireference/API_StartCommandExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_StartCommandExecution.html) HTTP 数据面板 API 操作来启动命令执行。API 请求和响应通过命令执行 ID 进行关联。设备完成命令执行后，它可以通过向命令响应主题发布消息来向云端报告状态和执行结果。对于自定义响应代码，您拥有的应用程序代码可以处理响应消息并将结果发布到 AWS IoT。 如果您的设备已订阅命令请求主题，则 `StartCommandExecution` API 将有效载荷消息发布到该主题。有效载荷可以使用您选择的任何格式。有关更多信息，请参阅 [命令有效载荷](iot-remote-command-create-manage.md#iot-commands-payload)。 ``` $aws/commands///executions/+/request/ ``` 如果有效负载格式不是 JSON 或 CBOR，则命令请求主题的格式如下所示。 ``` $aws/commands///executions/+/request ``` #### IAM 策略示例 在使用此 API 操作之前，请确保您的 IAM 策略授权您对设备执行此操作。以下示例显示一个 IAM 策略，允许用户执行 `StartCommandExecution` 操作。 在此示例中： + 将 `region` 替换成您的 AWS 区域，例如 `us-east-1`。 + 将 `account-id` 替换成您的 AWS 账户 编号，例如 `123456789012`。 + `command-id`使用 AWS IoT 命令的唯一标识符，例如`LockDoor`。如果您想发送多个命令，可以在 IAM 策略指定这些命令。 + `devices`使用`thing`或`client`取决于您的设备是已注册为 AWS IoT 事物还是被指定为 MQTT 客户端。 + `device-id`用你的 AWS IoT `thing-name`或`client-id`。 ``` { "Effect": "Allow", "Action": [ "iot:StartCommandExecution" ], "Resource": [ "arn:aws:iot:region:account-id:command/command-id", "arn:aws:iot:region:account-id:devices/device-id" ] } ``` 要查看支持的条件键列表`StartCommandExecution`，请参阅 *IAM 用户指南 AWS IoT*中的[条件密钥](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsiot.html#awsiot-policy-keys)。 #### 获取账户特定的数据面板端点 在运行 API 命令之前，您必须获取该端点的账户特定端点 URL。如果您使用的是双堆栈终端节点（IPv4和 IPv6），请使用。`iot:Data-ATS`终`iot:Jobs`端节点 IPv4 仅适用于。例如，如果您运行此命令： ``` aws iot describe-endpoint --endpoint-type iot:Data-ATS ``` 它会返回账户特定的终端节点 URL，如下面的示例响应所示。 ``` { "endpointAddress": "-ats.iot..api.com" } ``` #### 启动命令执行示例 (AWS CLI) 以下示例显示如何使用该命令开始执行`start-command-execution` AWS CLI 命令。 在此示例中： + 将 *``* 替换成您要执行的命令的 ARN。您可以从 `create-command` CLI 命令的响应中获取此信息。例如，如果您要执行更改方向盘模式的命令，请使用 `arn:aws:iot:region:account-id:command/SetComfortSteeringMode`。 + 将 *``* 替换成目标设备的事物 ARN，该设备可以是您要对其执行命令的物联网事物或 MQTT 客户端。例如，如果您要为目标设备 `myRegisteredThing` 执行命令，请使用 `arn:aws:iot:region:account-id:thing/myRegisteredThing`。 + 将 *``* 替换成您在 [获取账户特定的数据面板端点](#iot-remote-command-execution-start-endpoint) 中获取的账户特定端点，并以 `https://` 为前缀。例如 `https://123456789012abcd.jobs.iot.us-east-1.amazonaws.com`。 + （可选）您还可以在执行 `StartCommandExecution` API 操作时指定一个附加参数 `executionTimeoutSeconds`。此可选字段指定设备必须完成执行命令的时间（以秒为单位）。默认值为 10 秒。当命令执行状态为 `CREATED` 时，计时器启动。如果在计时器到期前未收到命令执行结果，则状态自动更改为 `TIMED_OUT`。 + ``` aws iot-jobs-data start-command-execution \ --command-arn \ --target-arn \ --endpoint \ --execution-timeout-seconds 900 ``` + （可选）对于动态命令，请指定用于替换的参数及其值。您必须为在创建命令时未设置 defaultValue 的参数提供一个值。如果参数具有 defaultValue，则此处提供的参数值优先。对于设置了 valueConditions 的参数，此处提供的参数值必须满足条件。 基于`Light_Power_Status`动态命令示例： + ``` aws iot-jobs-data start-command-execution \ --command-arn arn:aws:iot:us-east-1:123456789012:command/Light_Power_Status \ --target-arn arn:aws:iot:us-east-1:123456789012:thing/exampleThing \ --endpoint \ --execution-timeout-seconds 900 \ --parameters "powerStatus={S=ON}" ``` 运行此命令会返回一个命令执行 ID。您可以使用此 ID 查询命令执行状态、详细信息和命令执行历史记录。 **注意** 如果命令已被弃用，则 `StartCommandExecution` API 请求将失败并出现验证异常。要修复此错误，请首先使用 `UpdateCommand` API 恢复命令，然后执行 `StartCommandExecution` 请求。 ``` { "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542" } ``` ## 更新命令执行的结果 使用 `UpdateCommandExecution` MQTT 数据面板 API 操作更新命令执行的状态或结果。 **注意** 在使用此 API 之前： 您的设备必须已建立 MQTT 连接并订阅命令请求和响应主题。有关更多信息，请参阅 [高级命令工作流程](iot-remote-command-workflow.md)。 您必须已经使用 `StartCommandExecution` API 操作执行了此命令。 ### IAM 策略示例 在使用此 API 操作之前，请确保您的 IAM 策略授权您的设备执行这些操作。以下显示一个授权您的设备执行该操作的示例策略。有关允许用户执行 `UpdateCommandExecution` MQTT 操作的其他示例 IAM 策略，请参阅[连接和发布策略示例](connect-and-pub.md)。 在此示例中： + `Region`和你的 AWS 区域，比如`us-east-1`。 + 将 `AccountID` 替换成您的 AWS 账户 编号，例如 *`123456789012`*。 + `ThingName`用你要执行命令的 AWS IoT 东西的名称，例如*`myRegisteredThing`*。 + `commands-request-topic``commands-response-topic`以及您的 AWS IoT 命令、请求和响应主题的名称。有关更多信息，请参阅 [高级命令工作流程](iot-remote-command-workflow.md)。 #### MQTT 客户端 ID 的示例 IAM 策略 以下代码显示使用 MQTT 客户端 ID 时的示例设备策略。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iot:Publish", "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response", "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/json" ] }, { "Effect": "Allow", "Action": "iot:Receive", "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/request", "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/accepted", "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/rejected", "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/request/json", "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/accepted/json", "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/rejected/json" ] }, { "Effect": "Allow", "Action": "iot:Subscribe", "Resource": [ "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/request", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/accepted", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/rejected", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/request/json", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/accepted/json", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/rejected/json" ] }, { "Effect": "Allow", "Action": "iot:Connect", "Resource": "arn:aws:iot:us-east-1:123456789012:client/${iot:ClientId}" } ] } ``` #### IoT 事物的示例 IAM 策略 以下代码显示使用 AWS IoT 事物时的示例设备策略。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iot:Publish", "Resource": "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response" }, { "Effect": "Allow", "Action": "iot:Receive", "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/request", "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/accepted", "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/rejected", "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/request/json", "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/accepted/json", "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/rejected/json" ] }, { "Effect": "Allow", "Action": "iot:Subscribe", "Resource": [ "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/request", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/accepted", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/rejected", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/request/json", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/accepted/json", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/rejected/json" ] }, { "Effect": "Allow", "Action": "iot:Connect", "Resource": "arn:aws:iot:us-east-1:123456789012:client/${iot:ClientId}" } ] } ``` ### 如何使用 `UpdateCommandExecution` API 在请求主题收到命令执行后，设备处理该命令。然后，它使用 `UpdateCommandExecution` API 将命令执行的状态和结果更新为以下响应主题。 ``` $aws/commands///executions//response/ ``` 在此示例中，*``* 是您目标设备的唯一标识符，*``* 是目标设备上命令执行的标识符。**可以是 JSON 或 CBOR。 **注意** 如果您尚未在其中注册设备 AWS IoT，则可以使用客户端 ID 作为标识符而不是事物名称。 ``` $aws/commands/clients//executions//response/ ``` #### 设备报告的执行状态更新 您的设备可以使用 API 向命令执行报告以下任何状态更新。有关这些状态的更多信息，请参阅 [命令执行状态](iot-remote-command-concepts.md#iot-command-execution-status)。 + `IN_PROGRESS`：当设备开始执行命令时，它可以将状态更新为 `IN_PROGRESS`。 + `SUCCEEDED`：当设备成功处理命令并完成执行后，设备可以将消息作为 `SUCCEEDED` 发布到响应主题。 + `FAILED`：如果设备执行命令失败，它可以将消息作为 `FAILED` 发布到响应主题。 + `REJECTED`：如果设备接受命令失败，它可以将消息作为 `REJECTED` 发布到响应主题。 + `TIMED_OUT`：命令执行状态可因以下任何原因更改为 `TIMED_OUT`。 + 未收到命令执行结果。这可能是因为执行未在指定持续时间内完成，或者设备未能将状态信息发布到响应主题。 + 设备报告在尝试执行命令时发生超时。 有关 `TIMED_OUT` 状态的更多信息，请参阅 [超时值和 `TIMED_OUT` 执行状态](#iot-command-execution-timeout-status)。 #### 使用 `UpdateCommandExecution` API 时的注意事项 以下是使用 `UpdateCommandExecution` API 时的一些重要注意事项。 + 您的设备可以使用可选`statusReason`对象来提供有关执行的更多信息。如果您的设备提供此对象，则该对象的`reasonCode`字段为必填字段，但该`reasonDescription`字段为可选字段。 + 当您的设备使用`statusReason`对象时，`reasonCode`必须使用该模式，`[A-Z0-9_-]+`且长度不得超过 64 个字符。如果您提供`reasonDescription`，请确保其长度不超过 1,024 个字符。它可以使用除控制字符（如换行符）之外的任何字符。 + 您的设备可以使用一个可选的 `result` 对象来提供关于命令执行结果的信息，例如远程函数调用的返回值。如果您提供 `result`，它必须要求至少一个条目。 + 在 `result` 字段中，您将条目指定为键值对。对于每个条目，您必须将数据类型信息指定为字符串、布尔值或二进制。字符串数据类型必须使用键 `s`，布尔数据类型使用键 `b`，二进制数据类型必须使用键 `bin`。确保这些密钥为小写。 + 如果您在运行 `UpdateCommandExecution` API 时遇到错误，可以在 Amazon 的`AWSIoTLogsV2`日志组中查看错误 CloudWatch。有关启用日志记录和查看日志的信息，请参阅 [配置 AWS IoT 日志](configure-logging.md)。 #### `UpdateCommandExecution` API 示例 以下代码显示一个示例，说明您的设备如何使用 `UpdateCommandExecution` API 报告执行状态、使用 `statusReason` 字段提供有关状态的附加信息，以及使用结果字段提供有关执行结果的信息，例如本例中的汽车电池百分比。 ``` { "status": "IN_PROGRESS", "statusReason": { "reasonCode": "200", "reasonDescription": "Execution_in_progress" }, "result": { "car_battery": { "s": "car battery at 50 percent" } } } ``` ## 检索命令执行 运行命令后，您可以从 AWS IoT 控制台检索有关命令执行的信息，并使用 AWS CLI。您可以获取以下信息。 **注意** 要检索最新的命令执行状态，您的设备必须使用 `UpdateCommandExecution` MQTT API 将状态信息发布到响应主题，如下所述。在设备发布到此主题之前，`GetCommandExecution` API 会将状态报告为 `CREATED` 或 `TIMED_OUT`。 您创建的每个命令执行都将具有： + **执行 ID**，它是命令执行的唯一标识符。 + 代码执行输出的**状态**。当您在目标设备上运行命令时，命令执行进入 `CREATED` 状态。然后，它可以转换到其它命令执行状态，如下所述。 + 命令执行的**结果**。 + 唯一的**命令 ID** 和已为其创建执行的目标设备。 + **开始日期**，显示命令执行的创建时间。 ### 检索命令执行（控制台） 您可以使用以下任一方法从控制台检索命令执行。 + **从命令中心页面** 转到 AWS IoT 控制台的 [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) 页面并执行以下步骤。 1. 选择您在其目标设备上创建了执行的命令。 1. 在命令详细信息页面的**命令历史**选项卡上，您将看到您创建的执行。选择要检索信息的执行。 1. 如果您的设备使用 `UpdateCommandExecution` API 提供了结果信息，您可以在本页的**结果**选项卡中找到此信息。 + **从事物中心页面** 如果您在运行命令时选择了某 AWS IoT 件事作为目标设备，则可以从 Thing Hub 页面查看执行详细信息。 1. 转到 AWS IoT 控制台中的 Thin [g Hub](https://console.aws.amazon.com/iot/home#/thinghub) 页面，然后选择您为其创建命令执行的对象。 1. 在事物详细信息页面的**命令历史**上，您将看到您创建的执行。选择要检索信息的执行。 1. 如果您的设备使用 `UpdateCommandExecution` API 提供了结果信息，您可以在本页的**结果**选项卡中找到此信息。 ### 检索命令执行（CLI） 使用[https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommandExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommandExecution.html) AWS IoT Core 控制平面 HTTP API 操作来检索有关命令执行的信息。您必须已经使用 `StartCommandExecution` API 操作执行了此命令。 #### IAM 策略示例 在使用此 API 操作之前，请确保您的 IAM 策略授权您对设备执行此操作。以下示例显示一个 IAM 策略，允许用户执行 `GetCommandExecution` 操作。 在此示例中： + 将 `region` 替换成您的 AWS 区域，例如 `us-east-1`。 + 将 `account-id` 替换成您的 AWS 账户 编号，例如 `123456789012`。 + `command-id`使用您的唯一 AWS IoT 命令标识符，例如`LockDoor`。 + `devices`使用`thing`或`client`取决于您的设备是已注册为 AWS IoT 事物还是被指定为 MQTT 客户端。 + `device-id`用你的 AWS IoT `thing-name`或`client-id`。 ``` { "Effect": "Allow", "Action": [ "iot:GetCommandExecution" ], "Resource": [ "arn:aws:iot:region:account-id:command/command-id", "arn:aws:iot:region:account-id:devices/device-id" ] } ``` #### 检索命令执行示例 以下示例向您展示如何检索有关使用该命令执行的`start-command-execution` AWS CLI 命令的信息。以下示例显示如何检索有关已执行的、用于关闭方向盘模式的命令的信息。 在此示例中： + 将 *``* 替换成您要检索信息的命令执行的标识符。 + 将 *``* 替换成您要执行命令的目标设备的 Amazon 资源编号（ARN）。您可以从 `start-command-execution` CLI 命令的响应中获取此信息。 + 或者，如果您的设备使用 `UpdateCommandExection` API 提供了执行结果，您可以使用 `GetCommandExecution` API 指定是否在 `GetCommandExecution` API 的响应中包含命令执行结果。 ``` aws iot get-command-execution --execution-id \ --target-arn \ --include-result ``` 运行此命令会生成一个响应，其中包含有关命令执行的 ARN、执行状态、开始执行时间以及完成时间的信息。它还提供一个 `statusReason` 对象，其中包含有关状态的附加信息。有关不同状态和状态原因的更多信息，请参阅 [命令执行状态](iot-remote-command-concepts.md#iot-command-execution-status)。 以下代码显示 API 请求的示例响应。 **注意** 执行响应中的 `completedAt` 字段对应于设备向云端报告终端状态的时间。对于 `TIMED_OUT` 状态，仅当设备报告超时时，才会设置此字段。当 `TIMED_OUT` 状态由云端设置时，`TIMED_OUT` 状态不会更新。有关超时行为的更多信息，请参阅 [命令执行超时注意事项](#iot-command-execution-timeout)。 ``` { "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542", "commandArn": "arn:aws:iot:us-east-1:123456789012:command/LockDoor", "targetArn": "arn:aws:iot:us-east-1:123456789012:thing/myRegisteredThing", "status": "SUCCEEDED", "statusReason": { "reasonCode": "DEVICE_SUCCESSFULLY_EXECUTED", "reasonDescription": "SUCCESS" }, "result": { "sn": { "s": "ABC-001" }, "digital": { "b": true } }, "createdAt": "2024-03-23T00:50:10.095000-07:00", "completedAt": "2024-03-23T00:50:10.095000-07:00" } ``` ## 使用 MQTT 测试客户端查看命令更新 您可以使用 MQTT 测试客户端查看使用命令功能时通过 MQTT 进行的消息交换。在您的设备与建立 MQTT 连接后 AWS IoT，您可以创建命令，指定有效负载，然后在设备上运行该命令。运行命令时，如果您的设备订阅了 MQTT 保留的命令请求主题，则它会看到发布到该主题的有效载荷消息。 然后，设备接收有效载荷指令，并在 AWS IoT 设备上执行指定的操作。然后，它使用 `UpdateCommandExecution` API 将命令执行结果和状态信息发布到 MQTT 保留的命令响应主题。 AWS IoT Device Management 监听响应主题的更新并存储更新的信息，并将日志发布到 AWS CloudTrail 和 Amazon CloudWatch。然后，您可以从控制台或使用 `GetCommandExecution` API 检索最新的命令执行信息。 以下步骤显示如何使用 MQTT 测试客户端观察消息。 1. 在 AWS IoT 控制台中打开 [MQTT 测试客户端](https://console.aws.amazon.com/iot/home#/test)。 1. 在 “**订阅**” 选项卡上，输入以下主题，然后选择 “**订阅**”，其中**是您注册的设备的事物名称 AWS IoT。 **注意** 您可以从 AWS IoT 控制台的 Thing [Hub 页面找到设备的事物](https://console.aws.amazon.com/iot/home#/thinghub)名称。如果您尚未将设备注册为事物，则可以在 AWS IoT 从 [Connect 设备页面连接时注册该设备](https://console.aws.amazon.com/iot/home#/connect-overview)。 ``` $aws/commands/things//executions/+/request ``` 1. （可选）在**订阅**选项卡上，您还可以输入以下主题并选择**订阅**。 ``` $aws/commands/things/+/executions/+/response/accepted/json $aws/commands/things/+/executions/+/response/rejected/json ``` 1. 当您启动命令执行时，消息有效载荷将使用设备已订阅的请求主题 `$aws/commands/things//executions/+/request` 发送到设备。在 MQTT 测试客户端中，您应该看到包含设备处理命令指令的命令有效载荷。 1. 设备开始执行命令后，它可以将状态更新发布到以下 MQTT 命令保留响应主题。 ``` $aws/commands///executions//response/json ``` 例如，考虑一个您执行的命令，用于打开汽车的空调以将温度降低到期望值。以下 JSON 显示车辆发布到响应主题的示例消息，显示它未能执行该命令。 ``` { "deviceId": "My_Car", "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542", "status": "FAILED", "statusReason": { "reasonCode": "CAR_LOW_ON_BATTERY", "reasonDescription": "Car battery is lower than 5 percent" } } ``` 在这种情况下，您可以给汽车电池充电，然后再次运行该命令。 ## 列出你的命令执行情况 AWS 账户 运行命令后，您可以从 AWS IoT 控制台检索有关命令执行的信息，并使用 AWS CLI。您可以获取以下信息。 + **执行 ID**，它是命令执行的唯一标识符。 + 代码执行输出的**状态**。当您在目标设备上运行命令时，命令执行进入 `CREATED` 状态。然后，它可以转换到其它命令执行状态，如下所述。 + 唯一的**命令 ID** 和已为其创建执行的目标设备。 + **开始日期**，显示命令执行的创建时间。 ### 列出您账户中的命令执行（控制台） 您可以使用以下任一方法从控制台查看所有命令执行。 + **从命令中心页面** 转到 AWS IoT 控制台的 [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) 页面并执行以下步骤。 1. 选择您在其目标设备上创建了执行的命令。 1. 在命令详细信息页面中，转到**命令历史**选项卡，您将看到您创建的执行列表。 + **从事物中心页面** 如果您在运行命令时选择某 AWS IoT 物作为目标设备，并且为单个设备创建了多个命令执行，则可以从 Thing Hub 页面查看该设备的执行情况。 1. 转到 AWS IoT 控制台中的 Thing [Hub](https://console.aws.amazon.com/iot/home#/thinghub) 页面，然后选择您为其创建执行的事物。 1. 在事物详细信息页面的**命令历史**选项卡上，您将看到为该设备创建的执行列表。 ### 列出您账户中的命令执行（CLI） 使用[https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommandExecutions.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommandExecutions.html) AWS IoT Core 控制平面 HTTP API 操作列出您账户中的所有命令执行情况。 #### IAM 策略示例 在使用此 API 操作之前，请确保您的 IAM 策略授权您对设备执行此操作。以下示例显示一个 IAM 策略，允许用户执行 `ListCommandExecutions` 操作。 在此示例中： + 将 `region` 替换成您的 AWS 区域，例如 `us-east-1`。 + 将 `account-id` 替换成您的 AWS 账户 编号，例如 `123456789012`。 + `command-id`使用您的唯一 AWS IoT 命令标识符，例如`LockDoor`。 ``` { "Effect": "Allow", "Action": "iot:ListCommandExecutions", "Resource": * } ``` #### 列出命令执行示例 以下示例显示如何列出您 AWS 账户中的命令执行。 运行命令时，您必须指定是否筛选列表，以仅显示使用 `targetArn` 为特定设备创建的命令执行，或使用 `commandArn` 为特定命令指定的执行。 在此示例中： + *``* 与您要执行命令的目标设备的 Amazon 资源编号（ARN），例如 `arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f`。 + *``* 与您要执行命令的目标设备的 Amazon 资源编号（ARN），例如 `arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f`。 + *``* 与您希望列出在此时间之后创建的执行的时间，例如 `2024-11-01T03:00`。 ``` aws iot list-command-executions \ --target-arn \ --started-time-filter '{after=}' \ --sort-order "ASCENDING" ``` 运行此命令会生成一个响应，其中包含您创建的命令执行列表，以及执行开始和完成的时间。它还提供状态信息，以及包含有关状态附加信息的 `statusReason` 对象。 ``` { "commandExecutions": [ { "commandArn": "arn:aws:iot:us-east-1:123456789012:command/TestMe002", "executionId": "b2b654ca-1a71-427f-9669-e74ae9d92d24", "targetArn": "arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f", "status": "TIMED_OUT", "createdAt": "2024-11-24T14:39:25.791000-08:00", "startedAt": "2024-11-24T14:39:25.791000-08:00" }, { "commandArn": "arn:aws:iot:us-east-1:123456789012:command/TestMe002", "executionId": "34bf015f-ef0f-4453-acd0-9cca2d42a48f", "targetArn": "arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f", "status": "IN_PROGRESS", "createdAt": "2024-11-24T14:05:36.021000-08:00", "startedAt": "2024-11-24T14:05:36.021000-08:00" } ] } ``` 有关不同状态和状态原因的更多信息，请参阅 [命令执行状态](iot-remote-command-concepts.md#iot-command-execution-status)。 ## 删除命令执行 如果您不再想使用某个命令执行，可以将其从您的账户中永久删除。 **注意** 只有当命令执行进入终端状态（例如 `SUCCEEDED`、`FAILED` 或 `REJECTED`）时，才能将其删除。 此操作只能使用 AWS IoT Core API 或 AWS CLI。控制台不提供此操作。 ### IAM 策略示例 在使用此 API 操作之前，请确保您的 IAM 策略授权您的设备执行这些操作。以下显示一个授权您的设备执行该操作的示例策略。 在此示例中： + `Region`和你的 AWS 区域，比如`us-east-1`。 + 将 `AccountID` 替换成您的 AWS 账户 编号，例如 *`123456789012`*。 + 将 `CommandID` 替换成您要删除其执行的命令的标识符。 + `devices`使用`thing`或`client`取决于您的设备是已注册为 AWS IoT 事物还是被指定为 MQTT 客户端。 + `device-id`用你的 AWS IoT `thing-name`或`client-id`。 ``` { "Effect": "Allow", "Action": [ "iot:DeleteCommandExecution" ], "Resource": [ "arn:aws:iot:region:account-id:command/command-id", "arn:aws:iot:region:account-id:devices/device-id" ] } ``` ### 删除命令执行示例 以下示例说明如何使用命令删除`delete-command` AWS CLI 命令。根据您的应用程序，将 *``* 替换为您要删除的命令执行的标识符，并将 *``* 替换为您目标设备的 ARN。 ``` aws iot delete-command-execution \ --execution-id \ --target-arn ``` 如果 API 请求成功，则该命令执行会生成状态码 200。您可以使用 `GetCommandExecution` API 来验证该命令执行是否已不在您的账户中。 # 弃用命令资源 弃用命令以表明它们已过时且不应使用。例如，弃用不再主动维护的命令，或者在创建具有相同 ID 但负载不同的新命令时。 ## 重要注意事项 弃用命令时的重要注意事项： + 弃用命令并不能将其删除。您可以使用其 ID 检索命令，然后将其恢复以供重复使用。 + 尝试对已弃用的命令开始新的执行会生成错误，从而导致无法使用过时的命令。 + 要执行已弃用的命令，请先将其恢复。恢复后，该命令即可在目标设备上正常使用和执行。 + 如果您在执行过程中弃用了某个命令，则这些命令会继续运行直到完成。您仍然可以检索执行状态。 ## 弃用命令资源（控制台） 要弃用控制台中的命令，请转到控制台的 [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) 并执行以下步骤。 AWS IoT 1. 选择要弃用的命令，然后在 “**操作**” 下选择 “**弃用**”。 1. 确认您要弃用该命令，然后选择**弃用**。 ## 弃用命令资源（CLI） 使用 `update-command` CLI 将命令标记为已弃用。在删除命令之前，必须弃用命令。要使用已弃用的命令，请先将其恢复。 ``` aws iot update-command \ --command-id \ --deprecated ``` 例如，如果您弃用了在上例中更新的 `ACSwitch` 命令，以下代码显示运行该命令的示例输出。 ``` { "commandId": "turnOffAc", "deprecated": true, "lastUpdatedAt": "2024-05-09T23:16:51.370000-07:00" } ``` ## 检查弃用时间和状态 使用 `GetCommand` API 来确定命令是否已弃用以及上次弃用的时间。 ``` aws iot get-command --command-id ``` 此命令生成一个包含命令信息的响应，包括上次更新字段的创建和弃用时间戳。这有助于确定命令的生命周期以及是删除还是重复使用它。以下显示了该`turnOffAc`命令的示例响应： ``` { "commandId": "turnOffAC", "commandArn": "arn:aws:iot:us-east-1:123456789012:command/turnOffAC", "namespace": "AWS-IoT", "payload": { "content": "testPayload.json", "contentType": "application/json" }, "createdAt": "2024-03-23T00:50:10.095000-07:00", "lastUpdatedAt": "2024-05-09T23:16:51.370000-07:00", "deprecated": false } ``` ## 恢复命令资源 要使用命令或将`ACSwitch`命令发送到您的设备，请先将其恢复。 要从控制台恢复命令，请转到控制台的 C [ommand Hub](https://console.aws.amazon.com/iot/home#/commandHub)，选择要恢复的命令，然后在 “**操作**” 下选择 “**恢复**”。 AWS IoT 要使用 AWS IoT Core API 或，恢复命令 AWS CLI，请使用 `UpdateCommand` API 操作或 `update-command` CLI。以下代码显示了使用示例请求和响应。 ``` aws iot update-command \ --command-id --no-deprecated ``` 以下代码显示了示例输出。 ``` { "commandId": "ACSwitch", "deprecated": false, "lastUpdatedAt": "2024-05-09T23:17:21.954000-07:00" } ```