本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 命令概念和状态
<a name="iot-remote-command-concepts"></a>

使用 AWS IoT 命令将指令从云端发送到连接的设备。要使用此功能，请执行以下操作：

1. 创建一条包含在设备上运行所需的配置的有效载荷的命令。

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

1. 在目标设备上执行命令并检索状态信息。要对问题进行故障排除，请参阅 CloudWatch 日志。

有关工作流的更多信息，请参阅 [高级命令工作流程](iot-remote-command-workflow.md)。

**Topics**
+ [

## 命令关键概念
](#iot-command-concepts)
+ [

## 命令状态
](#iot-command-states)
+ [

## 命令执行状态
](#iot-command-execution-status)

## 命令关键概念
<a name="iot-command-concepts"></a>

以下关键概念可帮助您理解命令功能。在本文档中，术语的使用始终如一：
+ *命令*-定义设备指令的可重复使用的模板
+ *执行*-在设备上运行的命令的实例
+ *事物名称*-在 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设备端逻辑决定执行行为和向保留主题报告的状态。

### 参数值条件
<a name="iot-command-parameter-value-conditions"></a>

使用负载模板创建命令时，请在执行前定义值条件以验证参数值。值条件可确保参数满足要求，防止无效执行。

**按[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) 时评估的。验证失败会返回错误并阻止执行创建。

### 参数值优先级和评估
<a name="iot-command-parameter-value-priority"></a>

使用有效负载模板开始执行命令时，将使用以下优先级解析参数值：

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] 进行验证

## 命令状态
<a name="iot-command-states"></a>

您的命令 AWS 账户 可以处于以下三种状态之一：“*可*用”、“*已弃用*” 或 “*待删除*”。

**可用**  
成功创建后，命令将处于 “可用” 状态，可以在设备上执行。

**已弃用**  
当不再需要时，将命令标记为已弃用。已弃用的命令无法启动新的执行，但待执行会继续完成。要启用新的执行，请将命令恢复到 “可用” 状态。

**待删除**  
将命令标记为删除时，如果不推荐使用的命令超过最大超时时间（默认值：12 小时），则该命令将被自动删除。此操作是永久性的。如果在超时时间内未被弃用或弃用，则该命令将进入待删除状态，并在超时到期后被删除。

## 命令执行状态
<a name="iot-command-execution-status"></a>

当您在目标设备上开始执行时，它会进入`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)

### 非终端命令执行
<a name="iot-command-execution-status-nonterminal"></a>

如果执行可以接受来自设备的更新，则该执行是非终止的。非终止执行被视为处于*活动状态*。以下状态为非终端状态：
+ 

**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)。

### 终端命令执行
<a name="iot-command-execution-status-terminal"></a>

当执行不再接受来自设备的更新时，该执行将变为终止。以下状态是终端的。执行可以从任何非终端状态转换为终端状态：`CREATED``IN_PROGRESS`、或。`TIMED_OUT`
+ 

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

**FAILED**  
当设备无法完成执行时，它可以发布对命令响应主题的响应并将状态更新为`FAILED`。使用`statusReason`对象或 CloudWatch 日志中的`reasonCode`和`reasonDescription`字段对故障进行故障排除。
+ 

**REJECTED**  
当设备收到无效或不兼容的请求时，它可以调用带有状态`UpdateCommandExecution`的 API `REJECTED`。使用`statusReason`对象或 CloudWatch 日志中的`reasonCode`和`reasonDescription`字段对问题进行故障排除。