本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 命令
**重要**
對特定 AWS IoT FleetWise 功能的存取目前受到鎖定。如需詳細資訊，請參閱[AWS AWS IoT FleetWise 中的區域和功能可用性](fleetwise-regions.md)。
本文件說明如何使用[適用於 AWS IoT FleetWise 的命令功能](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-command-concepts-states.html#commands-iotfw-namespace)。如需在 中使用命令功能的詳細資訊 AWS IoT Device Management，請參閱 [命令](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command.html)。
您全權負責以安全且符合相關法律的方式部署命令。如需 責任的詳細資訊，請參閱 [AWSAWS IoT 服務條款](https://aws.amazon.com/service-terms/)。
使用命令功能，從雲端對車輛執行命令。命令一次以一個裝置為目標，可用於低延遲、高輸送量的應用程式，例如擷取裝置端日誌，或啟動裝置狀態變更。
*命令*是由 管理的資源 AWS IoT Device Management。它包含可在傳送命令執行至車輛時套用的可重複使用組態。您可以針對特定使用案例預先定義一組命令，或使用它們來為經常性使用案例建立可重複使用的組態。例如，您可以設定 命令，供 應用程式用來鎖定車輛的門或遠端變更溫度。
使用 AWS IoT 命令功能，您可以：
+ 建立命令資源並重複使用組態，將多個命令傳送至您的目標裝置，然後在裝置上執行這些命令。
+ 控制要在裝置上執行每個命令的精細程度。例如，您可以將車輛佈建為 AWS IoT 物件，然後傳送命令來鎖定或解鎖車輛的門。
+ 在目標裝置上同時執行多個命令，無需等待上一個命令完成。
+ 選擇 以啟用命令事件的通知，並在執行命令時以及完成後，從裝置擷取狀態和結果資訊。
下列主題說明如何建立、傳送、接收和管理命令。
**Topics**
+ [命令概念](remote-command-concepts-states.md)
+ [車輛和命令](remote-command-vehicles.md)
+ [建立和管理命令](create-manage-remote-command-cli.md)
+ [開始和監控命令執行](send-monitor-remote-command-cli.md)
+ [範例：使用命令控制車輛轉向模式 (AWS CLI)](remote-command-tutorial.md)
+ [命令使用案例](remote-command-use-cases.md)
# 命令概念
**重要**
對特定 AWS IoT FleetWise 功能的存取目前受到鎖定。如需詳細資訊，請參閱[AWS AWS IoT FleetWise 中的區域和功能可用性](fleetwise-regions.md)。
命令是從雲端傳送至目標裝置的指示。目標裝置可以是 車輛，且必須在*AWS IoT 物件*登錄檔中註冊為物件。命令可以包含參數，以定義車輛傳動器需要執行的動作。車輛接著會剖析命令及其參數，並處理它們以採取對應的動作。然後，它會以命令執行的狀態回應雲端應用程式。
如需詳細的工作流程，請參閱 [車輛和命令](remote-command-vehicles.md)。
**Topics**
+ [命令關鍵概念](#remote-command-concepts)
+ [命令執行狀態](#remote-command-execution-status-codes)
## 命令關鍵概念
以下顯示一些使用 命令功能的重要概念，以及其如何使用上次已知狀態 (LKS) 狀態範本。
**命令**
命令是一種實體，可用來將指示傳送至實體車輛，讓它執行動作，例如開啟引擎或變更視窗的位置。您可以針對特定使用案例預先定義一組命令，或使用它們來為經常性使用案例建立可重複使用的組態。例如，您可以設定 命令，供 應用程式用來鎖定車輛的門或遠端變更溫度。
**命名空間**
使用命令功能時，您必須指定命令的命名空間。當您在 AWS IoT FleetWise 中建立命令時，您必須選擇 `AWS-IoT-FleetWise`做為命名空間。當您使用此命名空間時，必須提供將用於在車輛上執行 命令的參數。如果您想要 AWS IoT Device Management 改為在 中建立命令，則必須改用 `AWS-IoT` 命名空間。如需詳細資訊，請參閱 *AWS IoT Device Management 開發人員指南*中的 [命令](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command.html)。
**命令狀態**
您建立的命令將處於可用狀態，這表示它可用於在車輛上啟動命令執行。如果命令過期，您可以棄用命令。對於處於已棄用狀態的命令，現有的命令執行將執行到完成。您無法更新命令或執行任何新的執行。若要傳送新的執行，您必須還原命令，使其變成可用。
如果不再需要命令，您也可以將其刪除。當您將命令標記為刪除時，如果命令已棄用超過最大逾時 24 小時的持續時間，則會立即刪除命令。如果命令未棄用，或已棄用超過最大逾時的持續時間，則命令將處於待定刪除狀態。命令會在 24 小時後自動從您的帳戶中移除。
**參數**
建立命令時，您可以選擇指定您希望目標車輛在執行命令時執行的參數。您建立的 命令是可重複使用的組態，可用來將多個命令執行傳送至您的 車輛，並同時執行它們。或者，您也可以只在執行時間指定參數，並選擇執行建立命令並將其傳送至車輛的一次性操作。
**目標車輛**
當您想要執行命令時，您必須指定將接收命令並執行特定動作的目標車輛。目標車輛必須已向 註冊為*物件* AWS IoT。將命令傳送至車輛後，它會開始根據您指定的參數和值執行命令的執行個體。
**傳動器**
當您想要執行 命令時，您必須在車輛上指定將接收命令的傳動器及其值，以決定要執行的動作。您可以選擇性地設定傳動器的預設值，以避免傳送不正確的命令。例如，您可以將預設值 `LockDoor`用於門鎖致動器，讓命令不會意外解除鎖定門。如需傳動器的一般資訊，請參閱 [重要概念](how-iotfleetwise-works.md#key-concepts)。
**資料類型支援**
用於命令功能的傳動器支援以下資料類型。
遠端資訊處理資料、命令或最後已知狀態 (LKS) 不支援陣列。您只能將陣列資料類型用於視覺系統資料。
+ 浮點數類型。支援下列類型。
+ 浮點數 (32 位元）
+ 雙 (64 位元）
+ 整數 （已簽章和未簽章）。支援下列整數類型。
+ int8 和 uint8
+ int16 和 uint16
+ int32 和 uint32
+ 長。支援下列長型。
+ 長 (int64)
+ 未簽署的長 (uint64)
+ String
+ Boolean
**命令執行**
命令執行是在目標裝置上執行之命令的執行個體。車輛會使用您在建立命令或啟動命令執行時指定的參數來執行命令。車輛接著會執行指定的操作，並傳回執行的狀態。
對於指定的車輛，您可以同時執行多個命令。如需您可以為每個車輛執行的並行執行數目上限的相關資訊，請參閱[AWS IoT Device Management 命令配額](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#commands-limits)。
**上次已知狀態 (LKS) 狀態範本**
狀態範本為車主提供追蹤其車輛狀態的機制。若要近乎即時地監控您車輛的上次已知狀態 (LKS)，您可以建立狀態範本並將其與您的車輛建立關聯。
使用 命令功能，您可以執行可用於狀態資料收集和處理的「隨需」操作。例如，您可以請求目前車輛狀態一次性 （擷取），或啟用或停用先前部署的 LKS 狀態範本，以開始或停止報告車輛資料。如需示範如何使用 命令搭配狀態範本的範例，請參閱 [命令使用案例](remote-command-use-cases.md)。
## 命令執行狀態
啟動命令執行後，您的車輛可以發佈執行狀態，並提供狀態原因做為執行的其他資訊。下列各節說明各種命令執行狀態，以及狀態碼。
**Topics**
+ [命令執行狀態原因代碼和描述](#remote-command-execution-status-reason-codes)
+ [命令執行狀態和狀態碼](#remote-command-execution-status-codes)
+ [命令執行逾時狀態](#remote-command-execution-status-timeout)
### 命令執行狀態原因代碼和描述
若要報告命令執行狀態的更新，您的車輛可以使用 `UpdateCommandExecution` API，使用*AWS IoT Core 開發人員指南*中所述[的命令保留主題](https://docs.aws.amazon.com/iot/latest/developerguide/reserved-topics.html#reserved-topics-commands)，將更新的狀態資訊發佈至雲端。報告狀態資訊時，您的裝置可以使用 `StatusReason` 物件提供每個命令執行狀態的其他內容，以及包含在 物件中的欄位 `reasonCode` 和 `reasonDescription` 。
### 命令執行狀態和狀態碼
下表顯示各種命令執行狀態碼，以及命令執行可以轉換到的允許狀態。它也會顯示命令執行是否為「終端」（即不會進一步進行狀態更新）、變更是由車輛或雲端啟動，以及不同的預先定義狀態碼，以及它們如何對應到雲端報告的狀態。
+ 如需有關 AWS IoT FleetWise 如何使用預先定義狀態碼和 `statusReason` 物件的資訊，請參閱 *Edge Agent for AWS IoT FleetWise 軟體文件中*的[命令狀態](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/include/aws/iotfleetwise/ICommandDispatcher.h)。
+ 如需有關終端機和非終端機執行以及狀態之間轉換的其他資訊，請參閱*AWS IoT Core 開發人員指南*中的[命令執行狀態](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command-concepts.html#iot-command-execution-status)。
**命令執行狀態和來源**
| 命令執行狀態 | Description | 由裝置/雲端啟動？ | 終端機執行？ | 允許的狀態轉換 | 預先定義的狀態碼 |
| --- | --- | --- | --- | --- | --- |
| CREATED | 當開始執行命令的 API 請求 (StartCommandExecution API) 成功時，命令執行狀態會變更為 CREATED。 | 雲端 | 否 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-fleetwise/latest/developerguide/remote-command-concepts-states.html) | 無 |
| IN\$1PROGRESS | 當車輛開始執行命令時，可以發佈訊息至回應主題，將狀態更新為 IN\$1PROGRESS。 | 裝置 | 否 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-fleetwise/latest/developerguide/remote-command-concepts-states.html) | COMMAND\$1STATUS\$1COMMAND\$1IN\$1PROGRESS |
| SUCCEEDED | 當車輛成功處理命令並完成執行時，可以將訊息發佈至回應主題，以將狀態更新為 SUCCEEDED。 | 裝置 | 是 | 不適用 | COMMAND\$1STATUS\$1SUCCEEDED |
| FAILED | 當車輛無法執行命令時，可以將訊息發佈至回應主題，以將狀態更新為 FAILED。 | 裝置 | 是 | 不適用 | COMMAND\$1STATUS\$1EXECUTION\$1FAILED |
| REJECTED | 如果車輛無法接受命令，可以將訊息發佈至回應主題，將狀態更新為 REJECTED。 | 裝置 | 是 | 不適用 | 無 |
| TIMED\$1OUT | 由於下列任何原因`TIMED_OUT`，命令執行狀態可能會變更為 。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-fleetwise/latest/developerguide/remote-command-concepts-states.html) 如需此狀態的詳細資訊，請參閱 [命令執行逾時狀態](#remote-command-execution-status-timeout)。 | 裝置和雲端 | 否 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-fleetwise/latest/developerguide/remote-command-concepts-states.html) | COMMAND\$1STATUS\$1EXECUTION\$1TIMEOUT |
### 命令執行逾時狀態
雲端和裝置都可以報告命令執行逾時。命令傳送至裝置後，計時器便會啟動。如果在指定的持續時間內沒有收到來自裝置的回應，則雲端會報告`TIMED_OUT`狀態。在此情況下，`TIMED_OUT`狀態為 的命令執行為非終端。
裝置可以將此狀態覆寫為終端狀態，例如 `SUCCEEDED`、 `FAILED`或 `REJECTED`。它也可以報告執行 命令時發生逾時。在此情況下，命令執行狀態會保持在 ，`TIMED_OUT`但`StatusReason`物件的欄位會根據裝置報告的資訊更新。狀態中的命令執行`TIMED_OUT`現在會變成終端機。
如需詳細資訊，請參閱*AWS IoT Core 《 開發人員指南*》中的[命令執行逾時考量](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command-execution-start-monitor.html#iot-command-execution-timeout)事項。
# 車輛和命令
**重要**
某些 AWS IoT FleetWise 功能的存取目前受到鎖定。如需詳細資訊，請參閱[AWS AWS IoT FleetWise 中的區域和功能可用性](fleetwise-regions.md)。
您全權負責以安全且符合相關法律的方式部署命令。
若要使用命令功能：
1. 首先，建立命令資源。或者，指定包含執行命令所需資訊的參數。
1. 指定將接收命令並執行指定動作的目標車輛。
1. 現在，您可以在目標裝置上執行 命令，並檢查命令執行詳細資訊以擷取狀態，並使用 CloudWatch 日誌進一步疑難排解任何問題。
下列各節顯示 車輛和 命令之間的工作流程。
**Topics**
+ [工作流程概觀](#remote-command-vehicles-overview)
+ [車輛工作流程](#iot-remote-command-devices-workflow)
+ [命令工作流程](#iot-remote-command-commands-workflow)
+ [（選用） 命令通知](#remote-command-notifications)
## 工作流程概觀
下列步驟提供 車輛與 命令之間命令工作流程的概觀。當您使用任何 命令 HTTP API 操作時，系統會使用 Sigv4 登入資料來簽署請求。
**注意**
除了 `StartCommandExecution` API 操作之外，透過 HTTP 通訊協定執行的所有操作都會使用控制平面端點。
1.
**建立 MQTT 連線並訂閱命令主題**
若要準備命令工作流程，裝置必須與`iot:Data-ATS`端點建立 MQTT 連線，並訂閱上述的命令請求主題。或者，您的裝置也可以訂閱接受和拒絕的命令回應主題。
1.
**建立車輛模型和命令資源**
您現在可以使用 和 `CreateCommand`控制平面 API 操作來建立 車輛`CreateVehicle`和命令資源。命令資源包含要在車輛上執行命令時套用的組態。
1.
**在目標裝置上啟動命令執行**
使用`StartCommandExecution`資料平面 API 搭配您的帳戶特定`iot:Jobs`端點，在車輛上啟動命令執行。API 會將 protobuf 編碼的承載訊息發佈至命令請求主題。
1.
**更新命令執行的結果**
車輛會處理 命令和收到的承載，然後使用 `UpdateCommandExecution` API 將命令執行的結果發佈至回應主題。如果您的車輛訂閱了接受和拒絕的命令回應主題，將會收到一則訊息，指出雲端服務是否接受或拒絕回應。
1.
**（選用） 擷取命令執行結果**
若要擷取命令執行的結果，您可以使用`GetCommandExecution`控制平面 API 操作。在您的車輛將命令執行結果發佈至回應主題後，此 API 會傳回更新的資訊。
1.
**（選用） 訂閱和管理命令事件**
若要接收命令執行狀態更新的通知，您可以訂閱命令事件主題。然後，您可以使用`CreateTopicRule`控制平面 API 將命令事件資料路由到其他應用程式，例如 AWS Lambda 函數或 Amazon SQS，並在其上建置應用程式。
## 車輛工作流程
下列步驟詳細說明使用 命令功能時的車輛工作流程。
**注意**
本節所述的操作使用 MQTT 通訊協定。
1.
**建立 MQTT 連線**
若要讓您的車輛準備好使用命令功能，必須先連線到 AWS IoT Core 訊息中介裝置。必須允許 車輛執行 `iot:Connect`動作，以連線至 AWS IoT Core 並與訊息中介裝置建立 MQTT 連線。若要尋找 的資料平面端點 AWS 帳戶，請使用 `DescribeEndpoint` API 或 `describe-endpoint` CLI 命令，如下所示。
```
aws iot describe-endpoint --endpoint-type iot:Data-ATS
```
執行此命令會傳回帳戶特定的資料平面端點，如下所示。
```
account-specific-prefix.iot.region.amazonaws.com
```
1.
**命令請求主題的 Susbcribe**
建立連線之後，您的裝置就可以訂閱 AWS IoT 命令 MQTT 請求主題。當您在目標裝置上建立命令並啟動命令執行時，訊息中介裝置會將 protobuf 編碼的承載訊息發佈至請求主題。然後，您的裝置可以接收承載訊息並處理 命令。在此範例中，將 取代*``*為目標車輛的唯一識別符。此 ID 可以是您車輛的唯一識別符或物件名稱
**注意**
傳送至裝置的承載訊息必須使用 protobuf 格式。
```
$aws/commands/things//executions/+/request/protobuf
```
1.
**（選用） 訂閱命令回應主題**
或者，您可以訂閱這些命令回應主題，以接收訊息，指出雲端服務是否接受或拒絕來自裝置的回應。
**注意**
車輛可選擇訂閱 `/accepted`和 `/rejected`回應主題。即使未明確訂閱這些主題，您的 車輛也會自動收到這些回應訊息。
```
$aws/commands/things//executions//response/protobuf/accepted
$aws/commands/things//executions//response/protobuf/rejected
```
1.
**更新命令執行的結果**
目標車輛接著會處理 命令。然後，它會使用 `UpdateCommandExecution` API 將執行結果發佈至下列 MQTT 回應主題。
**注意**
對於指定的車輛和命令執行，** 必須符合裝置訂閱之請求主題中的對應欄位。
```
$aws/commands/things//executions//response/protobuf
```
`UpdateCommandExecution` API 是透過 TLS 驗證的 MQTT 進行的資料平面 API 操作。
+ 如果雲端服務成功處理命令執行結果，則會將訊息發佈至 MQTT 接受的主題。接受的主題使用下列格式。
```
$aws/commands/things//executions//response/protobuf/accepted
```
+ 如果雲端服務無法處理命令執行結果，回應會發佈至 MQTT 拒絕主題。拒絕的主題使用下列格式。
```
$aws/commands/things//executions//response/protobuf/rejected
```
如需此 API 和範例的詳細資訊，請參閱 [更新命令執行結果](send-monitor-remote-command-cli.md#update-remote-command-execution-cli)。
## 命令工作流程
下列步驟詳細說明命令工作流程。
**注意**
本節所述的操作使用 HTTP 通訊協定。
1.
**註冊您的 車輛**
現在您已經準備好 車輛使用 命令功能，您可以註冊 車輛，然後建立將傳送至車輛的命令來準備應用程式。若要註冊車輛，請使用[https://docs.aws.amazon.com/iot-fleetwise/latest/APIReference/API_CreateVehicle.html](https://docs.aws.amazon.com/iot-fleetwise/latest/APIReference/API_CreateVehicle.html)控制平面 API 操作建立車輛模型 （模型資訊清單） 的執行個體。如需詳細資訊和範例，請參閱[建立車輛](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/create-vehicle.html)。
1.
**建立命令**
使用 [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html) HTTP 控制平面 API 操作來建立適用於您目標車輛的命令模型。指定執行命令時要使用的任何參數和預設值，並確保它使用 `AWS-IoT-FleetWise` 命名空間。如需使用此 API 的詳細資訊和範例，請參閱 [建立命令資源](create-manage-remote-command-cli.md#create-remote-command-cli)。
1.
**啟動命令執行**
您現在可以使用[https://docs.aws.amazon.com/iot/latest/apireference/API_iotdata_StartCommandExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iotdata_StartCommandExecution.html)資料平面 API 操作執行您在車輛上建立的命令。 AWS IoT Device Management 會擷取命令和命令參數，並驗證傳入的請求。然後，它會呼叫具有必要參數的 AWS IoT FleetWise API，以產生車輛特定的承載。承載會透過 AWS IoT Device Management MQTT 傳送至裝置訂閱的命令請求主題。如需使用此 API 的詳細資訊和範例，請參閱 [傳送命令 (AWS CLI)](send-monitor-remote-command-cli.md#send-remote-command-cli)。
```
$aws/commands/things//executions/+/request/protobuf
```
**注意**
如果裝置在從雲端傳送命令並使用 MQTT 持久性工作階段時離線，則命令會在訊息中介裝置等待。如果裝置在逾時持續時間之前恢復線上狀態，且已訂閱命令請求主題，則裝置可以處理命令並將結果發佈至回應主題。如果裝置未在逾時持續時間之前恢復上線，則命令執行將會逾時，承載訊息將會過期。
1.
**擷取命令執行**
在裝置上執行 命令之後，請使用[https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommandExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommandExecution.html)控制平面 API 操作來擷取和監控命令執行的結果。您也可以使用 API 取得執行資料的其他資訊，例如上次更新的時間、執行完成的時間，以及指定的參數。
**注意**
若要擷取最新的狀態資訊，您的裝置必須已將命令執行結果發布至回應主題。
如需使用此 API 的詳細資訊和範例，請參閱 [取得命令執行](send-monitor-remote-command-cli.md#get-remote-command-execution-cli)。
## （選用） 命令通知
您可以訂閱命令事件，以在命令執行狀態變更時接收通知。下列步驟說明如何訂閱命令事件，然後處理它們。
1.
**建立主題規則**
您可以訂閱命令事件主題，並在命令執行狀態變更時收到通知。您也可以建立主題規則，將車輛處理的資料路由到其他應用程式，例如 AWS Lambda 函數。您可以使用 AWS IoT 主控台或[https://docs.aws.amazon.com/iot/latest/apireference/API_CreateTopicRule.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateTopicRule.html) AWS IoT Core 控制平面 API 操作來建立主題規則。如需詳細資訊，請參閱[建立 和 AWS IoT 規則](https://docs.aws.amazon.com/iot/latest/developerguide/iot-create-rule.html)。
在此範例中，將 取代``為您要接收通知之命令的識別符，並將 ``取代為命令執行的狀態。
```
$aws/events/commandExecution//
```
**注意**
若要接收所有命令和命令執行狀態的通知，您可以使用萬用字元並訂閱下列主題。
```
$aws/events/commandExecution/+/#
```
1.
**接收和處理命令事件**
如果您在上一個步驟中建立了主題規則來訂閱命令事件，則可以管理您收到的命令推播通知。您也可以選擇性地在其上建置應用程式，例如使用您建立的主題規則搭配 AWS Lambda、Amazon SQS、Amazon SNS 或 AWS Step Functions。
下列程式碼顯示您將收到的命令事件通知的範例承載。
```
{
"executionId": "2bd65c51-4cfd-49e4-9310-d5cbfdbc8554",
"status":"FAILED",
"statusReason": {
"reasonCode": "4",
"reasonDescription": ""
},
"eventType": "COMMAND_EXECUTION",
"commandArn":"arn:aws:iot:us-east-1:123456789012:command/0b9d9ddf-e873-43a9-8e2c-9fe004a90086",
"targetArn":"arn:aws:iot:us-east-1:123456789012:thing/5006c3fc-de96-4def-8427-7eee36c6f2bd",
"timestamp":1717708862107
}
```
# 建立和管理命令
**重要**
存取特定 AWS IoT FleetWise 功能目前已封鎖。如需詳細資訊，請參閱[AWS AWS IoT FleetWise 中的區域和功能可用性](fleetwise-regions.md)。
您可以設定可重複使用的遠端動作，或傳送一次性的立即指示至您的裝置。使用此功能時，您可以指定裝置可以近乎即時執行的指示。命令可讓您為目標車輛設定可重複使用的遠端動作。建立命令之後，您可以啟動以特定車輛為目標的命令執行。
本主題說明如何使用 AWS IoT Core API 或 建立和管理命令資源 AWS CLI。它說明如何在命令資源上執行下列動作。
**Topics**
+ [建立命令資源](#create-remote-command-cli)
+ [擷取命令的相關資訊](#get-remote-command-cli)
+ [列出您帳戶中的命令](#list-remote-command-cli)
+ [更新或取代命令資源](#update-remote-command-cli)
+ [刪除命令資源](#delete-remote-command-cli)
## 建立命令資源
您可以使用[https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html) AWS IoT Core 控制平面 API 操作或 AWS IoT FleetWise 主控台來建立命令。
### 建立命令 （主控台）
您可以使用 AWS IoT FleetWise 主控台來建立命令。
**建立命令**
1. 開啟 [AWS IoT FleetWise 主控台](https://console.aws.amazon.com/iotfleetwise)。
1. 在導覽窗格中，選擇**命令**。
1. 選擇**建立命令**。
1. 指定唯一的命令 ID，協助您識別要在車輛上執行的命令。
1. （選用） 指定選用的顯示名稱和描述。
1. （選用） 選取致動器和預設參數值。參數指定目標車輛在收到命令時可執行的動作。如果您未新增參數，則需要在執行命令時提供參數。
1. 選擇授予許可以產生命令承載的 IAM 角色。請參閱[控制存取](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/controlling-access.html#generate-command-payload)。
1. 選擇**建立命令**。
### 建立命令 (AWS CLI)
下列範例示範如何使用 參數建立命令。
#### 建立命令時的考量事項
當您在 中建立命令時 AWS IoT FleetWise：
+ 您必須指定 `roleArn`，授予在您的車輛上建立和執行命令的許可。如需範例政策的詳細資訊，包括啟用 KMS 金鑰的時間，請參閱 [授予使用 產生命令承載的 AWS IoT Device Management 許可 AWS IoT FleetWise](controlling-access.md#generate-command-payload)。
+ 您必須指定 `AWS-IoT-FleetWise`做為命名空間。
+ 您可以略過 `mandatory-parameters` 欄位，並在執行時間指定它們。或者，您可以使用參數建立命令，並選擇性地為其指定預設值。如果您指定了預設值，則在執行時間，您可以使用這些值，或透過指定您自己的值來覆寫這些值。如需這些其他範例，請參閱 [命令使用案例](remote-command-use-cases.md)。
+ 您可以為 `mandatory-parameters` 欄位指定最多三個名稱/值對。不過，在車輛上執行 命令時，只接受一個名稱值對，而 `name` 欄位必須使用完整名稱與`$actuatorPath.`字首。
+ 將 *command-id* 取代為命令的唯一識別符。您可以使用 UUID、英數字元、"-" 和 "\$1"。
+ 將 *role-arn* 取代為授予您建立和執行命令許可的 IAM 角色，例如 `"arn:aws:iam:accountId:role/FwCommandExecutionRole"`。
+ （選用） 以易於使用的命令名稱取代 *display-name*，並以有意義的命令描述取代*描述*。
+ 將`mandatory-parameters`物件*的名稱*和*值*取代為所建立命令的必要資訊。`name` 欄位是訊號目錄中定義為字`$actuatorPath.`首的完整名稱。例如， `name` 可以是 *\$1actuatorPath.Vehicle.Chassis.SteeringWheel.HandsOff.HandsOffSteeringMode*，`value`也可以是指示轉向模式狀態的布林值，例如 *\$1"B"： false\$1*。
```
aws iot create-command --command-id command-id \
--role-arn role-arn \
--description description \
--display-name display-name \
--namespace "AWS-IoT-FleetWise" \
--mandatory-parameters '[
{
"name": name,
"value": value
}
]'
```
`CreateCommand` API 操作會傳回回應，其中包含 命令的 ID 和 ARN (Amazon Resource Name)。
```
{
"commandId": "HandsOffSteeringMode",
"commandArn": "arn:aws:iot:ap-south-1:123456789012:command/HandsOffSteeringMode"
}
```
## 擷取命令的相關資訊
您可以使用[https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommand.html) AWS IoT Core 控制平面 API 操作來擷取命令資源的相關資訊。
若要取得命令資源的相關資訊，請執行下列命令。將 *command-id* 取代為建立命令時使用的識別符。
```
aws iot get-command --command-id command-id
```
`GetCommand` API 操作會傳回包含下列資訊的回應。
+ 命令的 ID 和 ARN (Amazon Resource Name)。
+ 命令建立和上次更新的日期和時間。
+ 命令狀態，指出它是否可以在車輛上執行。
+ 您在建立命令時指定的任何參數。
```
{
"commandId": "HandsOffSteeringMode",
"commandArn": "arn:aws:iot:ap-south-1:123456789012:command/HandsOffSteeringMode"",
"namespace": "AWS-IoT-FleetWise",
"mandatoryParameters":[
{
"name": "$actuatorPath.Vehicle.Chassis.SteeringWheel.HandsOff.HandsOffSteeringMode",
"value": {"B": false }
}
],
"createdAt": "2024-03-23T11:24:14.919000-07:00",
"lastUpdatedAt": "2024-03-23T11:24:14.919000-07:00",
"deprecated": false,
"pendingDeletion": false
}
```
## 列出您帳戶中的命令
您可以使用[https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommands.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommands.html) AWS IoT Core 控制平面 API 操作來列出您建立之帳戶中的所有命令。
若要列出您帳戶中的命令，請執行下列命令。根據預設，API 會傳回為兩個命名空間建立的命令。若要篩選清單以僅顯示為 建立的命令 AWS IoT FleetWise，請執行下列命令。
**注意**
您也可以依遞增或遞減順序排序清單，或篩選清單，僅顯示具有特定命令參數名稱的命令。
```
aws iot list-commands --namespace "AWS-IoT-FleetWise"
```
`ListCommands` API 操作會傳回包含下列資訊的回應。
+ 命令的 ID 和 ARN (Amazon Resource Name)。
+ 命令建立和上次更新的日期和時間。
+ 命令狀態，指出命令是否可以在車輛上執行。
## 更新或取代命令資源
您可以使用[https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateCommand.html) AWS IoT Core 控制平面 API 操作或 AWS IoT FleetWise 主控台來更新命令資源。您可以更新命令的顯示名稱和描述。如果命令目前未使用，您也可以將其棄用。
**注意**
您無法修改執行 命令時要使用的命名空間資訊或參數。
### 更新命令 （主控台）
**更新命令**
若要從主控台更新命令，請前往 AWS IoT FleetWise 主控台的[命令](https://console.aws.amazon.com/iotfleetwise/home#/commands)頁面，並執行下列步驟。
1. 選擇您要更新的命令，然後選擇**編輯**。
1. 編輯命令詳細資訊，然後選擇**儲存變更**。
**棄用命令**
若要從主控台棄用命令，請前往 AWS IoT FleetWise 主控台的[命令](https://console.aws.amazon.com/iotfleetwise/home#/commands)頁面，並執行下列步驟。
1. 選擇您要棄用的命令，然後選擇**棄用**。
1. 確認棄用，然後選擇**棄用**。
### 更新命令 (AWS CLI)
**更新命令**
若要更新命令資源，請執行下列命令。將 *command-id* 取代為您要更新的命令識別符，並提供更新的 *display-name* 和*描述*。
```
aws iot update-command \
--command-id command-id \
--display-name display-name \
--description description
```
`UpdateCommand` API 操作會傳回下列回應。
```
{
"commandId": "HandsOffSteeringMode",
"deprecated": false,
"lastUpdatedAt": "2024-05-09T23:16:51.370000-07:00"
}
```
**棄用命令**
當您打算不再為裝置繼續使用命令或命令已過期時，會棄用命令。下列範例示範如何棄用命令。
```
aws iot update-command \
--command-id command-id \
--deprecated
```
`UpdateCommand` API 操作會傳回回應，其中包含 命令的 ID 和 ARN (Amazon Resource Name)。
```
{
"commandId": "HandsOffSteeringMode",
"deprecated": true,
"lastUpdatedAt": "2024-05-09T23:16:51.370000-07:00"
}
```
一旦命令已棄用，現有的命令執行將繼續在車輛上執行，直到變成終端機為止。若要執行任何新的命令執行，您必須使用 `UpdateCommand` API 還原命令，使其變成可用。如需有關棄用和還原命令及其考量事項的其他資訊，請參閱《 *AWS IoT Core 開發人員指南*》中的[棄用命令資源](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command-deprecate)。
## 刪除命令資源
您可以使用[https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteCommand.html) AWS IoT Core 控制平面 API 操作或 AWS IoT FleetWise 主控台來刪除命令資源。
**注意**
刪除動作為永久性動作，且無法還原。命令將從您的帳戶永久移除。
### 刪除命令 （主控台）
若要從主控台刪除命令，請前往 AWS IoT FleetWise 主控台的[命令](https://console.aws.amazon.com/iotfleetwise/home#/commands)頁面，並執行下列步驟。
1. 選擇您要刪除的命令，然後選擇**刪除**。
1. 確認您想要刪除命令，然後選擇**刪除**。
### 刪除命令 (AWS CLI)
若要刪除命令資源，請執行下列命令。以您要刪除之命令的識別符取代 *command-id*。下列範例顯示如何刪除命令資源。
```
aws iot delete-command --command-id command-id
```
如果刪除請求成功：
+ 如果命令已棄用超過最大逾時 24 小時的持續時間，則會立即刪除命令，而且您會看到 HTTP `statusCode` 為 204。
+ 如果命令未棄用，或已棄用超過最大逾時的持續時間，則命令將處於 `pending deletion` 狀態，您會看到 HTTP `statusCode` 為 202。在 24 小時的逾時上限之後，命令將自動從您的帳戶中移除。
# 開始和監控命令執行
**重要**
對特定 AWS IoT FleetWise 功能的存取目前受到鎖定。如需詳細資訊，請參閱[AWS AWS IoT FleetWise 中的區域和功能可用性](fleetwise-regions.md)。
建立命令資源之後，您可以在目標車輛上啟動命令執行。一旦車輛開始執行命令，就可以開始更新命令執行的結果，並將狀態更新和結果資訊發佈至 MQTT 預留主題。然後，您可以擷取命令執行的狀態，並監控帳戶中執行的狀態。
本主題說明如何使用 AWS CLI or AWS IoT FleetWise 主控台將命令傳送至您的 車輛。它還說明如何監控和更新命令執行的狀態。
**Topics**
+ [更新命令執行結果](#update-remote-command-execution-cli)
+ [取得命令執行](#get-remote-command-execution-cli)
+ [列出您帳戶中的命令執行](#list-remote-command-execution-cli)
+ [刪除命令執行](#delete-remote-command-execution-cli)
## 傳送命令 （主控台）
若要從主控台傳送命令，請前往 AWS IoT FleetWise 主控台[的車輛](https://console.aws.amazon.com/iotfleetwise/home#/vehicles)頁面，並執行下列步驟。
1. 選擇您要傳送命令的車輛。
1. 選擇**執行命令**。
1. 選取命令 ID。
1. 指定命令執行逾時，然後選擇**執行命令**。
## 傳送命令 (AWS CLI)
您可以使用[https://docs.aws.amazon.com/iot/latest/apireference/API_iot_data_StartCommandExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot_data_StartCommandExecution.html) AWS IoT 資料平面 API 操作，將命令傳送至車輛。接著，車輛會將命令轉送至汽車中介軟體服務 （例如 SOME/IP （透過 IP 的可擴展服務導向中介軟體）)，或將其發佈至車輛網路 （例如控制器區域網路 (CAN) 裝置界面）。下列為使用 AWS CLI的範例。
**Topics**
+ [傳送命令時的考量事項](#send-remote-command-considerations)
+ [取得帳戶特定的資料平面端點](#send-remote-command-endpoint)
+ [傳送命令範例](#send-remote-command-example)
### 傳送命令時的考量事項
當您在 中啟動命令執行時 AWS IoT FleetWise：
+ 您必須為車輛佈建 AWS IoT 物件。如需詳細資訊，請參閱[Provision AWS IoT FleetWise 車輛](provision-vehicles.md)。
+ 您必須已使用 建立 命令`AWS-IoT-FleetWise`做為命名空間`role-Arn`，並提供 授予您在 AWS IoT FleetWise 中建立和執行命令的許可。如需詳細資訊，請參閱[建立命令資源](create-manage-remote-command-cli.md#create-remote-command-cli)。
+ 如果您選擇在建立命令時使用為參數指定的任何預設值，則可以略過 `parameters` 欄位。如果`mandatory-parameters`未在建立時指定 ，或者如果您想要透過為參數指定自己的值來覆寫任何預設值，則必須指定 `parameters` 欄位。如需這些其他範例，請參閱 [命令使用案例](remote-command-use-cases.md)。
+ 您可以為 `mandatory-parameters` 欄位指定最多三個名稱/值對。不過，在車輛上執行 命令時，只接受一個名稱/值對，而 `name` 欄位必須使用完整名稱與`$actuatorPath.`字首。
### 取得帳戶特定的資料平面端點
執行 API 命令之前，您必須取得端點的帳戶特定`iot:Jobs`端點 URL。例如，如果您執行此命令：
```
aws iot describe-endpoint --endpoint-type iot:Jobs
```
它會傳回帳戶特定的端點 URL，如以下範例回應所示。
```
{
"endpointAddress": ".jobs.iot..amazonaws.com"
}
```
### 傳送命令範例
若要將命令傳送至車輛，請執行下列命令。
+ 將 *command-arn* 取代為您要執行之命令的 ARN。您可以從 CLI `create-command` 命令的回應取得此資訊。
+ 將 *target-arn* 取代為您要執行命令的目標裝置或 AWS IoT 物件的 ARN。
**注意**
您可以指定 AWS IoT 物件的目標 ARN (AWS IoT FleetWise 車輛）。目前不支援物件群組和機群。
+ 以您在 中取得的帳戶特定端點取代 *endpoint-url*[取得帳戶特定的資料平面端點](#send-remote-command-endpoint)，字首為 `https://`，例如 `https://123456789012abcd.jobs.iot.ap-south-1.amazonaws.com`。
+ 將*名稱*和*值*取代為您使用 CLI `create-command` 建立命令時指定的`mandatory-parameters`欄位。
`name` 欄位是訊號目錄中定義的完整名稱，字首`$actuatorPath.`為 。例如， `name` 可以是 *\$1actuatorPath.Vehicle.Chassis.SteeringWheel.HandsOff.HandsOffSteeringMode*，`value`也可以是指示轉向模式狀態的布林值，例如 *\$1"B"： false\$1*。
+ （選用） 您也可以指定其他參數 `executionTimeoutSeconds`。此選用欄位指定裝置必須以執行結果回應的時間，以秒為單位。您可以將逾時設定為最大值 24 小時。
建立命令執行後，計時器就會啟動。在計時器過期之前，如果命令執行狀態未變更為使其終止的狀態，例如 `SUCCEEDED`或 `FAILED`，則狀態會自動變更為 `TIMED_OUT`。
**注意**
裝置也可以報告`TIMED_OUT`狀態，或將此狀態覆寫為 狀態，例如 `SUCCEEDED`、 `FAILED`或 `REJECTED`，而且命令執行會變成終端機。如需詳細資訊，請參閱[命令執行逾時狀態](remote-command-concepts-states.md#remote-command-execution-status-timeout)。
```
aws iot-jobs-data start-command-execution \
--command-arn command-arn \
--target-arn target-arn \
--execution-timeout-seconds 30 \
--endpoint-url endpoint-url \
--parameters '[
{
"name": name,
"value": value
}
]'
```
`StartCommandExecution` API 操作會傳回命令執行 ID。您可以使用此 ID 查詢命令執行狀態、詳細資訊和命令執行歷史記錄。
```
{
"executionId": "07e4b780-7eca-4ffd-b772-b76358da5542"
}
```
執行 命令後，您的裝置會收到包含下列資訊的通知。`issued_timestamp_ms` 欄位對應至叫用 `StartCommandExecution` API 的時間。`timeout_ms` 對應至叫用 `StartCommandExecution` API 時使用 `executionTimeoutSeconds` 參數設定的逾時值。
```
timeout_ms: 9000000
issued_timestamp_ms: 1723847831317
```
## 更新命令執行結果
若要更新命令執行的狀態，您的裝置必須已建立 MQTT 連線並訂閱下列命令請求主題。
在此範例中，將 取代*``*為目標裝置的唯一識別符，可以是 `VehicleId`或物件名稱，並將 *``*取代為命令執行的識別符。
**注意**
承載必須使用 protobuf 格式。
您的裝置可選擇是否訂閱 `/accepted`和 `/rejected`回應主題。即使您的裝置尚未明確訂閱，也會收到這些回應訊息。
```
// Request topic
$aws/devices//command_executions/+/request/protobuf
// Response topics (Optional)
$aws/devices//command_executions//response/accepted/protobuf
$aws/devices//command_executions//response/rejected/protobuf
```
您的裝置可以將訊息發佈至命令回應主題。處理命令後，它會傳送 protobuf 編碼的回應至此主題。** 欄位必須符合請求主題中的對應欄位。
```
$aws/devices//command_executions//response/
```
裝置發佈對本主題的回應後，您可以使用 `GetCommandExecution` API 擷取更新的狀態資訊。命令執行的狀態可以是此處列出的任何項目。
+ `IN_PROGRESS`
+ `SUCCEEDED`
+ `FAILED`
+ `REJECTED`
+ `TIMED_OUT`
請注意，狀態為 `SUCCEEDED`、 `FAILED`和 的命令執行`REJECTED`為終端機，且狀態是由裝置回報。當命令執行為終端機時，這表示不會進一步更新其狀態或相關欄位。裝置或雲端可能會報告`TIMED_OUT`狀態。如果雲端回報，裝置稍後可能會更新狀態原因欄位。
例如，以下顯示裝置發佈的範例 MQTT 訊息。
**注意**
針對命令執行狀態，如果您的裝置使用 `statusReason` 物件來發佈狀態資訊，您必須確定：
`reasonCode` 使用 模式 `[A-Z0-9_-]+`，長度不超過 64 個字元。
長度`reasonDescription`不超過 1，024 個字元。它可以使用控制字元以外的任何字元，例如新行。
```
{
"deviceId": "",
"executionId": "",
"status": "CREATED",
"statusReason": {
"reasonCode": "",
"reasonDescription": ""
}
}
```
如需示範如何使用 AWS IoT Core MQTT 測試用戶端訂閱主題並查看命令執行訊息的範例，請參閱《 *AWS IoT Core 開發人員指南*》中的[使用 MQTT 測試用戶端檢視命令更新](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command-execution-start-monitor.html#iot-remote-command-execution-update-mqtt)。
## 取得命令執行
您可以使用[https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommandExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommandExecution.html) AWS IoT 控制平面 API 操作來擷取命令執行的相關資訊。您必須已使用 `StartCommandExecution` API 操作執行此命令。
若要擷取已執行命令的中繼資料，請執行下列命令。
+ 將 *execution-id* 取代為 命令的 ID。您可以從 CLI `start-command-execution` 命令的回應取得此資訊。
+ 將 *target-arn* 取代為您要執行命令的目標車輛或 AWS IoT 物件的 ARN。
```
aws iot get-command-execution --execution-id execution-id \
--target-arn target-arn
```
`GetCommandExecution` API 操作會傳回回應，其中包含命令執行的 ARN、執行狀態，以及命令開始執行的時間和完成時間的相關資訊。下列程式碼顯示來自 API 請求的範例回應。
為了提供有關每個命令執行狀態的其他內容，命令功能會提供 `statusReason` 物件。物件包含兩個欄位 `reasonCode`和 `reasonDescription`。使用這些欄位，您的裝置可以提供有關命令執行狀態的其他資訊。此資訊將覆寫從雲端報告的任何預設 `reasonCode`和 `reasonDescription` 。
若要報告此資訊，您的裝置可以將更新的狀態資訊發佈至雲端。然後，當您使用 `GetCommandExecution` API 擷取命令執行狀態時，您會看到最新的狀態碼。
**注意**
執行回應中的 `completedAt` 欄位對應至裝置向雲端回報終端機狀態的時間。在`TIMED_OUT`狀態的情況下，只有在裝置報告 A 逾時時，才會設定此欄位。狀態由雲端設定`TIMED_OUT`時，`TIMED_OUT`狀態不會更新。如需逾時行為的詳細資訊，請參閱 [命令執行逾時狀態](remote-command-concepts-states.md#remote-command-execution-status-timeout)。
```
{
"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/myFrontDoor",
"status": "SUCCEEDED",
"statusReason": {
"reasonCode": "65536",
"reasonDescription": "SUCCESS"
},
"createdAt": "2024-03-23T00:50:10.095000-07:00",
"completedAt": "2024-03-23T00:50:10.095000-07:00",
"Parameters": '{
"$actuatorPath.Vehicle.Chassis.SteeringWheel.HandsOff.HandsOffSteeringMode":
{ "B": true }
}'
}
```
## 列出您帳戶中的命令執行
使用[https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommandExecutions.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommandExecutions.html) AWS IoT Core 控制平面 HTTP API 操作列出您帳戶中的所有命令執行。此範例使用 AWS CLI。
**Topics**
+ [列出命令執行時的考量事項](#list-remote-command-considerations)
+ [列出命令執行範例](#list-remote-command-example)
### 列出命令執行時的考量事項
以下是使用 `ListCommandExecutions` API 時的一些考量。
+ 您必須指定至少 `targetArn`或 ，`commandArn`取決於您是否要列出特定命令或目標車輛的執行。API 請求不能是空的，也不能包含相同請求中的兩個欄位。
+ 您必須僅提供 `startedTimeFilter`或 `completedTimeFilter`資訊。API 請求不能是空的，也不能包含相同請求中的兩個欄位。您可以使用 物件的 `before`和 `after` 欄位，列出在特定時間範圍內建立或完成的命令執行。
+ `before` 和 `after` 欄位不得大於目前時間。根據預設，如果您未指定任何值， `before` 欄位是目前時間， `after` 欄位是目前時間 - 6 個月。也就是說，根據您使用的篩選條件，API 會列出過去六個月內建立或完成的所有執行。
+ 您可以使用 `sort-order` 參數來指定是否要以遞增順序列出執行。根據預設，如果您未指定此欄位，則執行會以遞減順序列出。
+ 當列出命令 ARN 的命令執行時，您無法根據命令執行的狀態來篩選命令執行。
### 列出命令執行範例
下列範例示範如何在 中列出命令執行 AWS 帳戶。
執行 命令時，您必須指定是否要篩選清單，以僅顯示使用 為特定裝置建立的命令執行`targetArn`，還是使用 為特定命令指定的執行`commandArn`。
在此範例中，取代：
+ *``* 您以執行為目標之裝置的 Amazon Resource Number (ARN)，例如 `arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f`。
+ *``* 您以執行為目標之裝置的 Amazon Resource Number (ARN)，例如 `arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f`。
+ *``* 以及您想要列出建立之執行的時間，例如 `2024-11-01T03:00`。
```
aws iot list-command-executions \
--target-arn \
--started-time-filter '{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"
}
]
}
```
## 刪除命令執行
如果您不想再使用命令執行，可以從您的帳戶永久移除它。
**注意**
命令執行只有在進入終端狀態時才能刪除，例如 `SUCCEEDED`、 `FAILED`或 `REJECTED`。
下列範例示範如何使用 命令刪除`delete-command-execution` AWS CLI 命令執行。*``* 將 取代為您要刪除之命令執行的識別符。
```
aws iot delete-command-execution --execution-id
```
如果 API 請求成功，則命令執行會產生 200 狀態碼。您可以使用 `GetCommandExecution` API 來驗證 帳戶中不再存在命令執行。
# 範例：使用命令控制車輛轉向模式 (AWS CLI)
**重要**
對特定 AWS IoT FleetWise 功能的存取目前受到鎖定。如需詳細資訊，請參閱[AWS AWS IoT FleetWise 中的區域和功能可用性](fleetwise-regions.md)。
下列範例示範如何使用 命令功能 AWS CLI。此範例使用 AWS IoT FleetWise 車輛做為目標裝置，示範如何傳送命令以遠端控制轉向模式。
**Topics**
+ [車輛轉向模式範例概觀](#iot-remote-command-tutorial-overview)
+ [先決條件](#iot-remote-command-tutorial-prereq)
+ [使用遠端命令的 IAM 政策](#remote-command-policy)
+ [執行 AWS IoT 命令 (AWS CLI)](#iot-remote-command-tutorial-run)
+ [清除](#remote-command-tutorial-clean)
## 車輛轉向模式範例概觀
在此範例中，您將：
1. 使用 為 操作建立命令資源，`create-command` AWS CLI 以變更車輛的轉向模式。
1. 擷取命令的相關資訊，例如使用 建立或上次更新命令的時間`get-command` AWS CLI。
1. 使用 `start-command-execution` AWS CLI 搭配 轉向模式做為強制性參數，將命令傳送至車輛，然後會在裝置上執行。
1. 使用 取得命令執行的結果`get-command-execution` AWS CLI。您可以檢查執行完成的時間，並擷取執行結果等其他詳細資訊，以及完成執行命令所需的時間。
1. 移除您不想再使用的任何命令和命令執行，以執行清除活動。
## 先決條件
在您執行此範例之前：
+ 將 AWS IoT FleetWise 車輛佈建為 AWS IoT 登錄檔中的 AWS IoT 物件。您還必須將憑證新增至物件並加以啟用，然後將政策連接至物件。然後，您的裝置可以連接到雲端並執行命令。如需詳細資訊，請參閱[佈建 車輛](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/provision-vehicles.html)。
+ 建立 IAM 使用者和 IAM 政策，授予您使用 命令執行 API 操作的許可，如 所示[使用遠端命令的 IAM 政策](#remote-command-policy)。
## 使用遠端命令的 IAM 政策
下表顯示範例 IAM 政策，授予對命令功能之所有控制平面和資料平面 API 操作的存取權。應用程式的使用者將具有執行所有遠端命令 API 操作的許可，如下表所示。
**API 操作**
| API 動作 | 控制/資料平面 | 通訊協定 | Description | 資源 |
| --- | --- | --- | --- | --- |
| CreateCommand | 控制平面 | HTTP | 建立命令資源 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| GetCommand | 控制平面 | HTTP | 擷取命令的相關資訊 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| UpdateCommand | 控制平面 | HTTP | 更新命令或 的相關資訊以取代命令 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| ListCommands | 控制平面 | HTTP | 列出您帳戶中的命令 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| DeleteCommand | 控制平面 | HTTP | 刪除命令 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| StartCommandExecution | 資料平面 | HTTP | 開始執行命令 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| UpdateCommandExecution | 資料平面 | MQTT | 更新命令執行 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| GetCommandExecution | 控制平面 | HTTP | 擷取命令執行的相關資訊 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| ListCommandExecutions | 控制平面 | HTTP | 列出您帳戶中的命令執行 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| DeleteCommandExecution | 控制平面 | HTTP | 刪除命令執行 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
在此範例中，取代：
+ `us-east-1` ， AWS 區域例如 `ap-south-1`。
+ `111122223333` 您的 AWS 帳戶 號碼，例如 `57EXAMPLE833`。
+ `command-id`、 `command-id1`和 `command-id2`，以及您的唯一命令識別符，例如 `LockDoor`或 `TurnOffAC`。
+ `thing-name` 您的 AWS IoT 物件名稱，例如 `my_car`。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"iot:CreateCommand",
"iot:GetCommand",
"iot:ListCommands",
"iot:UpdateCommand",
"iot:DeleteCommand"
],
"Effect": "Allow",
"Resource": [
"arn:aws:iot:us-east-1:111122223333:command/command-id1",
"arn:aws:iot:us-east-1:111122223333:command/command-id2"
]
},
{
"Action": [
"iot:GetCommandExecution",
"iot:ListCommandExecutions",
"iot:DeleteCommandExecution"
],
"Effect": "Allow",
"Resource": [
"arn:aws:iot:us-east-1:111122223333:command/command-id",
"arn:aws:iot:us-east-1:111122223333:thing/thing-name"
]
},
{
"Action": "iot:StartCommandExecution",
"Effect": "Allow",
"Resource": [
"arn:aws:iot:us-east-1:111122223333:command/command-id",
"arn:aws:iot:us-east-1:111122223333:thing/thing-name"
]
}
]
}
```
------
## 執行 AWS IoT 命令 (AWS CLI)
以下說明如何使用 AWS CLI 執行命令操作和變更車輛轉向模式。
1.
**為轉向模式操作建立命令資源**
使用 `create-command`CLI 建立您要傳送到裝置的命令。在此範例中，指定：
+ `command-id` 作為 *`TurnOffSteeringMode`*
+ `role-arn` 因為`role-arn`必須提供 `"arn:aws:iam:accountId:role/FwCommandExecutionRole"` ，因為它是 IAM 角色，授予在您的車輛上建立和執行命令的許可。如需詳細資訊，請參閱[授予使用 產生命令承載的 AWS IoT Device Management 許可 AWS IoT FleetWise](controlling-access.md#generate-command-payload)。
+ `display-name` 為 "*`Turn off steering mode`*"
+ `namespace` 必須 `AWS-IoT-FleetWise`
+ `mandatory-parameters` 作為名稱值對，其中 "*\$1actuatorPath.Vehicle.Chassis.SteeringWheel.TurnOffSteeringMode*" `name`和 defaultValue 作為 `{ "S": "true" }`
**注意**
您也可以建立命令，而無需指定任何必要參數。然後，您必須指定使用 CLI `start-command-execution` 執行命令時要使用的參數。如需範例，請參閱 [命令使用案例](remote-command-use-cases.md)。
**重要**
使用 `AWS-IoT-FleetWise` 命名空間時，您必須確保指定為 一部分`Name`的欄位`mandatory-parameters`使用 `$actuatorPath.`字首，而 `Value` 欄位必須使用 字串資料類型。
```
aws iot create-command \
--command-id TurnOffSteeringMode \
--role-arn "arn:aws:iam:accountId:role/FwCommandExecutionRole" \
--display-name "Turn off steering mode" \
--namespace AWS-IoT-FleetWise \
--mandatory-parameters '[
{
"name": "$actuatorPath.Vehicle.Chassis.SteeringWheel.TurnOffSteeringMode",
"defaultValue": { "S": "true" }
}
]'
```
下列輸出顯示來自 CLI 的範例回應，其中 `ap-south-1`和 `123456789012`是 AWS 區域 和 AWS 帳戶 ID 的範例。
```
{
"commandId": "TurnOffSteeringMode",
"commandArn": "arn:aws:iot:ap-south-1:123456789012:command/TurnOffSteeringMode"
}
```
如需使用此命令的其他範例，請參閱 [建立命令資源](create-manage-remote-command-cli.md#create-remote-command-cli)。
1.
**擷取命令的相關資訊**
執行下列命令來擷取命令的相關資訊，其中 `command-id`是從`create-command`上方操作輸出中的命令 ID。
**注意**
如果您建立多個命令，您可以使用 `ListCommands` API 列出帳戶中的所有命令，然後使用 `GetCommand` API 取得特定命令的其他資訊。如需詳細資訊，請參閱[列出您帳戶中的命令](create-manage-remote-command-cli.md#list-remote-command-cli)。
```
aws iot get-command --command-id TurnOffSteeringMode
```
執行此命令會產生下列回應。您將看到建立命令的時間、上次更新的時間、您指定的任何參數，以及命令是否可在裝置上執行。
```
{
"commandId": "TurnOffSteeringMode",
"commandArn": "arn:aws:iot:ap-south-1:123456789012:command/TurnOffSteeringMode",
"namespace": "AWS-IoT-FleetWise",
"mandatoryParameters":[
{
"name": "$actuatorPath.Vehicle.Chassis.SteeringWheel.TurnOffSteeringMode",
"defaultValue": {"S": "true" }
}
],
"createdAt": "2024-03-23T00:50:10.095000-07:00",
"lastUpdatedAt": "2024-03-23T00:50:10.095000-07:00",
"deprecated": false
}
```
如需使用此命令的其他範例，請參閱 [擷取命令的相關資訊](create-manage-remote-command-cli.md#get-remote-command-cli)。
1.
**啟動命令執行**
執行下列命令以開始執行命令，其中 `command-arn`是從`get-command`上方操作輸出中的命令 ARN。`target-arn` 是您執行命令的目標裝置的 ARN，例如 *`myVehicle`*。
在此範例中，由於您在建立命令時提供參數的預設值，因此 `start-command-execution` CLI 可以在執行命令時使用這些值。您也可以選擇覆寫預設值，方法是在使用 CLI 時為參數指定不同的值。
```
aws iot-data start-command-execution \
--command-arn arn:aws:iot:ap-south-1:123456789012:command/TurnOffSteeringMode \
--target-arn arn:aws:iot:ap-south-1:123456789012:thing/myVehicle
```
執行此命令會傳回命令執行 ID。您可以使用此 ID 來查詢命令執行狀態、詳細資訊和命令執行歷史記錄。
```
{
"executionId": "07e4b780-7eca-4ffd-b772-b76358da5542"
}
```
如需使用 CLI 的其他範例，請參閱 [傳送命令 (AWS CLI)](send-monitor-remote-command-cli.md#send-remote-command-cli)。
1.
**擷取命令執行的相關資訊**
執行下列命令，以擷取您在目標裝置上執行之命令的相關資訊。指定`execution-id`您從上方取得做為`start-command-execution`操作輸出的 ，以及 `target-arn`，這是您要鎖定之裝置的 ARN。
**注意**
若要取得最新的狀態資訊，您的裝置必須使用 MQTT API 將更新的狀態資訊發佈至命令的 `UpdateCommandExecution` MQTT 預留回應主題。如需詳細資訊，請參閱[更新命令執行結果](send-monitor-remote-command-cli.md#update-remote-command-execution-cli)。
如果您啟動多個命令執行，您可以使用 `ListCommandExecutions` API 列出帳戶中的所有命令執行，然後使用 `GetCommandExecution` API 取得特定執行的其他資訊。如需詳細資訊，請參閱[列出您帳戶中的命令執行](send-monitor-remote-command-cli.md#list-remote-command-execution-cli)。
```
aws iot get-command-execution \
--execution-id <"07e4b780-7eca-4ffd-b772-b76358da5542"> \
--target-arn arn:aws:iot:us-east-1::thing/myVehicle
```
執行此命令會傳回命令執行、執行狀態、開始執行的時間，以及完成時間的相關資訊。例如，以下回應顯示命令在目標裝置上成功執行，且轉向模式已關閉。
```
{
"executionId": "07e4b780-7eca-4ffd-b772-b76358da5542",
"commandArn": "arn:aws:iot:ap-south-1:123456789012:command/TurnOffSteeringMode",
"targetArn": "arn:aws:iot:ap-south-1:123456789012:thing/myVehicle",
"result": "SUCCEEDED",
"statusReason": {
"reasonCode": "65536",
"reasonDescription": "SUCCESS"
},
"result": {
"KeyName": {
"S": "",
"B": true,
"BIN": null
}
},
"createdAt": "2024-03-23T00:50:10.095000-07:00",
"completedAt": "2024-03-23T00:50:10.095000-07:00",
"parameters": '{
"$actuatorPath.Vehicle.Chassis.SteeringWheel.TurnOffSteeringMode":
{ "S": "true" }
}'
}
```
## 清除
現在您已建立命令並在裝置上執行，如果您不想再使用此命令，可以將其刪除。任何進行中的待定命令執行都會繼續執行，而不會受到刪除請求的影響。
**注意**
或者，如果命令已過期，而且您稍後可能需要用它在目標裝置上執行，您也可以棄用命令。
1.
**（選用） 棄用命令資源**
執行下列命令以取代命令，其中 `command-id`是從`get-command`上方操作輸出中的命令 ID。
```
aws iot update-command \
--command-id TurnOffSteeringMode \
--deprecated
```
執行此命令會傳回輸出，顯示命令已棄用。您也可以使用 CLI 還原命令。
**注意**
您也可以使用 `update-command` CLI 來更新命令的顯示名稱和描述。如需其他資訊，請參閱 [更新或取代命令資源](create-manage-remote-command-cli.md#update-remote-command-cli)。
```
{
"commandId": "TurnOffSteeringMode",
"deprecated": true,
"lastUpdatedAt": "2024-05-09T23:16:51.370000-07:00"
}
```
1.
**刪除 命令**
執行下列命令來刪除由 指定的命令`command-id`。
**注意**
刪除動作是永久的，無法復原。
```
aws iot delete-command --command-id TurnOffSteeringMode
```
如果刪除請求成功，您會看到 HTTP `statusCode`為 202 或 204，這取決於您是否將命令標記為棄用，以及何時棄用。如需詳細資訊和範例，請參閱 [刪除命令資源](create-manage-remote-command-cli.md#delete-remote-command-cli)。
您可以使用 `get-command` CLI 來驗證命令是否已從您的帳戶中移除。
1.
**（選用） 刪除命令執行**
根據預設，所有命令執行都會在您建立後的六個月內刪除。您可以使用 `GetCommandExecution` API 中的 `timeToLive` 參數來檢視此資訊。
或者，如果您的命令執行變成結束，例如當您的執行狀態為 `SUCCEEDED`、 `FAILED`或 之一時`REJECTED`，您可以刪除命令執行。執行下列命令來刪除執行，其中 `execution-id`是上述`get-command-execution`操作輸出中的執行 ID。
```
aws iot delete-command-execution \
--execution-id "07e4b780-7eca-4ffd-b772-b76358da5542"
```
您可以使用 `get-command-execution` CLI 來驗證命令執行是否已從您的帳戶中移除。
# 命令使用案例
**重要**
對特定 AWS IoT FleetWise 功能的存取目前受到鎖定。如需詳細資訊，請參閱[AWS AWS IoT FleetWise 中的區域和功能可用性](fleetwise-regions.md)。
使用命令功能時，您可以在下列案例中建立和執行命令：
+ 您可以在建立期間省略參數，並僅指定命令 ID。在此情況下，您需要指定在目標裝置上執行 命令時要使用的參數。
+ 您可以指定一或多個參數，並在建立命令時為其設定預設值。提供預設值有助於防止您傳送不正確的命令。
+ 您可以指定一或多個參數，並在建立命令時為其設定值。可以提供多個參數，但只會執行其中一個參數，而且此參數`Name`的欄位必須使用 `$actuatorPath`字首。
本節提供 `CreateCommand`和 `StartCommandExecution` API 以及使用 參數的一些使用案例。它也會顯示一些使用 命令搭配狀態範本的範例。
**Topics**
+ [建立不含參數的命令](#remote-command-use-case1)
+ [建立具有參數預設值的命令](#remote-command-use-case2)
+ [使用參數值建立命令](#remote-command-use-case3)
+ [搭配狀態範本使用命令](#remote-command-use-cases-templates)
## 建立不含參數的命令
下列使用案例顯示如何使用 `CreateCommand` API 或 `create-command` CLI 來建立不含參數的命令。當您建立命令時，只需要提供命令 ID 和角色 ARN。
此使用案例在經常性使用案例中特別有用，例如當您想要多次將相同的命令傳送到車輛時。在此情況下，命令不會繫結至特定傳動器，並可讓您彈性地在任何傳動器上執行命令。使用 `StartCommandExecution` API 或 `start-command-execution`CLI 執行命令時，您必須在執行時間指定參數，其中包含致動器和實體訊號值。
### 建立不含`mandatory-parameters`輸入的命令
此使用案例示範如何在沒有任何必要參數輸入的情況下建立命令。
```
aws iot create-command \
--command-id "UserJourney1" \
--role-arn "arn:aws:iam:accountId:role/FwCommandExecutionRole" \
--description "UserJourney1 - No mandatory parameters" \
--namespace "AWS-IoT-FleetWise"
```
### 執行在沒有`mandatory-parameters`輸入的情況下建立的命令
在此第一個範例中，上述建立的 命令可讓您在任何作動器上執行命令，而不受限制。若要`actuator1`將 設定為 10 的值，請執行：
```
aws iot-jobs-data start-command-execution \
--command-arn arn:aws:iot:region:111122223333:command/UserJourney1 \
--target-arn arn:aws:iot:region:111122223333:thing/target-vehicle \
--parameters '{
"$actuatorPath.Vehicle.actuator1": {"S": "10"}
}'
```
同樣地，您可以執行 命令，將 `actuator3`設定為 的值`true`。
```
aws iot-jobs-data start-command-execution \
--command-arn arn:aws:iot:region:111122223333:command/UserJourney1 \
--target-arn arn:aws:iot:region:111122223333:thing/target-vehicle \
--parameters '{
"$actuatorPath.Vehicle.actuator3": {"S": "true"}
}'
```
## 建立具有參數預設值的命令
此命令只允許您在指定的作動器上執行命令。提供預設值有助於防止您傳送不正確的命令。例如，可以使用預設值來設定鎖定和解鎖門的`LockDoor`命令，以避免命令意外解鎖門。
當您想要多次傳送相同的命令，並在相同的作動器上執行不同的動作時，例如鎖定和解鎖車輛的門時，此使用案例特別有用。如果您想要將致動器設定為預設值，則不需要將 qny 傳遞`parameters`給 `start-command-execution` CLI。如果您在 CLI `start-command-execution` `parameters`中為 指定不同的值，則會覆寫預設值。
### 使用 的預設值建立命令 `mandatory-parameters`
下列命令顯示如何為 致動器 1 提供預設值。
```
aws iot create-command \
--command-id "UserJourney2" \
--namespace "AWS-IoT-FleetWise" \
--role-arn "arn:aws:iam:accountId:role/FwCommandExecutionRole" \
--mandatory-parameters '[
{
"name": "$actuatorPath.Vehicle.actuator1",
"defaultValue": {"S": "0"}
}
]'
```
### 執行使用 的預設值建立的命令 `mandatory-parameters`
命令`UserJourney2`可讓您執行命令，而不需要在執行時間傳遞輸入值。在此情況下，執行時間的執行將使用建立期間指定的預設值。
```
aws iot-data start-command-execution \
--command-arn arn:aws:iot:region:111122223333:command/UserJourney3 \
--target-arn arn:aws:iot:region:111122223333:thing/target-vehicle
```
您也可以在執行時間期間，為相同的作動器 - 作動器 1 傳遞不同的值，這會覆寫預設值。
```
aws iot-jobs-data start-command-execution \
--command-arn arn:aws:iot:region:111122223333:command/UserJourney3 \
--target-arn arn:aws:iot:region:111122223333:thing/target-vehicle \
--parameters '{
"$actuatorPath.Vehicle.actuator1": {"S": "139"}
}'
```
## 使用參數值建立命令
此命令只允許您在指定的作動器上執行命令。它也會強制您在執行時間期間設定致動器的值。
當您希望最終使用者在車輛上執行某些動作器時，此使用案例特別有用。
**注意**
您可以有超過 個`mandatory-parameters`輸入的名稱值對，其中有部分或全部的預設值。然後，在執行時間，您可以判斷要在啟動器上執行時使用的參數，前提是啟動器名稱使用完整名稱與`$actuatorPath.`字首。
### 建立不含預設值的 命令 `mandatory-parameters`
此命令只允許您在指定的作動器上執行命令。它也會強制您在執行時間期間設定致動器的值。
```
aws iot create-command \
--command-id "UserJourney2" \
--namespace "AWS-IoT-FleetWise" \
--role-arn "arn:aws:iam:accountId:role/FwCommandExecutionRole" \
--mandatory-parameters '[
{
"name": "$actuatorPath.Vehicle.actuator1"
}
]'
```
### 執行在沒有預設值的情況下為 建立的命令 `mandatory-parameters`
執行 命令時，在此情況下，您必須指定 致動器 1 的值。以下顯示的命令執行會成功將 的值設定為 `actuator1` `10`。
```
aws iot-data start-command-execution \
--command-arn arn:aws:iot:region:111122223333:command/UserJourney2 \
--target-arn arn:aws:iot:region:111122223333:thing/target-vehicle \
--parameters '{
"$actuatorPath.Vehicle.actuator1": {"S": "10"}
}'
```
## 搭配狀態範本使用命令
您也可以使用命令 API 操作進行狀態資料收集和處理。例如，您可以擷取一次性狀態快照，或啟用或停用狀態範本，以開始或停止收集車輛狀態資料。下列範例示範如何搭配狀態範本使用命令功能。如需詳細資訊，請參閱[用於收集和處理資料的狀態範本操作](state-template-api-operations.md)
**注意**
指定為`mandatory-parameters`輸入一部分的名稱欄位必須使用 `$stateTemplate`字首。
### 範例 1：使用預設值為狀態範本建立命令
此範例說明如何使用 `create-command` CLI 來啟用狀態範本。
```
aws iot create-command \
--command-id \
--display-name "Activate State Template" \
--namespace AWS-IoT-FleetWise \
--mandatory-parameters '[
{
"name": "$stateTemplate.name"
},
{
"name": "$stateTemplate.operation",
"defaultValue": {"S": "activate"}
}
]'
```
同樣地，以下命令顯示如何將 `start-command-execution` CLI 用於狀態範本的範例。
```
aws iot-data start-command-execution \
--command-arn arn:aws:iot:region:111122223333:command/ \
--target-arn arn:aws:iot:region:111122223333:thing/ \
--parameters '{
"$stateTemplate.name": {"S": "ST345"}
}'
```
### 範例 2：為沒有預設值的狀態範本建立命令
下列命令會建立多個狀態範本，而沒有任何參數的預設值。它會強制您使用這些參數及其值來執行命令。
```
aws iot create-command \
--command-id \
--display-name "Activate State Template" \
--namespace AWS-IoT-FleetWise \
--mandatory-parameters '[
{
"name": "$stateTemplate.name",
"defaultValue": {"S": "ST123"}
},
{
"name": "$stateTemplate.operation",
"defaultValue": {"S": "activate"}
},
{
"name": "$stateTemplate.deactivateAfterSeconds",
"defaultValue": {"L": "120"}
}
]'
```
下列命令顯示如何針對上述範例使用 `start-command-execution` CLI。
```
aws iot-data start-command-execution \
--command-arn arn:aws:iot:region:111122223333:command/ \
--target-arn arn:aws:iot:region:111122223333:thing/ \
--parameters '{
"$stateTemplate.name": {"S": "ST345"},
"$stateTemplate.operation": {"S": "activate"},
"$stateTemplate.deactivateAfterSeconds" : {"L": "120"}
```