本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 命令概念和狀態
<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 識別符
+ *承載* - 傳送至裝置的指令資料
+ *主題* - 命令通訊的 MQTT 頻道

**命令**  
命令是以 MQTT 訊息形式從雲端傳送至 IoT 裝置的指示。收到承載後，裝置會處理指示並採取對應的動作，例如修改組態設定、傳輸感應器讀數或上傳日誌。裝置接著會將結果傳回至雲端，以啟用遠端監控和控制。

**命名空間**  
建立命令時，請指定其命名空間。對於 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) 類型支援的運算子**

**數值類型 (INTEGER、LONG、DOUBLE、UnSIGNEDLONG)**  
+ `EQUALS` - 值必須等於指定的數字
+ `NOT_EQUALS` - 值不得等於指定的數字
+ `GREATER_THAN` - 值必須大於指定的數字
+ `GREATER_THAN_EQUALS` - 值必須大於或等於指定的數字
+ `LESS_THAN` - 值必須小於指定的數字
+ `LESS_THAN_EQUALS` - 值必須小於或等於指定的數字
+ `IN_RANGE` - 值必須在指定的範圍內 （包含）
+ `NOT_IN_RANGE` - 值必須超出指定的範圍 （包含）
+ `IN_SET` - 值必須符合其中一個指定的數字
+ `NOT_IN_SET` - 值不得與任何指定的數字相符

**字串類型 (STRING)**  
+ `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_tw/iot/latest/developerguide/iot-remote-command-concepts.html)  | 
| IN\$1PROGRESS | 裝置 | 否 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot/latest/developerguide/iot-remote-command-concepts.html)  | 
| TIMED\$1OUT | 裝置和雲端 | 否 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot/latest/developerguide/iot-remote-command-concepts.html)  | 
| SUCCEEDED | 裝置 | 是 | 不適用 | 
| FAILED | 裝置 | 是 | 不適用 | 
| REJECTED | 裝置 | 是 | 不適用 | 

裝置可以隨時使用命令預留 MQTT 主題來發佈狀態和結果更新。為了提供額外的內容，裝置可以使用 `statusReason` 物件中的 `reasonCode`和 `reasonDescription` 欄位。

下圖顯示執行狀態轉換。

![\[顯示命令執行狀態如何在各種狀態之間轉換的影像。\]](http://docs.aws.amazon.com/zh_tw/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\$1PROGRESS**  
收到承載後，裝置可以開始執行指示和執行指定的動作。執行時，裝置可以將回應發佈至命令回應主題，並將狀態更新至 `IN_PROGRESS`。從 `IN_PROGRESS`，執行可以轉換為 以外的任何終端機或非終端機狀態`CREATED`。
**注意**  
可以使用 `IN_PROGRESS` 狀態多次叫用 `UpdateCommandExecution` API。使用 `statusReason` 物件指定其他執行詳細資訊。
+ 

**TIMED\$1OUT**  
雲端和裝置都可以觸發此狀態。`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>

當執行不再接受來自裝置的更新時，就會變成終端機。下列狀態為終端機。執行可以從任何非終端狀態轉換為終端狀態：`IN_PROGRESS`、 `CREATED`或 `TIMED_OUT`。
+ 

**SUCCEEDED (成功)**  
如果裝置成功完成執行，則可以將回應發佈至命令回應主題，並將狀態更新為 `SUCCEEDED`。
+ 

**失敗**  
當裝置無法完成執行時，可以發佈回應至命令回應主題，並將狀態更新至 `FAILED`。使用 `statusReason` 物件中的 `reasonCode`和 `reasonDescription` 欄位或 CloudWatch 日誌，對失敗進行故障診斷。
+ 

**REJECTED**  
當裝置收到無效或不相容的請求時，它可以調用狀態為 的 `UpdateCommandExecution` API`REJECTED`。使用 `statusReason` 物件中的 `reasonCode`和 `reasonDescription` 欄位或 CloudWatch 日誌來疑難排解問題。