命令概念和状态 - AWS IoT Core
命令关键概念命令状态命令执行状态

命令概念和状态

使用 AWS IoT 命令将指令从云端发送到连接到 AWS IoT 的设备。要使用命令功能：

  1. 首先，创建一个命令资源，其有效载荷包含在设备上运行命令所需的配置。

  2. 指定将接收有效载荷并执行指定操作的目标设备。

  3. 在目标设备上运行命令，并从设备检索状态信息。要排除任何问题，请查看 CloudWatch 日志。

有关工作流的更多信息，请参阅 高级命令工作流程。

命令关键概念

以下展示了使用命令功能的一些关键概念。

命令

命令是从云发送到您的物联网设备的指令。这些指令（命令有效载荷）作为 MQTT 消息发送到设备。设备收到命令有效载荷后，可以处理指令以执行相应的操作。此类操作的示例包括修改设备配置设置、传输传感器读数或上传日志。然后设备可以运行命令并将结果返回给云。这使您能够远程监控和控制连接的设备。

命名空间：

当您使用命令功能时，可以指定命令的命名空间。当您想在 AWS IoT Device Management 中创建命令时，必须使用默认的 AWS-IoT 命名空间。使用此命名空间时，创建命令必须提供有效载荷。该有效载荷将在您目标设备上运行命令时使用。如果您想为 AWS IoT FleetWise 创建命令，则必须改用 AWS-IoT-FleetWise 命名空间。有关更多信息，请参阅《AWS IoT FleetWise 命令开发人员指南》中的远程命令。

有效载荷

创建命令时，必须提供一个定义设备必须执行的操作的有效载荷。有效载荷可以使用您选择的任何格式。为确保设备能够正确读取和理解您发送的信息，我们建议您在命令中指定有效载荷格式类型。如果您的设备使用 MQTT5，它们可以遵循 MQTT 标准来识别有效载荷格式。命令请求主题中将提供 JSON 或 CBOR 的格式指示符。

目标设备

当您要运行命令时，必须指定将接收命令并执行操作的目标设备。如果您的设备已在 AWS IoT 中注册为事物，您可以使用事物名称。如果您的设备尚未注册，则可以改用 MQTT 客户端 ID。客户端 ID 是在 MQTT 协议中为您的设备或客户端定义的唯一标识符。它可用于将您的设备连接到 AWS IoT。

命令执行

命令执行是在目标设备上运行的命令的一个实例。当您启动执行时，命令（有效载荷）将传递给目标设备。此时会为目标生成一个唯一的命令执行 ID。然后设备可以执行命令并将其进度报告给 AWS IoT。设备端逻辑决定命令将如何执行以及状态如何发布到保留主题。

命令主题

在运行命令之前，您的设备必须已订阅命令请求主题。当您向云发送请求以执行命令时，有效载荷将通过命令请求主题发送到设备。设备执行命令后，可以将执行的结果和状态发布到命令响应主题。有关更多信息，请参阅 命令主题。

命令状态

您在 AWS 账户 中创建的命令可以处于“可用”、“已弃用”或“待删除”状态。

可用

成功创建命令资源后，它将处于可用状态。现在可以使用该命令向设备发送命令执行。

已弃用

如果您不再打算使用某个命令，可以将其标记为弃用。在此状态下，您无法向设备发送该命令的任何新执行。任何已启动的待处理执行将在设备上继续运行直至完成。要发送新的执行，必须恢复命令以使其可用。

待删除

当您标记要删除的命令时，如果该命令已被弃用的时间长于最大超时时间，则该命令将被自动删除。这是一个永久性操作，无法撤消。默认情况下，最大超时持续时间为 12 小时。如果命令未被弃用，或已被弃用的持续时间短于最大超时时间，该命令将处于待删除状态。该命令将在最大超时持续时间后自动从您的帐户中移除。

命令执行状态

当您在目标设备上开始执行命令时，命令执行进入 CREATED 状态。然后，它可以根据设备报告的状态转换到任何其他命令执行状态。然后，您可以检索状态信息并跟踪您的命令执行。

注意

对于给定的目标设备，您可以并发运行多个命令。您可以使用并发控制功能限制发送到同一设备的最大执行数量，从而防止设备过载。有关每个设备可以运行的最大并发执行数量的信息，请参阅 AWS IoT Device Management 命令配额。

