启动和监控命令执行

当您要运行命令时，必须指定将接收命令并执行指定指令的目标设备。目标设备可以是 AWS IoT 事物，或者如果设备尚未在 AWS IoT 注册表中注册，则可以是客户端 ID。接收命令有效载荷后，设备可以开始执行命令并执行指定的操作。

AWS IoT 事物

该命令的目标设备可以是您在 AWS IoT 事物注册表中注册的 AWS IoT 事物。AWS IoT 中的事物可让您更轻松地搜索和管理设备。

您可以在将设备连接到 AWS IoT 时，从连接设备页面或使用 CreateThing API 将设备注册为事物。您可以从 AWS IoT 控制台的事物中心页面或使用 DescribeThing API 找到要为其运行命令的现有事物。有关如何将设备注册为 AWS IoT 事物的信息，请参阅使用注册表管理事物。

客户端 ID

如果您的设备尚未向 AWS IoT 注册为事物，则可以改用客户端 ID。

客户端 ID 是您分配给设备或客户端的唯一标识符。客户端 ID 在 MQTT 协议中定义，可以包含字母数字字符、下划线或破折号。它对于连接到 AWS IoT 的每个设备必须是唯一的。

客户端 ID 通常是您的设备在连接到 AWS IoT Core 时可以使用的 MQTT 客户端 ID。此 ID 由 AWS IoT 用于识别每个特定设备并管理连接和订阅。

超时表示设备可以提供命令执行结果的持续时间（以秒为单位）。

创建命令执行后，计时器启动。如果设备在超时时间内离线或未能报告执行结果，则命令执行将超时，执行状态将报告为 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 分钟的命令，您可以请求延长持续会话的到期时间。

要从控制台开始运行命令，请转到 AWS IoT 控制台的命令中心页面并执行以下步骤。

使用 StartCommandExecution HTTP 数据面板 API 操作来启动命令执行。API 请求和响应通过命令执行 ID 进行关联。设备完成命令执行后，它可以通过向命令响应主题发布消息来向云端报告状态和执行结果。对于自定义响应代码，您拥有的应用程序代码可以处理响应消息并将结果发布到 AWS IoT。

如果您的设备已订阅命令请求主题，则 StartCommandExecution API 将有效载荷消息发布到该主题。有效载荷可以使用您选择的任何格式。有关更多信息，请参阅 命令有效载荷。

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

如果有效载荷格式不是 JSON 或 CBOR，则以下显示命令请求主题的格式。

$aws/commands/<devices>/<DeviceID>/executions/+/request

IAM 策略示例

在使用此 API 操作之前，请确保您的 IAM 策略授权您对设备执行此操作。以下示例显示一个 IAM 策略，允许用户执行 StartCommandExecution 操作。

在此示例中：

{
  "Effect": "Allow",
  "Action": [
      "iot:StartCommandExecution"
  ],
  "Resource": [
      "arn:aws:iot:region:account-id:command/command-id",
      "arn:aws:iot:region:account-id:devices/device-id"
  ]
}

获取账户特定的数据面板端点

在运行 API 命令之前，您必须获取该端点的账户特定端点 URL。如果您使用双栈端点（IPv4 和 IPv6），请使用 iot:Data-ATS。iot:Jobs 端点仅适用于 IPv4。例如，如果您运行此命令：

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

它将返回账户特定的端点 URL，如下面的示例响应所示。

{
    "endpointAddress": "<account-specific-prefix>-ats.iot.<region>.api.com"
}

启动命令执行示例 (AWS CLI)

以下示例显示如何使用 start-command-execution AWS CLI 命令开始执行命令。

在此示例中：

aws iot-jobs-data start-command-execution \ 
    --command-arn <command-arn>  \
    --target-arn <target-arn> \  
    --endpoint <endpoint-url> \ 
    --execution-timeout-seconds 900

运行此命令会返回一个命令执行 ID。您可以使用此 ID 查询命令执行状态、详细信息和命令执行历史记录。

{
    "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542"
}

在使用此 API 操作之前，请确保您的 IAM 策略授权您的设备执行这些操作。以下显示一个授权您的设备执行该操作的示例策略。有关允许用户执行 UpdateCommandExecution 操作的其他示例 IAM 策略，请参阅 连接和发布策略示例。

在此示例中：

MQTT 客户端 ID 的示例 IAM 策略

以下代码显示使用 MQTT 客户端 ID 时的示例设备策略。

IoT 事物的示例 IAM 策略

