启动和监控命令执行

指定要接收和执行命令的目标设备。对已注册的设备使用事物名称，对未注册的设备使用客户端 ID。收到有效载荷后，设备执行命令并执行指定的操作。

Amazon IoT 东西

目标设备可以是在注册 Amazon IoT 表中注册的事物。这简化了设备搜索和管理。

从 Connect 设备页面或使用将设备注册为事物CreateThing。从 Thing Hub 或使用中查找现有事物DescribeThing。有关注册的详细信息，请参阅使用注册表管理事物。

客户端 ID

对于未注册的设备，请使用客户端 ID。

客户端 ID 是您分配给设备的唯一标识符。它在 MQTT 协议中定义，包含字母数字字符、下划线或破折号。连接的每台设备都 Amazon IoT 需要一个唯一的客户端 ID。

客户端 ID 是设备在连接时使用的 MQTT 客户端 ID。 Amazon IoT Core Amazon IoT 使用此 ID 来识别设备并管理连接和订阅。

超时指定设备提供执行结果的持续时间（以秒为单位）。

创建执行后，计时器启动。如果设备离线或未能在超时时间内报告结果，则执行超时并显示状态TIMED_OUT。

默认值：10 秒。最长：12 小时。

超时值和 TIMED_OUT 执行状态

云端和设备都可以报告超时。

发送命令后，计时器启动。如果在超时时间内没有设备响应，则云会将执行状态设置为，并TIMED_OUT附带原因代码$NO_RESPONSE_FROM_DEVICE。

在以下情况下会发生这种情况：

在这种情况下，当从云端报告 TIMED_OUT 的执行状态时，命令执行是非终端的。您的设备可以发布响应，将状态改写为任何终端状态：SUCCEEDEDFAILED、或。REJECTED然后，命令执行变为终端，不接受任何进一步的更新。

您的设备还可以通过报告在执行命令时出现超时来更新云端启动的TIMED_OUT状态。在这种情况下，命令执行状态保持为TIMED_OUT，但会根据设备报告的信息更新statusReason对象。然后，命令执行变为终止，并且不接受进一步的更新。

使用 MQTT 持久会话

您可以配置 MQTT 持久会话以与 Amazon IoT Device Management 命令功能配合使用。此功能在诸如您的设备离线并且您希望确保设备在超时持续时间之前重新上线时仍能接收命令并执行指定指令的情况下特别有用。

默认情况下，MQTT 持久会话到期时间设置为 60 分钟。如果您的命令执行超时配置为超过此持续时间的值，则运行时间超过 60 分钟的命令执行可能会被消息代理拒绝并失败。要运行持续时间超过 60 分钟的命令，您可以请求延长持续会话的到期时间。

要开始从控制台运行该命令，请转到控制台的 Command Hub 页面并执行以下步骤。 Amazon IoT

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

要查看支持的条件键列表StartCommandExecution，请参阅 IAM 用户指南 Amazon IoT中的条件密钥。

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

在运行 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"
}

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

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

在此示例中：

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

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

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

在此示例中：

MQTT 客户端 ID 的示例 IAM 策略

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

IoT 事物的示例 IAM 策略

以下代码显示使用 Amazon 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"
        }
    }
}

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

使用GetCommandExecution Amazon 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 Amazon 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: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"    
}

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

使用ListCommandExecutions Amazon IoT Core 控制平面 HTTP API 操作列出您账户中的所有命令执行情况。

IAM 策略示例

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

在此示例中：

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

列出命令执行示例

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

运行命令时，您必须指定是否筛选列表，以仅显示使用 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 Amazon CLI 命令。根据您的应用程序，将 <execution-id> 替换为您要删除的命令执行的标识符，并将 <target-arn> 替换为您目标设备的 ARN。

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

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