本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 启动和监控命令执行 创建命令后，在目标设备上开始执行。设备更新结果并将状态发布到 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 来验证该命令执行是否已不在您的账户中。