以下代码显示使用 AWS IoT 事物时的示例设备策略。

在请求主题收到命令执行后，设备处理该命令。然后，它使用 UpdateCommandExecution API 将命令执行的状态和结果更新为以下响应主题。

$aws/commands/<devices>/<DeviceID>/executions/<ExecutionId>/response/<PayloadFormat>

在此示例中，<DeviceID> 是您目标设备的唯一标识符，<execution-id> 是目标设备上命令执行的标识符。<PayloadFormat> 可以是 JSON 或 CBOR。

$aws/commands/clients/<ClientID>/executions/<ExecutionId>/response/<PayloadFormat>

设备报告的执行状态更新

您的设备可以使用 API 向命令执行报告以下任何状态更新。有关这些状态的更多信息，请参阅 命令执行状态。

有关 TIMED_OUT 状态的更多信息，请参阅 超时值和 TIMED_OUT 执行状态。

使用 UpdateCommandExecution API 时的注意事项

以下是使用 UpdateCommandExecution API 时的一些重要注意事项。

UpdateCommandExecution API 示例

以下代码显示一个示例，说明您的设备如何使用 UpdateCommandExecution API 报告执行状态、使用 statusReason 字段提供有关状态的附加信息，以及使用结果字段提供有关执行结果的信息，例如本例中的汽车电池百分比。

{
  "status": "IN_PROGRESS",
  "statusReason": {
    "reasonCode": "200",
    "reasonDescription": "Execution_in_progress"
  },
  "result": {
        "car_battery": {
            "s": "car battery at 50 percent"
        }
    }
}

您可以使用以下任一方法从控制台检索命令执行。

使用 GetCommandExecutionAWS IoT Core 控制面板 HTTP API 操作检索有关命令执行的信息。您必须已经使用 StartCommandExecution API 操作执行了此命令。

IAM 策略示例

在使用此 API 操作之前，请确保您的 IAM 策略授权您对设备执行此操作。以下示例显示一个 IAM 策略，允许用户执行 GetCommandExecution 操作。

在此示例中：

{
  "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 命令检索有关已执行命令的信息。以下示例显示如何检索有关已执行的、用于关闭方向盘模式的命令的信息。

在此示例中：

aws iot get-command-execution  
    --execution-id <execution-id> \ 
    --target-arn <target-arn> \
    --include-result

运行此命令会生成一个响应，其中包含有关命令执行的 ARN、执行状态、开始执行时间以及完成时间的信息。它还提供一个 statusReason 对象，其中包含有关状态的附加信息。有关不同状态和状态原因的更多信息，请参阅 命令执行状态。

以下代码显示 API 请求的示例响应。

{
    "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542",
    "commandArn": "arn:aws:iot:ap-south-1:123456789012:command/LockDoor",
    "targetArn": "arn:aws:iot:ap-south-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"    
}

您可以使用以下任一方法从控制台查看所有命令执行。

使用 ListCommandExecutionsAWS IoT Core 控制面板 HTTP API 操作列出您账户中的所有命令执行。

IAM 策略示例

在使用此 API 操作之前，请确保您的 IAM 策略授权您对设备执行此操作。以下示例显示一个 IAM 策略，允许用户执行 ListCommandExecutions 操作。

在此示例中：

{
  "Effect": "Allow",
  "Action": "iot:ListCommandExecutions",
  "Resource": *
}

列出命令执行示例

以下示例显示如何列出您 AWS 账户 中的命令执行。

运行命令时，您必须指定是否筛选列表，以仅显示使用 targetArn 为特定设备创建的命令执行，或使用 commandArn 为特定命令指定的执行。

在此示例中：

aws iot list-command-executions \ 
--target-arn <target-arn> \ 
--started-time-filter '{after=<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"
        }
    ]
}

有关不同状态和状态原因的更多信息，请参阅 命令执行状态。

在使用此 API 操作之前，请确保您的 IAM 策略授权您的设备执行这些操作。以下显示一个授权您的设备执行该操作的示例策略。

在此示例中：

{
  "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 命令删除命令。根据您的应用程序，将 <execution-id> 替换为您要删除的命令执行的标识符，并将 <target-arn> 替换为您目标设备的 ARN。

aws iot delete-command-execution \ 
--execution-id <execution-id> \ 
--target-arn <target-arn>

如果 API 请求成功，则该命令执行会生成状态码 200。您可以使用 GetCommandExecution API 来验证该命令执行是否已不在您的账户中。