下表显示了命令执行的不同状态，以及命令执行如何根据执行进度在各种状态之间转换。

命令执行状态和来源
命令执行状态 由设备/云端发起？ 是否为终端执行？ 允许的状态转换
CREATED 云 否

  • IN_PROGRESS

  • SUCCEEDED

  • FAILED

  • REJECTED

  • TIMED_OUT
IN_PROGRESS 设备 否

  • IN_PROGRESS

  • SUCCEEDED

  • FAILED

  • REJECTED

  • TIMED_OUT
TIMED_OUT 设备和云 否

  • SUCCEEDED

  • FAILED

  • REJECTED

  • TIMED_OUT
SUCCEEDED 设备 是 不适用
FAILED 设备 是 不适用
REJECTED 设备 是 不适用

当您的设备执行命令时，它可以随时使用命令保留的 MQTT 主题向云发布状态和结果的更新。为了向云提供有关每个命令执行状态的额外上下文，它可以使用包含在 statusReason 对象内的 reasonCode 和 reasonDescription。

下图显示了各种命令执行状态以及它们之间的转换方式。

该图显示了命令执行状态如何在各种状态之间转换。
注意

当 AWS IoT 在超时期间内未检测到设备响应时，它会将 TIMED_OUT 设置为一个允许重试和状态更改的临时状态。如果您的设备在命令执行期间显式报告 TIMED_OUT，则这将成为一个最终状态，无法再进行任何转换。请参阅 非终端命令执行。

下一节介绍了终端和非终端命令的执行、各种执行状态及其工作原理。

非终端命令执行

如果执行可以接受来自设备或客户端的更新，则您的命令执行是非终端的。在非终端状态下的执行被视为活动。以下状态是非终端的。

  • CREATED

    当您从 AWS IoT 控制台启动命令执行，或使用 StartCommandExecution API 通过命令请求主题将命令发送到您的设备时。如果请求成功，命令执行状态更改为 CREATED。从此状态，命令执行可以过渡到任何其他非终端或终端状态。

  • IN_PROGRESS

    在接收命令有效载荷后，您的设备可以开始执行有效载荷中的指令并执行指定的操作。在执行命令时，设备可以发布响应到命令响应主题，并将命令执行状态更新为 IN_PROGRESS。从 IN_PROGRESS 状态，命令执行可以过渡到任何其他终端或非终端状态，除了 CREATED。

    注意

    UpdateCommandExecution API 可以多次调用，状态为 IN_PROGRESS。您可以使用 statusReason 对象指定有关执行的其他详细信息。

  • TIMED_OUT

    此命令执行状态可以由云端和设备触发。在 IN_PROGRESS 或 CREATED 状态下的执行可以由于以下原因更改为 TIMED_OUT 状态。

    • 在命令发送到设备后，计时器启动。如果在指定持续时间内没有来自设备的响应，云端将命令执行状态更改为 TIMED_OUT。在这种情况下，命令执行是非终端的。

    • 设备可以将状态覆盖为任何其他终端状态，或报告在执行命令时发生超时，并将状态设置为 TIMED_OUT。在这种情况下，执行状态保持在 TIMED_OUT，但 StatusReason 对象的字段根据设备报告的信息而变化。命令执行现在变为终端。

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

终端命令执行

如果执行不再接受来自设备的任何其他更新，则命令执行变为终端。以下状态是终端的。执行可以从任何非终端状态 CREATED、IN_PROGRESS 或 TIMED_OUT 过渡到终端状态。

  • SUCCEEDED

    如果设备成功完成执行命令，它可以发布响应到命令响应主题，并将命令执行状态更新为 SUCCEEDED。

  • FAILED

    当您的设备未能完成执行命令时，它可以发布响应到命令响应主题，并将命令执行状态更新为 FAILED。您可以使用 statusReason 对象的 reasonCode 和 reasonDescription 字段，或 CloudWatch 日志，来进一步排除故障。

  • REJECTED

    当您的设备收到无效或不兼容的请求时，设备可以调用 UpdateCommandExecution API 且状态为 REJECTED。您可以使用 statusReason 对象的 reasonCode 和 reasonDescription 字段，或 CloudWatch 日志，来进一步排除任何问题。