本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # AWS IoT Device Management 命令 **重要** 本文件說明如何在 [中使用命令功能 AWS IoT Device Management](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command-concepts.html#command-iot-namespace)。如需針對 使用此功能的詳細資訊 AWS IoT FleetWise，請參閱[遠端命令](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-commands.html)。 您全權負責以安全且符合相關法律的方式部署命令。如需 責任的詳細資訊，請參閱 [AWSAWS IoT 服務條款](https://aws.amazon.com/service-terms/)。 使用 AWS IoT Device Management 命令將指示從雲端傳送至連線至 的裝置 AWS IoT。命令一次以一個裝置為目標，可用於低延遲、高輸送量的應用程式，例如擷取裝置端日誌或啟動裝置狀態變更。 *命令*是由 管理的可重複使用資源 AWS IoT Device Management。其中包含在發佈至裝置之前套用的組態。您可以針對特定使用案例預先定義一組命令，例如開啟燈泡或解鎖車輛門。 AWS IoT 命令功能可讓您： + 使用靜態或動態承載建立可重複使用的命令範本，然後在特定裝置上執行這些範本。 + 目標裝置已註冊為 AWS IoT 實物或未註冊的 MQTT 用戶端。 + 在同一裝置上同時執行多個命令。 + 啟用事件通知，並在裝置處理命令時追蹤執行狀態。 下列主題說明如何建立命令、將命令傳送至您的裝置，以及擷取裝置報告的狀態。 **Topics** + [快速入門](iot-commands-quickstart.md) + [命令概念和狀態](iot-remote-command-concepts.md) + [高階命令工作流程](iot-remote-command-workflow.md) + [建立和管理命令](iot-remote-command-create-manage.md) + [開始和監控命令執行](iot-remote-command-execution-start-monitor.md) + [取代指令資源](iot-remote-command-deprecate.md) # 快速入門 完成以下步驟以傳送您的第一個命令： 1. **先決條件** - 確保您已加入 IoT Core、連線至 IoT Core 的裝置、 Commands API 操作的 IAM 許可，以及安裝在裝置上的 MQTT 用戶端程式庫。 1. **建立命令** - 定義具有靜態承載的命令，或指定裝置動作的承載範本。請參閱 [建立命令資源](iot-remote-command-create-manage.md#iot-remote-command-create)。 1. **識別您的裝置** - 將您的裝置註冊為 IoT 物件或記下其 MQTT 用戶端 ID。請參閱 [目標裝置考量事項](iot-remote-command-execution-start-monitor.md#iot-command-execution-target)。 1. **設定許可** - 設定 IAM 政策，允許您的裝置接收命令並發佈回應。 1. **訂閱主題** - 設定您的裝置以訂閱命令請求和回應主題。請參閱 [為您的命令選擇目標裝置並訂閱 MQTT 主題](iot-remote-command-workflow.md#command-choose-target)。 1. **執行命令** - 在目標裝置上啟動命令執行。請參閱 [啟動命令執行啟動命令執行 （主控台）啟動命令執行 (AWS CLI)](iot-remote-command-execution-start-monitor.md#iot-remote-command-execution-start)。 **常見使用案例：** + *遠端診斷 *- 擷取日誌、執行診斷、檢查裝置運作狀態 + *組態更新* - 變更設定、更新參數、切換功能 + *裝置控制* - 鎖定/解鎖、開啟/關閉電源、模式變更 # 命令概念和狀態 使用 AWS IoT 命令將指示從雲端傳送至連線的裝置。若要使用此功能： 1. 建立具有承載的命令，其中包含在裝置上執行 所需的組態。 1. 指定將接收承載並執行動作的目標裝置。 1. 在目標裝置上執行 命令並擷取狀態資訊。若要疑難排解問題，請參閱 CloudWatch 日誌。 如需有關此工作流程的詳細資訊，請參閱 [高階命令工作流程](iot-remote-command-workflow.md)。 **Topics** + [命令關鍵概念](#iot-command-concepts) + [命令狀態](#iot-command-states) + [命令執行狀態](#iot-command-execution-status) ## 命令關鍵概念 下列重要概念可協助您了解 命令功能。本文件中會持續使用術語： + *命令* - 可重複使用的範本，定義裝置指示 + *執行* - 在裝置上執行之命令的執行個體 + *物件名稱* - 在 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。裝置端邏輯會決定保留主題的執行行為和狀態報告。 ### 參數值條件 使用承載範本建立命令時，請定義值條件，以在執行之前驗證參數值。值條件可確保參數符合要求，防止無效執行。 **[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) 時評估。失敗的驗證會傳回錯誤，並防止建立執行。 ### 參數值優先順序和評估 使用承載範本啟動命令執行時，會使用下列優先順序解析參數值： 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】 驗證 ## 命令狀態 您 中的命令 AWS 帳戶 可以處於三種狀態之一：*可用*、*已棄用*或*待刪除*。 **可用性** 成功建立後，命令會處於可用狀態，並且可以在裝置上執行。 **已棄用** 不再需要時，將命令標記為棄用。已棄用的命令無法啟動新的執行，但待定執行會繼續完成。若要啟用新的執行，請將命令還原為可用狀態。 **待刪除** 當您將命令標記為刪除時，如果已取代超過最大逾時 （預設值：12 小時），則會自動將其刪除。此動作為永久性。如果超過逾時仍未棄用或棄用，則命令會進入待定刪除狀態，並在逾時過期後移除。 ## 命令執行狀態 當您在目標裝置上啟動執行時，它會進入 `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) ### 非終端命令執行 如果可以接受來自裝置的更新，則執行是非終端的。非終端執行會被視為*作用中*。下列狀態為非終端狀態： + **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)。 ### 終端機命令執行 當執行不再接受來自裝置的更新時，就會變成終端機。下列狀態為終端機。執行可以從任何非終端狀態轉換為終端狀態：`IN_PROGRESS`、 `CREATED`或 `TIMED_OUT`。 + **SUCCEEDED (成功)** 如果裝置成功完成執行，則可以將回應發佈至命令回應主題，並將狀態更新為 `SUCCEEDED`。 + **失敗** 當裝置無法完成執行時，可以發佈回應至命令回應主題，並將狀態更新至 `FAILED`。使用 `statusReason` 物件中的 `reasonCode`和 `reasonDescription` 欄位或 CloudWatch 日誌，對失敗進行故障診斷。 + **REJECTED** 當裝置收到無效或不相容的請求時，它可以調用狀態為 的 `UpdateCommandExecution` API`REJECTED`。使用 `statusReason` 物件中的 `reasonCode`和 `reasonDescription` 欄位或 CloudWatch 日誌來疑難排解問題。 # 高階命令工作流程 此工作流程顯示裝置如何與 AWS IoT Device Management 命令互動。所有 HTTP API 請求都使用 [Sigv4 登入](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html)資料進行簽署。 ![\[AWS IoT Device Management 裝置命令高階工作流程概觀。\]](http://docs.aws.amazon.com/zh_tw/iot/latest/developerguide/images/device-command-workflow.png) **Topics** + [建立和管理命令](#command-create-command) + [為您的命令選擇目標裝置並訂閱 MQTT 主題](#command-choose-target) + [啟動和監控目標裝置的命令執行](#command-command-executions) + [（選用） 啟用命令事件的通知](#iot-remote-command-commands-notifications) ## 建立和管理命令 若要建立和管理裝置的命令，請執行下列步驟。 1. **建立命令資源** 從 Command [Hub 或使用 API 建立命令](https://console.aws.amazon.com/iot/home#/commandHub)。 [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html) 1. **指定承載** 以任何格式提供承載。指定內容類型，以確保正確的裝置解譯。 對於具有承載範本的動態命令，最終承載會在執行時間使用您提供的參數產生。範本僅支援 JSON 格式，但產生的承載可以 JSON 或 CBOR 傳送。 1. **（選用） 管理建立的命令** 建立後更新顯示名稱和描述。不再需要時，將命令標記為已棄用，或將其永久刪除。若要修改承載資訊，請建立新的 命令。 ## 為您的命令選擇目標裝置並訂閱 MQTT 主題 選擇您的目標裝置，並設定 MQTT 主題以接收命令和發佈回應。 1. **選擇命令的目標裝置** 選擇要接收和執行 命令的目標裝置。針對已註冊的裝置使用物件名稱，或未註冊裝置的用戶端 ID。如需詳細資訊，請參閱[目標裝置考量事項](iot-remote-command-execution-start-monitor.md#iot-command-execution-target)。 1. **設定 AWS IoT 裝置政策** 設定授予許可以接收執行和發佈更新的 IAM 政策。如需政策範例[範例 IAM 政策](iot-remote-command-execution-start-monitor.md#iot-remote-command-execution-update-policy)，請參閱 。 1. **建立 MQTT 連線** 將裝置連接至訊息中介裝置，並訂閱請求和回應主題。裝置需要 `iot:Connect` 許可。使用 `DescribeEndpoint` API 或 CLI `describe-endpoint` 命令尋找您的資料平面端點： ``` aws iot describe-endpoint --endpoint-type iot:Data-ATS ``` 執行此命令會傳回帳戶特定的資料平面端點，如下所示。 ``` account-specific-prefix.iot.region.amazonaws.com ``` 1. **訂閱命令主題** 訂閱 命令請求主題。當您啟動執行時，訊息中介裝置會將承載發佈至此主題。您的裝置會接收並處理 命令。 （選用） 訂閱回應主題 (`accepted` 或 `rejected`) 以接收雲端服務是否接受或拒絕裝置回應的確認。 在此範例中，取代： + *``* ，`thing`或`client`取決於您要鎖定的裝置是否已註冊為 IoT 物件，或指定為 MQTT 用戶端。 + *``* 具有目標裝置的唯一識別符。此 ID 可以是唯一的 MQTT 用戶端 ID 或物件名稱。 **注意** 如果承載類型不是 JSON 或 CBOR，則命令請求主題中可能不存在 ** 欄位。若要取得承載格式，建議您使用 MQTT5 從 MQTT 訊息標頭取得格式資訊。如需詳細資訊，請參閱[命令主題](reserved-topics.md#reserved-topics-commands)。 ``` $aws/commands///executions/+/request/ $aws/commands///executions/+/response/accepted/ $aws/commands///executions/+/response/rejected/ ``` ## 啟動和監控目標裝置的命令執行 建立命令並指定命令的目標之後，您可以執行下列步驟，在目標裝置上開始執行。 1. **在目標裝置上啟動命令執行** 從 [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) 或使用 `StartCommandExecution` API 搭配您帳戶特定的端點來啟動執行。`iot:Data-ATS` 用於雙堆疊 (IPv4/IPv6) 或僅用於 `iot:Jobs` IPv4。 API 會將承載發佈至 命令請求主題。 **注意** 如果裝置離線並使用 MQTT 持久性工作階段，則 Command 會等待訊息中介裝置。當裝置在逾時前重新連線時，可以處理 命令並發佈結果。如果逾時過期，則執行會逾時，並將捨棄承載。 1. **更新命令執行的結果** 裝置會收到承載、處理 命令、執行指定的動作，以及使用 `UpdateCommandExecution` MQTT API 將結果發佈至 命令回應主題。如果訂閱接受和拒絕的主題，裝置會收到雲端服務是否接受或拒絕回應的確認。 根據您在請求主題中指定的內容，** 可以是實物或用戶端，而 ** 可以是您的 AWS IoT 實物名稱或 MQTT 用戶端 ID。 **注意** ** 只能是命令回應主題中的 JSON 或 CBOR。 ``` $aws/commands///executions//response/ ``` 1. **（選用） 擷取命令執行結果** 從 AWS IoT 主控台或使用 擷取執行結果`GetCommandExecution`。裝置必須將結果發佈至 Commands 回應主題，以取得最新資訊。檢視其他詳細資訊，包括上次更新時間、結果和完成時間。 ## （選用） 啟用命令事件的通知 訂閱 命令事件，以在執行狀態變更時收到通知。如需命令執行事件的詳細資訊，包括事件訊息格式和承載屬性，請參閱 [命令執行事件](command-events.md)。 1. **建立主題規則** 訂閱 Commands 事件主題以取得狀態變更通知。使用 AWS IoT 主控台或 建立主題規則，將裝置資料路由到其他服務 AWS Lambda， AWS IoT 例如 Amazon SQS 和 AWS Step Functions[建立 AWS IoT 規則](iot-create-rule.md)。 在此範例中，將 ``取代為您要接收通知之命令的識別符，並將 ``取代為命令執行的狀態。 ``` $aws/events/commandExecution// ``` **注意** 若要接收所有命令和命令執行狀態的通知，您可以使用萬用字元並訂閱下列主題。 ``` $aws/events/commandExecution/+/# ``` 1. **接收和處理命令事件** 管理命令推送通知，並使用訂閱的事件建置應用程式。 下列程式碼顯示您將收到的命令事件通知的範例承載。 ``` { "executionId": "2bd65c51-4cfd-49e4-9310-d5cbfdbc8554", "status":"FAILED", "statusReason": { "reasonCode": "DEVICE_TOO_BUSY", "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 Device Management 命令來設定可重複使用的遠端動作，或傳送立即指示至裝置。從 AWS IoT 主控台或使用 建立和管理命令 AWS CLI。 **Topics** + [建立命令資源](#iot-remote-command-create) + [擷取命令的相關資訊](#iot-remote-command-get) + [在 中列出命令 AWS 帳戶](#iot-remote-command-list) + [更新命令資源](#iot-remote-command-update) + [棄用或還原命令資源](#iot-remote-command-deprecatecmd) + [刪除命令資源](#iot-remote-command-delete) ## 建立命令資源 在建立命令時提供下列資訊： + **一般資訊** 提供唯一的命令 ID，以在目標裝置上執行命令時識別命令。選擇性地指定要管理的顯示名稱、描述和標籤。 + **承載** 對於靜態命令，請提供承載定義裝置動作。指定承載格式類型以正確解譯裝置。 如需動態命令，請參閱承載範本屬性。 + **承載範本** 對於動態命令，請提供具有預留位置和參數的 payloadTemplate。選擇性地提供 `defaultValue`和 條件。 AWS IoT Device Management 命令會在執行時間取代預留位置。缺少參數會使用其 defaultValue。所有值都必須滿足定義的條件。 支援以下區分大小寫的預留位置類型： + `${aws:iot:commandexecution::parameter:parameter1}` – 名稱為 之參數值的預留位置`parameter1`。 + `${aws:iot:commandexecution::executionTimeoutSec}` – 執行時間提供的命令執行逾時參數的預留位置。 ### 承載和命令主題 命令預留主題使用基於承載格式類型的格式。 + 對於 `application/json`或 `application/cbor`內容類型，請使用此請求主題： ``` $aws/commands///executions/+/request/ ``` + 對於其他內容類型或未指定的格式，請使用此請求主題。承載格式會出現在 MQTT 訊息標頭中。 ``` $aws/commands///executions/+/request ``` 無論承載類型為何， 命令回應主題都會使用 `json`或 `cbor` 格式。** 必須是 `json`或 `cbor`： ``` $aws/commands///executions//response/ ``` ### 建立命令資源 （主控台） 下列各節說明承載格式考量事項，以及從 主控台建立命令。 **Topics** + [靜態命令承載格式](#iot-commands-payload-format) + [動態命令承載格式](#iot-commands-dynamic-payload-format) + [如何建立命令 （主控台）](#iot-commands-console-how) #### 靜態命令承載格式 承載支援任何最多 32 KB 的格式。指定承載格式類型，以進行安全且正確的裝置解譯。 使用格式 （例如 `application/json`或 `application/cbor`) 指定承載`type/subtype`格式類型。預設：`application/octet-stream`。如需支援的格式，請參閱[常見 MIME 類型](https://developer.mozilla.org/en-US/docs/Web/HTTP/MIME_types/Common_types)。 #### 動態命令承載格式 payloadTemplate 必須是具有至少一個預留位置的有效 JSON，最多可達 32 KB。 對於`AwsJsonSubstitution`預處理器， AWS IoT Device Management Commands 會根據預處理器組態，以 JSON 或 CBOR 格式傳送通知。 #### 如何建立命令 （主控台） 若要從主控台建立命令，請前往 [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) 並遵循下列步驟： 1. 選擇**建立命令**。 1. 指定唯一的命令 ID。 1. （選用） 指定顯示名稱、描述和標籤。 1. 上傳包含裝置動作的承載檔案。指定承載格式類型以正確解譯裝置。 1. （選用） 對於具有預留位置的 JSON 承載範本，參數會預先填入內嵌資料表中以供編輯。 1. （選用） 設定參數值類型 （必要）、預設值和條件。 1. 選擇**建立命令**。 ### 建立命令資源 (CLI) 使用 [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html) API 或 [https://docs.aws.amazon.com/cli/latest/reference/iot/create-command.html](https://docs.aws.amazon.com/cli/latest/reference/iot/create-command.html) CLI 命令來建立命令。 **Topics** + [命令承載](#iot-commands-payload) + [範例 IAM 政策](#iot-remote-command-create-iam) + [靜態命令建立範例](#iot-remote-command-create-example) + [動態命令建立範例](#iot-remote-dynamic-command-create-example) #### 命令承載 提供靜態承載或承載範本。靜態承載是 base64 編碼。對於承載範本，最終承載會在執行時間使用參數值產生。裝置會處理承載並執行指定的動作。指定用於正確裝置接收的承載內容類型。 **注意** 建立命令後無法修改承載。建立新的命令來修改承載。 #### 範例 IAM 政策 使用此 API 操作之前，請確定您的 IAM 政策授權您在裝置上執行此動作。下列範例顯示 IAM 政策，允許使用者執行 `CreateCommand`動作的許可。 在此範例中，取代： + `region` 搭配您的 AWS 區域，例如 `us-east-1`。 + `account-id` 您的 AWS 帳戶 號碼，例如 `123456789012`。 + `command-id` 具有 AWS IoT 命令 ID 的唯一識別符，例如 `LockDoor`。如果您想要傳送多個命令，您可以在 IAM 政策的資源**區段下指定這些命令。 **** ``` { "Version":"2012-10-17", "Statement": { "Action": "iot:CreateCommand", "Effect": "Allow", "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id" } } ``` #### 靜態命令建立範例 下列範例示範如何建立靜態命令。根據您的應用程式，取代： + *``* 具有命令的唯一識別符。例如，若要鎖定房屋的門，您可以指定 *`LockDoor`*。我們建議您使用 UUID。您也可以使用英數字元、"-" 和 "\$1"。 + （選用） *``* *``*和 ，這是選用欄位，您可以用來為命令提供易記的名稱和有意義的描述，例如 *`Lock the doors of my home`*。 + `namespace`，您可以使用它來指定命令的命名空間。它必須是 `AWS-IoT`。如需針對 使用此功能的詳細資訊 AWS IoT FleetWise，請參閱[遠端命令](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-commands.html) + `payload` 包含您在執行 命令時要使用之承載及其內容類型的相關資訊。 ``` aws iot create-command \ --command-id \ --display-name \ --description \ --namespace AWS-IoT \ --payload '{"content":"eyAibWVzc2FnZSI6ICJIZWxsbyBJb1QiIH0=","contentType":"application/json"}' ``` 執行此命令會產生回應，其中包含命令的 ID 和 ARN (Amazon 資源名稱）。例如，如果您在建立期間指定 `LockDoor`命令，則以下顯示執行命令的範例輸出。 ``` { "commandId": "LockDoor", "commandArn": "arn:aws:iot:us-east-1:123456789012:command/LockDoor" } ``` #### 動態命令建立範例 下列範例示範如何建立動態命令。根據您的應用程式，取代： + *``* 具有命令的唯一識別符。例如，若要設定光源狀態，您可以指定 *`Light_Power_Status`*。我們建議您使用 UUID。您也可以使用英數字元、"-" 和 "\$1"。 + （選用） *``* *``*和 ，這是選用欄位，您可以用來為命令提供易記的名稱和有意義的描述，例如 *`Turn a light ON or OFF`*。 + `namespace`，您可以使用它來指定命令的命名空間。它必須是 `AWS-IoT`。如需針對 使用此功能的詳細資訊 AWS IoT FleetWise，請參閱[遠端命令](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-commands.html) + `payloadTemplate` 包含具有 placehodlers 的 JSON 格式 Playoad 範本。 + `preprocessor` 包含預處理器的組態，決定如何處理 payloadTemplate。 + `mandatoryParameter` 包含與 payloadTemplate 中預留位置對應的參數、其類型、預設值和條件。 ``` aws iot create-command \ --command-id Light_Power_Status \ --description "Turn a light ON or OFF" \ --namespace AWS-IoT \ --payload-template '{"powerStatus":"${aws:iot:commandexecution::parameter:powerStatus}"}' \ --preprocessor awsJsonSubstitution={outputFormat=JSON} \ --mandatory-parameters "name=powerStatus, defaultValue={S=OFF}, valueConditions=[{comparisonOperator=IN_SET, operand={strings=['ON','OFF']}}]" ``` 執行此命令會產生回應，其中包含命令的 ID 和 ARN (Amazon 資源名稱）。例如，如果您在建立期間指定 `Light_Power_Status`命令，則以下顯示執行命令的範例輸出。 ``` { "commandId": "Light_Power_Status", "commandArn": "arn:aws:iot:us-east-1:123456789012:command/Light_Power_Status" } ``` ## 擷取命令的相關資訊 建立命令之後，您可以從主控台並使用 擷取其 AWS IoT 相關資訊 AWS CLI。您可以取得下列資訊。 + 命令 ID、Amazon 資源名稱 (ARN)、您為命令指定的任何顯示名稱和描述。 + 命令狀態，指出命令是否可在目標裝置上執行，或是否已被取代或刪除。 + 您提供的承載或 payloadTemplate。 + 您提供的前置處理器。 + 您提供的 mandatoryParameters。 + 命令建立和上次更新的時間。 ### 擷取命令資源 （主控台） 若要從主控台擷取命令，請前往 AWS IoT 主控台的 [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub)，然後選擇您建立的命令以檢視其詳細資訊。 除了命令詳細資訊之外，您還可以查看命令歷史記錄，該歷史記錄提供有關在目標裝置上執行命令的資訊。在裝置上執行此命令後，您可以在此索引標籤上找到執行的相關資訊。 ### 擷取命令資源 (CLI) 使用 [https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommand.html) HTTP 控制平面 API 操作或 [https://docs.aws.amazon.com/cli/latest/reference/get-command.html](https://docs.aws.amazon.com/cli/latest/reference/get-command.html) AWS CLI 命令來擷取命令資源的相關資訊。您必須已經使用 `CreateCommand` API 請求或 CLI `create-command` 建立命令。 #### 範例 IAM 政策 使用此 API 操作之前，請確定您的 IAM 政策授權您在裝置上執行此動作。下列範例顯示 IAM 政策，允許使用者執行 `GetCommand`動作的許可。 在此範例中，取代： + `region` ， AWS 區域例如 `us-east-1`。 + `account-id` 您的 AWS 帳戶 號碼，例如 `123456789023`。 + `command-id` 您的 AWS IoT 唯一命令識別符，例如 `LockDoor`或 `Light_Power_Status`。如果您想要擷取多個命令，您可以在 IAM 政策的資源**區段下指定這些命令。 **** ``` { "Version":"2012-10-17", "Statement": { "Action": "iot:GetCommand", "Effect": "Allow", "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id" } } ``` #### 擷取命令範例 (AWS CLI) 下列範例說明如何使用 擷取命令的相關資訊`get-command` AWS CLI。根據您的應用程式，將 *``*取代為您要擷取資訊的命令的識別符。您可以從 CLI `create-command` 的回應取得此資訊。 ``` aws iot get-command --command-id ``` 執行此命令會產生回應，其中包含命令、承載及其建立和上次更新時間的相關資訊。它也提供指出命令是否已棄用或正在刪除的資訊。 例如，下列程式碼顯示範例回應。 ``` { "commandId": "LockDoor", "commandArn": "arn:aws:iot:::command/LockDoor", "namespace": "AWS-IoT", "payload":{ "content": "eyAibWVzc2FnZSI6ICJIZWxsbyBJb1QiIH0=", "contentType": "application/json" }, "createdAt": "2024-03-23T00:50:10.095000-07:00", "lastUpdatedAt": "2024-03-23T00:50:10.095000-07:00", "deprecated": false, "pendingDeletion": false } ``` ## 在 中列出命令 AWS 帳戶 建立命令之後，您可以檢視您在帳戶中建立的命令。在清單中，您可以找到下列相關資訊： + 命令 ID，以及您為命令指定的任何顯示名稱。 + 命令的 Amazon 資源名稱 (ARN)。 + 命令狀態，指出命令是否可在目標裝置上執行，或是否已棄用。 **注意** 此清單不會顯示正在從您的帳戶中刪除的 。如果命令正在等待刪除，您仍然可以使用其命令 ID 檢視這些命令的詳細資訊。 + 命令建立和上次更新的時間。 ### 列出您帳戶中的命令 （主控台） 在 AWS IoT 主控台中，您可以前往 [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub)，找到您建立的命令清單及其詳細資訊。 ### 列出您帳戶中的命令 (CLI) 若要列出您建立的命令，請使用 [https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommands.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommands.html) API 操作或 [https://docs.aws.amazon.com/cli/latest/reference/iot/list-commands.html](https://docs.aws.amazon.com/cli/latest/reference/iot/list-commands.html) CLI。 #### 範例 IAM 政策 使用此 API 操作之前，請確定您的 IAM 政策授權您在裝置上執行此動作。下列範例顯示 IAM 政策，允許使用者執行 `ListCommands`動作的許可。 在此範例中，取代： + `region` ， AWS 區域例如 `us-east-1`。 + `account-id` 使用您的 AWS 帳戶 號碼，例如 `123456789012`。 **** ``` { "Version":"2012-10-17", "Statement": { "Action": "iot:ListCommands", "Effect": "Allow", "Resource": "arn:aws:iot:us-east-1:123456789012:command/*" } } ``` #### 在您的帳戶範例中列出命令 下列命令說明如何列出您帳戶中的命令。 ``` aws iot list-commands --namespace "AWS-IoT" ``` 執行此命令會產生回應，其中包含您建立的命令清單、建立命令的時間，以及上次更新的時間。它也提供命令狀態資訊，指出命令是否已棄用或可在目標裝置上執行。如需不同狀態和狀態原因的詳細資訊，請參閱 [命令執行狀態](iot-remote-command-concepts.md#iot-command-execution-status)。 ## 更新命令資源 建立命令之後，您可以更新命令的顯示名稱和描述。 **注意** 無法更新 命令的承載。若要更新此資訊或使用修改後的承載，您需要建立新的命令。 ### 更新命令資源 （主控台） 若要從主控台更新命令，請前往 AWS IoT 主控台的 [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub)，並執行下列步驟。 1. 若要更新現有的命令資源，請選擇您要更新的命令，然後在**動作**下選擇**編輯**。 1. 指定您要使用的顯示名稱和描述，以及任何名稱/值對做為命令的標籤。 1. 選擇**編輯**以使用新設定儲存命令。 ### 更新命令資源 (CLI) 使用[https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateCommand.html)控制平面 API 操作或 [https://docs.aws.amazon.com/cli/latest/reference/iot/update-command.html](https://docs.aws.amazon.com/cli/latest/reference/iot/update-command.html) AWS CLI 來更新命令資源。使用此 API，您可以： + 編輯您建立之命令的顯示名稱和描述。 + 棄用命令資源，或還原已棄用的命令。 #### 範例 IAM 政策 使用此 API 操作之前，請確定您的 IAM 政策授權您在裝置上執行此動作。下列範例顯示 IAM 政策，允許使用者執行 `UpdateCommand`動作的許可。 在此範例中，取代： + `region` ， AWS 區域例如 `us-east-1`。 + `account-id` 使用您的 AWS 帳戶 號碼，例如 `123456789012`。 + `command-id` 您的 AWS IoT 唯一命令識別符，例如 `LockDoor`。如果您想要擷取多個命令，您可以在 IAM 政策中的*資源*區段下指定這些命令。 **** ``` { "Version":"2012-10-17", "Statement": { "Action": "iot:UpdateCommand", "Effect": "Allow", "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id" } } ``` #### 更新命令範例的相關資訊 (AWS CLI) 下列範例示範如何使用 命令更新命令的相關資訊`update-command` AWS CLI 。如需有關如何使用此 API 取代或還原命令資源的資訊，請參閱 [更新命令資源 (CLI)](iot-remote-command-deprecate.md#iot-remote-command-deprecate-cli)。 此範例示範如何更新命令的顯示名稱和描述。根據您的應用程式，將 *``*取代為您要擷取資訊的命令的識別符。 ``` aws iot update-command \ --command-id --displayname \ --description ``` 執行此命令會產生回應，其中包含有關命令和上次更新時間的更新資訊。下列程式碼顯示更新關閉 AC 之命令的顯示名稱和描述的範例請求和回應。 ``` aws iot update-command \ --command-id \ --displayname \ --description ``` 執行此命令會產生下列回應。 ``` { "commandId": "LockDoor", "commandArn": "arn:aws:iot:us-east-1:123456789012:command/LockDoor", "displayName": "Secondary lock door", "description": "Locks doors to my home", "lastUpdatedAt": "2024-05-09T23:15:53.899000-07:00" } ``` ## 棄用或還原命令資源 建立命令之後，如果不想再繼續使用命令，您可以將其標記為已棄用。當您棄用命令時，所有待定命令執行都會繼續在目標裝置上執行，直到達到終端機狀態為止。一旦命令已棄用，如果您想要使用 等命令，將新的命令執行傳送至目標裝置，則必須將其還原。 **注意** 您無法編輯已棄用的命令，或對其執行任何新的執行。若要在裝置上執行新的命令，您必須將其還原，命令狀態才會變更為*可用*。 如需有關棄用和還原命令以及其考量事項的其他資訊，請參閱 [取代指令資源](iot-remote-command-deprecate.md)。 ## 刪除命令資源 如果您不想再使用命令，可以從您的帳戶永久移除該命令。如果刪除動作成功： + 如果命令已棄用超過最大逾時 12 小時的持續時間，則會立即刪除命令。 + 如果命令未棄用，或已棄用超過最大逾時的持續時間，則命令將處於 `pending deletion` 狀態。最長逾時 12 小時後，系統會自動將其從您的帳戶中移除。 **注意** 即使有任何待定的命令執行，也可能會刪除命令。命令將處於待定刪除狀態，並會自動從您的帳戶中移除。 ### 刪除命令資源 （主控台） 若要從主控台刪除命令，請前往 AWS IoT 主控台的 [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub)，然後執行下列步驟。 1. 選擇您要刪除的命令，然後在**動作**下選擇**刪除**。 1. 確認您想要刪除命令，然後選擇**刪除**。 命令將標記為刪除，並在 12 小時後從您的帳戶中永久移除。 ### 刪除命令資源 (CLI) 使用 `DeleteCommand` HTTP 控制平面 API 操作或 `delete-command` AWS CLI 命令來刪除命令資源。如果刪除動作成功，您會看到 HTTP `statusCode`為 204 或 202，且命令會在逾時持續時間上限為 12 小時後自動從您的帳戶刪除。在 204 狀態的情況下，表示命令已刪除。 #### 範例 IAM 政策 使用此 API 操作之前，請確定您的 IAM 政策授權您在裝置上執行此動作。下列範例顯示 IAM 政策，允許使用者執行 `DeleteCommand`動作的許可。 在此範例中，取代： + `region` ， AWS 區域例如 `us-east-1`。 + `account-id` 使用您的 AWS 帳戶 號碼，例如 `123456789012`。 + `command-id` 您的 AWS IoT 唯一命令識別符，例如 `LockDoor`。如果您想要擷取多個命令，您可以在 IAM 政策的資源**區段下指定這些命令。 **** ``` { "Version":"2012-10-17", "Statement": { "Action": "iot:DeleteCommand", "Effect": "Allow", "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id" } } ``` #### 刪除命令範例 (AWS CLI) 下列範例示範如何使用 命令刪除`delete-command` AWS CLI 命令。根據您的應用程式，*``*將 取代為您要刪除之命令的識別符。 ``` aws iot delete-command --command-id ``` 如果 API 請求成功，則命令會產生狀態碼 202 或 204。您可以使用 `GetCommand` API 來驗證 命令是否不再存在於您的帳戶中。 # 開始和監控命令執行 建立命令後，在目標裝置上啟動執行。裝置會更新結果並將狀態發佈至 MQTT 預留主題。從您的帳戶擷取和監控執行狀態。 使用 AWS IoT 主控台或 啟動和監控命令 AWS CLI。 **Topics** + [啟動命令執行](#iot-remote-command-execution-start) + [更新命令執行的結果](#iot-remote-command-execution-update) + [擷取命令執行](#iot-remote-command-execution-get) + [使用 MQTT 測試用戶端檢視命令更新](#iot-remote-command-execution-update-mqtt) + [在 中列出命令執行 AWS 帳戶](#iot-remote-command-execution-list) + [刪除命令執行](#iot-remote-command-execution-delete) ## 啟動命令執行 **重要** 您全權負責以安全且符合相關法律的方式部署命令。 開始執行之前，請確定： + 您已在具有承載資訊的 AWS IoT 命名空間中建立 命令。開始執行時，裝置會處理承載指示並執行指定的動作。如需建立命令[建立命令資源](iot-remote-command-create-manage.md#iot-remote-command-create)的詳細資訊，請參閱 。 + 您的裝置已訂閱 命令的 MQTT 預留主題。開始執行時，承載資訊會發佈至此預留 MQTT 請求主題： ** 可以是 Things 或 MQTT 用戶端。** 是物件名稱或用戶端 ID。支援的 ** 值：JSON 和 CBOR。如需詳細資訊，請參閱[命令主題](reserved-topics.md#reserved-topics-commands)。 ``` $aws/commands///executions/+/request/ ``` 對於非 JSON/CBOR **，請使用下列命令主題格式： ``` $aws/commands///executions/+/request ``` ### 目標裝置考量事項 指定要接收和執行 命令的目標裝置。將物件名稱用於已註冊的裝置，或將用戶端 ID 用於未註冊的裝置。收到承載後，裝置會執行 命令並執行指定的動作。 #### AWS IoT 物件 目標裝置可以是在 AWS IoT 登錄檔中註冊的物件。物件可簡化裝置搜尋和管理。 從 [Connect 裝置頁面或使用 將裝置](https://console.aws.amazon.com/iot/home#/connect-overview)註冊為實物[https://docs.aws.amazon.com/iot/latest/apireference/API_CreateThing.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateThing.html)。從[物件中樞](https://console.aws.amazon.com/iot/home#/thinghub)或使用 尋找現有的物件[https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeThing.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeThing.html)。如需註冊詳細資訊[，請參閱使用登錄檔管理物件](https://docs.aws.amazon.com/iot/latest/developerguide/thing-registry)。 #### 用戶端 ID 對於未註冊的裝置，請使用用戶端 ID。 用戶端 ID 是您指派給裝置的唯一識別符。在 MQTT 通訊協定中定義，其中包含英數字元、底線或破折號。連線至 的每個裝置 AWS IoT 都需要唯一的用戶端 ID。 **注意** 對於已註冊的物件，用戶端 ID 可以符合物件名稱。 以特定用戶端 ID 為目標時，裝置必須使用 AWS IoT 該用戶端 ID 連線至 ，才能接收承載。 用戶端 ID 是連線至 時使用的 MQTT 用戶端 ID 裝置 AWS IoT Core。 AWS IoT 使用此 ID 來識別裝置和管理連線和訂閱。 ### 命令執行逾時考量 逾時會指定裝置提供執行結果的持續時間 （以秒為單位）。 建立執行後，計時器會啟動。如果裝置離線或無法在逾時內報告結果，則執行會逾時，狀態為 `TIMED_OUT`。 預設：10 秒。上限：12 小時。 #### 逾時值和`TIMED_OUT`執行狀態 雲端和裝置都可以報告逾時。 傳送 命令後，計時器會啟動。如果沒有裝置回應在逾時內到達，則雲端會將執行狀態設定為 ，`TIMED_OUT`原因碼為 `$NO_RESPONSE_FROM_DEVICE`。 發生下列情況時，會發生這種情況： + 裝置在執行期間離線。 + 裝置無法在逾時內完成執行。 + 裝置無法在逾時內報告狀態。 在此執行個體中，當從雲端報告 `TIMED_OUT`的執行狀態時，命令執行是非終端的。您的裝置可以發佈回應，將狀態覆寫為任何終端狀態：`FAILED`、 `SUCCEEDED`或 `REJECTED`。然後，命令執行會變成終端機，且不接受任何進一步的更新。 您的裝置也可以透過報告執行命令時發生逾時，來更新雲端啟動`TIMED_OUT`的狀態。在此情況下，命令執行狀態會保持在 `TIMED_OUT`，但會根據裝置報告的資訊更新`statusReason`物件。命令執行接著會變成終端機，而且不接受進一步的更新。 #### 使用 MQTT 持久性工作階段 您可以設定 MQTT 持久性工作階段，以搭配 AWS IoT Device Management 命令功能使用。此功能在裝置離線且您希望確保裝置在逾時持續時間之前恢復上線時仍能收到命令，並執行指定的指示等情況下特別有用。 MQTT 持續性工作階段到期時間預設為 60 分鐘。如果您的命令執行逾時設定為超過此持續時間的值，執行時間超過 60 分鐘的命令執行可能會被訊息代理程式拒絕並失敗。若要執行持續期間超過 60 分鐘的命令，您可以請求增加持續性工作階段到期時間。 **注意** 為了確保您正確使用 MQTT 持久性工作階段功能，請將 Clean Start 旗標設為零。如需詳細資訊，請參閱 [MQTT 持續性工作階段](https://docs.aws.amazon.com/iot/latest/developerguide/mqtt.html#mqtt-persistent-sessions)。 ### 啟動命令執行 （主控台） 若要從主控台開始執行命令，請前往 AWS IoT 主控台的 [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) 頁面並執行下列步驟。 1. 若要執行您已建立的命令，請選擇**執行命令**。 1. 檢閱您所建立命令的相關資訊，包括 MQTT 預留主題和參數，如適用。 針對動態命令，輸入參數值或保留預設值。對於沒有預設值的參數，您必須提供要作為此執行的一部分傳送的值。 1. 指定要接收和執行 命令的目標裝置。如果裝置已向 註冊，則可以將其指定為 AWS IoT 物件 AWS IoT，如果裝置尚未註冊，則可以使用用戶端 ID。如需詳細資訊，請參閱[目標裝置考量事項](#iot-command-execution-target) 1. （選用） 設定命令的逾時值，決定您希望命令在逾時之前執行的持續時間。如果您的命令需要執行超過 60 分鐘，您可能需要增加 MQTT 持久性工作階段到期時間。如需詳細資訊，請參閱[命令執行逾時考量](#iot-command-execution-timeout)。 1. 選擇**執行命令**。 ### 啟動命令執行 (AWS CLI) 使用 [https://docs.aws.amazon.com/iot/latest/apireference/API_StartCommandExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_StartCommandExecution.html) HTTP 資料平面 API 操作來啟動命令執行。API 請求和回應與命令執行 ID 相關聯。裝置完成執行命令後，可以透過將訊息發佈至命令回應主題，向雲端報告狀態和執行結果。對於自訂回應碼，您擁有的應用程式碼可以處理回應訊息並將結果發佈到其中 AWS IoT。 如果您的裝置已訂閱命令請求主題，`StartCommandExecution`API 會將承載訊息發佈至主題。承載可以使用您選擇的任何格式。如需詳細資訊，請參閱[命令承載](iot-remote-command-create-manage.md#iot-commands-payload)。 ``` $aws/commands///executions/+/request/ ``` 如果承載格式不是 JSON 或 CBOR，則以下顯示命令請求主題的格式。 ``` $aws/commands///executions/+/request ``` #### 範例 IAM 政策 使用此 API 操作之前，請確定您的 IAM 政策授權您在裝置上執行此動作。下列範例顯示 IAM 政策，允許使用者執行 `StartCommandExecution`動作的許可。 在此範例中，取代： + `region` ， AWS 區域例如 `us-east-1`。 + `account-id` 您的 AWS 帳戶 號碼，例如 `123456789012`。 + `command-id` 具有 AWS IoT 命令的唯一識別符，例如 `LockDoor`。如果您想要傳送多個命令，您可以在 IAM 政策中指定這些命令。 + `devices` 使用 `thing`或 ，`client`取決於您的裝置是否已註冊為 AWS IoT 實物，或指定為 MQTT 用戶端。 + `device-id` 您的 AWS IoT `thing-name`或 `client-id`。 ``` { "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 使用者指南*》中的 [的條件金鑰 AWS IoT](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsiot.html#awsiot-policy-keys)。 #### 取得帳戶特定的資料平面端點 執行 API 命令之前，您必須取得端點的帳戶特定端點 URL。如果您使用的是雙堆疊端點 (IPv4 和 IPv6)，請使用 `iot:Data-ATS`。`iot:Jobs` 端點僅適用於 IPv4。例如，如果您執行此命令： ``` aws iot describe-endpoint --endpoint-type iot:Data-ATS ``` 它會傳回帳戶特定的端點 URL，如以下範例回應所示。 ``` { "endpointAddress": "-ats.iot..api.com" } ``` #### 啟動命令執行範例 (AWS CLI) 下列範例顯示如何使用 命令開始執行`start-command-execution` AWS CLI 命令。 在此範例中，取代： + *``* 搭配您要執行之命令的 ARN。您可以從 CLI `create-command` 命令的回應取得此資訊。例如，如果您正在執行變更方向盤模式的命令，請使用 `arn:aws:iot:region:account-id:command/SetComfortSteeringMode`。 + *``* 目標裝置的物件 ARN，可以是您要執行命令的 IoT 物件或 MQTT 用戶端。例如，如果您要執行目標裝置 的 命令`myRegisteredThing`，請使用 `arn:aws:iot:region:account-id:thing/myRegisteredThing`。 + *``* 使用您在 中取得的帳戶特定端點[取得帳戶特定的資料平面端點](#iot-remote-command-execution-start-endpoint)，字首為 `https://`。例如 `https://123456789012abcd.jobs.iot.us-east-1.amazonaws.com`。 + （選用） 您也可以在執行 `StartCommandExecution` API 操作時指定其他參數 `executionTimeoutSeconds`。此選用欄位指定裝置必須完成執行命令的時間，以秒為單位。根據預設，值為 10 秒。當命令執行狀態為 時`CREATED`，計時器會啟動。如果在計時器過期之前未收到命令執行結果，則狀態會自動變更為 `TIMED_OUT`。 + ``` aws iot-jobs-data start-command-execution \ --command-arn \ --target-arn \ --endpoint \ --execution-timeout-seconds 900 ``` + （選用） 對於動態命令，指定要用於替換的參數及其值。您必須為在命令建立時未設定 defaultValue 的參數提供值。如果參數具有 defaultValue，則此處提供的參數值優先。對於設定 valueConditions 的參數，此處提供的參數值必須符合條件。 根據`Light_Power_Status`動態命令範例： + ``` aws iot-jobs-data start-command-execution \ --command-arn arn:aws:iot:us-east-1:123456789012:command/Light_Power_Status \ --target-arn arn:aws:iot:us-east-1:123456789012:thing/exampleThing \ --endpoint \ --execution-timeout-seconds 900 \ --parameters "powerStatus={S=ON}" ``` 執行此命令會傳回命令執行 ID。您可以使用此 ID 來查詢命令執行狀態、詳細資訊和命令執行歷史記錄。 **注意** 如果命令已棄用，則 `StartCommandExecution` API 請求會失敗並出現驗證例外狀況。若要修正此錯誤，請先使用 `UpdateCommand` API 還原命令，然後執行`StartCommandExecution`請求。 ``` { "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542" } ``` ## 更新命令執行的結果 使用 `UpdateCommandExecution` MQTT 資料平面 API 操作來更新命令執行的狀態或結果。 **注意** 使用此 API 之前： 您的裝置必須已建立 MQTT 連線並訂閱命令請求和回應主題。如需詳細資訊，請參閱[高階命令工作流程](iot-remote-command-workflow.md)。 您必須已使用 `StartCommandExecution` API 操作執行此命令。 ### 範例 IAM 政策 使用此 API 操作之前，請確定您的 IAM 政策授權您的裝置執行這些動作。以下顯示範例政策，授權您的裝置執行 動作。如需允許使用者執行 `UpdateCommandExecution` MQTT 動作之許可的其他範例 IAM 政策，請參閱 [連線和發佈政策範例](connect-and-pub.md)。 在此範例中，取代： + `Region` ， AWS 區域例如 `us-east-1`。 + `AccountID` 使用您的 AWS 帳戶 號碼，例如 *`123456789012`*。 + `ThingName` 您以命令執行為目標的 AWS IoT 物件名稱，例如 *`myRegisteredThing`*。 + `commands-request-topic` 和 `commands-response-topic` 以及您 AWS IoT 命令請求和回應主題的名稱。如需詳細資訊，請參閱[高階命令工作流程](iot-remote-command-workflow.md)。 #### MQTT 用戶端 ID 的 IAM 政策範例 下列程式碼顯示使用 MQTT 用戶端 ID 時的範例裝置政策。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iot:Publish", "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response", "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/json" ] }, { "Effect": "Allow", "Action": "iot:Receive", "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/request", "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/accepted", "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/rejected", "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/request/json", "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/accepted/json", "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/rejected/json" ] }, { "Effect": "Allow", "Action": "iot:Subscribe", "Resource": [ "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/request", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/accepted", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/rejected", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/request/json", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/accepted/json", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/rejected/json" ] }, { "Effect": "Allow", "Action": "iot:Connect", "Resource": "arn:aws:iot:us-east-1:123456789012:client/${iot:ClientId}" } ] } ``` #### IoT 物件的 IAM 政策範例 下列程式碼顯示使用 AWS IoT 物件時的範例裝置政策。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iot:Publish", "Resource": "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response" }, { "Effect": "Allow", "Action": "iot:Receive", "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/request", "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/accepted", "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/rejected", "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/request/json", "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/accepted/json", "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/rejected/json" ] }, { "Effect": "Allow", "Action": "iot:Subscribe", "Resource": [ "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/request", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/accepted", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/rejected", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/request/json", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/accepted/json", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/rejected/json" ] }, { "Effect": "Allow", "Action": "iot:Connect", "Resource": "arn:aws:iot:us-east-1:123456789012:client/${iot:ClientId}" } ] } ``` ### 如何使用 `UpdateCommandExecution` API 在請求主題收到命令執行後，裝置會處理命令。然後，它會使用 `UpdateCommandExecution` API 將命令執行的狀態和結果更新為下列回應主題。 ``` $aws/commands///executions//response/ ``` 在此範例中， *``*是目標裝置的唯一識別符，而 *``*是目標裝置上命令執行的識別符。** 可以是 JSON 或 CBOR。 **注意** 如果您尚未向 註冊裝置 AWS IoT，您可以使用用戶端 ID 做為識別符，而不是物件名稱。 ``` $aws/commands/clients//executions//response/ ``` #### 裝置回報執行狀態的更新 您的裝置可以使用 API 向命令執行報告下列任何狀態更新。如需這些狀態的詳細資訊，請參閱 [命令執行狀態](iot-remote-command-concepts.md#iot-command-execution-status)。 + `IN_PROGRESS`：當裝置開始執行命令時，它可以將狀態更新為 `IN_PROGRESS`。 + `SUCCEEDED`：當裝置成功處理命令並完成執行時，裝置可以將訊息發佈至回應主題，做為 `SUCCEEDED`。 + `FAILED`：如果裝置無法執行 命令，它可以將訊息發佈至回應主題，做為 `FAILED`。 + `REJECTED`：如果裝置無法接受 命令，它可以將訊息發佈至回應主題，做為 `REJECTED`。 + `TIMED_OUT`：`TIMED_OUT`由於下列任何原因，命令執行狀態可能會變更為 。 + 未收到命令執行的結果。這可能是因為未在指定的持續時間內完成執行，或裝置無法將狀態資訊發佈至回應主題。 + 裝置報告嘗試執行 命令時發生逾時。 如需 `TIMED_OUT` 狀態的詳細資訊，請參閱 [逾時值和`TIMED_OUT`執行狀態](#iot-command-execution-timeout-status)。 #### 使用 `UpdateCommandExecution` API 時的考量事項 以下是使用 `UpdateCommandExecution` API 時的一些重要考量。 + 您的裝置可以使用選用`statusReason`物件來提供有關執行的其他資訊。如果您的裝置提供此物件，則需要 物件`reasonCode`的欄位，但 `reasonDescription` 欄位是選用的。 + 當您的裝置使用 `statusReason` 物件時， `reasonCode` 必須使用 模式`[A-Z0-9_-]+`，長度不得超過 64 個字元。如果您提供 `reasonDescription`，請確保長度不超過 1，024 個字元。它可以使用任何字元，但控制字元除外，例如換行。 + 您的裝置可以使用選用`result`物件來提供命令執行結果的相關資訊，例如遠端函數呼叫的傳回值。如果您提供 `result`，它必須至少需要一個項目。 + 在 `result` 欄位中，您將項目指定為鍵/值對。對於每個項目，您必須將資料類型資訊指定為字串、布林值或二進位。字串資料類型必須使用金鑰 `s`，布林值資料類型必須使用金鑰 `b`，而二進位資料類型必須使用金鑰 `bin`。請確定這些金鑰為小寫。 + 如果您在執行 `UpdateCommandExecution` API 時發生錯誤，您可以在 Amazon CloudWatch 的`AWSIoTLogsV2`日誌群組中檢視錯誤。如需啟用記錄和檢視日誌的資訊，請參閱 [設定 AWS IoT 記錄](configure-logging.md)。 #### `UpdateCommandExecution` API 範例 以下程式碼顯示您的裝置如何使用 `UpdateCommandExecution` API 報告執行狀態的範例、提供狀態額外資訊`statusReason`的欄位，以及提供執行結果相關資訊的結果欄位，例如在此情況下的汽車電池百分比。 ``` { "status": "IN_PROGRESS", "statusReason": { "reasonCode": "200", "reasonDescription": "Execution_in_progress" }, "result": { "car_battery": { "s": "car battery at 50 percent" } } } ``` ## 擷取命令執行 執行命令後，您可以從 AWS IoT 主控台和使用 擷取命令執行的相關資訊 AWS CLI。您可以取得下列資訊。 **注意** 若要擷取最新的命令執行狀態，您的裝置必須使用 `UpdateCommandExecution` MQTT API 將狀態資訊發佈至回應主題，如下所述。在裝置發佈至此主題之前，`GetCommandExecution`API 會將狀態報告為 `CREATED`或 `TIMED_OUT`。 您建立的每個命令執行作業都會有： + **執行 ID**，這是命令執行作業的唯一識別碼。 + 命令執行的**狀態**。當您在目標裝置上執行命令時，命令執行作業會進入 `CREATED` 狀態。然後作業會轉換成其他命令執行狀態，如下所述。 + 命令執行**的結果**。 + 唯一的**命令 ID** 和已建立執行作業的目標裝置。 + **開始日期**，顯示命令執行作業建立的時間。 ### 擷取命令執行 （主控台） 您可以使用下列其中一種方法，從主控台擷取命令執行。 + **從命令中樞頁面** 前往 AWS IoT 主控台的 [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) 頁面，並執行這些步驟。 1. 選擇您在目標裝置上建立執行的命令。 1. 在命令詳細資訊頁面的**命令歷史記錄**索引標籤中，您會看到您建立的執行。選擇您要擷取資訊的執行。 1. 如果您的裝置使用 `UpdateCommandExecution` API 提供結果資訊，您可以在此頁面**的結果**索引標籤中找到此資訊。 + **從物件中樞頁面** 如果您在執行 命令時選擇 AWS IoT 物件做為目標裝置，您可以從物件中樞頁面檢視執行詳細資訊。 1. 前往 AWS IoT 主控台中的[物件中樞](https://console.aws.amazon.com/iot/home#/thinghub)頁面，然後選擇您為其建立命令執行的物件。 1. 在物件詳細資訊頁面的**命令歷史記錄**中，您會看到您建立的執行。選擇您要擷取資訊的執行。 1. 如果您的裝置使用 `UpdateCommandExecution` API 提供結果資訊，您可以在此頁面**的結果**索引標籤中找到此資訊。 ### 擷取命令執行 (CLI) 使用[https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommandExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommandExecution.html) AWS IoT Core 控制平面 HTTP API 操作來擷取命令執行的相關資訊。您必須已使用 `StartCommandExecution` API 操作執行此命令。 #### 範例 IAM 政策 使用此 API 操作之前，請確定您的 IAM 政策授權您在裝置上執行此動作。下列範例顯示 IAM 政策，允許使用者執行 `GetCommandExecution`動作的許可。 在此範例中，取代： + `region` ， AWS 區域例如 `us-east-1`。 + `account-id` 您的 AWS 帳戶 號碼，例如 `123456789012`。 + `command-id` 您的唯一 AWS IoT 命令識別符，例如 `LockDoor`。 + `devices` 使用 `thing`或 ，`client`取決於您的裝置是否已註冊為 AWS IoT 實物，或指定為 MQTT 用戶端。 + `device-id` 您的 AWS IoT `thing-name`或 `client-id`。 ``` { "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` AWS CLI 命令的相關資訊。下列範例顯示如何擷取已執行之命令的相關資訊，以關閉方向盤模式。 在此範例中，取代： + *``* 具有您要擷取資訊的命令執行識別符。 + *``* 您以執行為目標之裝置的 Amazon Resource Number (ARN)。您可以從 CLI `start-command-execution` 命令的回應取得此資訊。 + 或者，如果您的裝置使用 `UpdateCommandExection` API 提供執行結果，您可以指定是否使用 `GetCommandExecution` API 在 `GetCommandExecution` API 回應中包含命令執行結果。 ``` aws iot get-command-execution --execution-id \ --target-arn \ --include-result ``` 執行此命令會產生回應，其中包含命令執行的 ARN、執行狀態，以及開始執行的時間，以及完成時間的相關資訊。它也提供 `statusReason` 物件，其中包含 狀態的其他資訊。如需不同狀態和狀態原因的詳細資訊，請參閱 [命令執行狀態](iot-remote-command-concepts.md#iot-command-execution-status)。 下列程式碼顯示來自 API 請求的範例回應。 **注意** 執行回應中的 `completedAt` 欄位對應至裝置向雲端回報終端機狀態的時間。在`TIMED_OUT`狀態的情況下，只有在裝置報告逾時時，才會設定此欄位。狀態由雲端設定`TIMED_OUT`時，`TIMED_OUT`狀態不會更新。如需逾時行為的詳細資訊，請參閱 [命令執行逾時考量](#iot-command-execution-timeout)。 ``` { "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" } ``` ## 使用 MQTT 測試用戶端檢視命令更新 使用命令功能時，您可以使用 MQTT 測試用戶端透過 MQTT 檢視訊息交換。在您的裝置與 建立 MQTT 連線後 AWS IoT，您可以建立命令、指定承載，然後在裝置上執行它。當您執行 命令時，如果您的裝置訂閱命令的 MQTT 預留請求主題，它會看到發佈至此主題的承載訊息。 然後，裝置會收到承載指示，並在 AWS IoT 裝置上執行指定的操作。然後，它會使用 `UpdateCommandExecution` API 將命令執行結果和狀態資訊發佈至 command. AWS IoT Device Management listens 的 MQTT 預留回應主題，以更新回應主題並儲存更新的資訊，並將日誌發佈至 AWS CloudTrail 和 Amazon CloudWatch。然後，您可以從主控台或使用 `GetCommandExecution` API 擷取最新的命令執行資訊。 下列步驟說明如何使用 MQTT 測試用戶端來觀察訊息。 1. 在 AWS IoT 主控台中開啟 [MQTT 測試用戶端](https://console.aws.amazon.com/iot/home#/test)。 1. 在**訂閱**索引標籤上，輸入下列主題，然後選擇**訂閱**，其中 ** 是您已註冊之裝置的物件名稱 AWS IoT。 **注意** 您可以從 AWS IoT 主控台的物件[中樞](https://console.aws.amazon.com/iot/home#/thinghub)頁面找到裝置的物件名稱。如果您尚未將裝置註冊為物件，您可以在 AWS IoT 從 [Connect 裝置頁面連線至 時註冊裝置](https://console.aws.amazon.com/iot/home#/connect-overview)。 ``` $aws/commands/things//executions/+/request ``` 1. （選用） 在**訂閱**索引標籤上，您也可以輸入下列主題，然後選擇**訂閱**。 ``` $aws/commands/things/+/executions/+/response/accepted/json $aws/commands/things/+/executions/+/response/rejected/json ``` 1. 當您啟動命令執行時，將使用裝置已訂閱的請求主題 ，將訊息承載傳送至裝置`$aws/commands/things//executions/+/request`。在 MQTT 測試用戶端中，您應該會看到命令承載，其中包含裝置處理命令的指示。 1. 裝置開始執行命令後，可以發佈狀態更新至下列命令的 MQTT 預留回應主題。 ``` $aws/commands///executions//response/json ``` 例如，請考慮您執行的命令，以開啟汽車的 AC，將溫度降至所需的值。下列 JSON 顯示 車輛發佈至回應主題的範例訊息，顯示無法執行 命令。 ``` { "deviceId": "My_Car", "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542", "status": "FAILED", "statusReason": { "reasonCode": "CAR_LOW_ON_BATTERY", "reasonDescription": "Car battery is lower than 5 percent" } } ``` 在這種情況下，您可以為汽車的電池充電，然後再次執行 命令。 ## 在 中列出命令執行 AWS 帳戶 執行命令之後，您可以從 AWS IoT 主控台和使用 擷取命令執行的相關資訊 AWS CLI。您可以取得下列資訊。 + **執行 ID**，這是命令執行作業的唯一識別碼。 + 命令執行的**狀態**。當您在目標裝置上執行命令時，命令執行作業會進入 `CREATED` 狀態。然後作業會轉換成其他命令執行狀態，如下所述。 + 唯一的**命令 ID** 和已建立執行作業的目標裝置。 + **開始日期**，顯示命令執行作業建立的時間。 ### 列出您帳戶中的命令執行 （主控台） 您可以使用下列其中一種方法，從主控台查看所有命令執行。 + **從命令中樞頁面** 前往 AWS IoT 主控台的 [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) 頁面，並執行這些步驟。 1. 選擇您在目標裝置上建立執行的命令。 1. 在命令詳細資訊頁面中，前往**命令歷史記錄**索引標籤，您會看到您建立的執行清單。 + **從物件中樞頁面** 如果您在執行 命令時選擇 AWS IoT 物件做為目標裝置，並為單一裝置建立多個命令執行，您可以從物件中樞頁面檢視裝置的執行。 1. 前往 AWS IoT 主控台中的[物件中樞](https://console.aws.amazon.com/iot/home#/thinghub)頁面，然後選擇您為其建立執行的物件。 1. 在物件詳細資訊頁面的**命令歷史記錄**中，您會看到為裝置建立的執行清單。 ### 列出您帳戶中的命令執行 (CLI) 使用[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 操作列出您帳戶中的所有命令執行。 #### 範例 IAM 政策 使用此 API 操作之前，請確定您的 IAM 政策授權您在裝置上執行此動作。下列範例顯示 IAM 政策，允許使用者執行 `ListCommandExecutions`動作的許可。 在此範例中，取代： + `region` ， AWS 區域例如 `us-east-1`。 + `account-id` 使用您的 AWS 帳戶 號碼，例如 `123456789012`。 + `command-id` 您的唯一 AWS IoT 命令識別符，例如 `LockDoor`。 ``` { "Effect": "Allow", "Action": "iot:ListCommandExecutions", "Resource": * } ``` #### 列出命令執行範例 下列範例示範如何在 中列出命令執行 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" } ] } ``` 如需不同狀態和狀態原因的詳細資訊，請參閱 [命令執行狀態](iot-remote-command-concepts.md#iot-command-execution-status)。 ## 刪除命令執行 如果您不想再使用命令執行，可以從您的帳戶永久移除它。 **注意** 命令執行只有在進入終端狀態時才能刪除，例如 `SUCCEEDED`、 `FAILED`或 `REJECTED`。 此操作只能使用 AWS IoT Core API 或 執行 AWS CLI。它無法從 主控台使用。 ### 範例 IAM 政策 使用此 API 操作之前，請確定您的 IAM 政策授權您的裝置執行這些動作。以下顯示範例政策，授權您的裝置執行 動作。 在此範例中，取代： + `Region` 您的 AWS 區域，例如 `us-east-1`。 + `AccountID` 使用您的 AWS 帳戶 號碼，例如 *`123456789012`*。 + `CommandID` 具有您要刪除執行之命令的識別符。 + `devices` 使用 `thing`或 ，`client`取決於您的裝置是否已註冊為 AWS IoT 實物，或指定為 MQTT 用戶端。 + `device-id` 您的 AWS IoT `thing-name`或 `client-id`。 ``` { "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` AWS CLI 命令。根據您的應用程式，將 *``*取代為您要刪除之命令執行的識別符，並將 *``*取代為您目標裝置的 ARN。 ``` aws iot delete-command-execution \ --execution-id \ --target-arn ``` 如果 API 請求成功，則命令執行會產生 200 狀態碼。您可以使用 `GetCommandExecution` API 來驗證 帳戶中不再存在命令執行。 # 取代指令資源 棄用命令以指出它們已過時且不應使用。例如，棄用不再主動維護的命令，或在建立具有相同 ID 但不同承載的較新命令時。 ## 關鍵考量 取代命令時的重要考量： + 棄用命令並不會將其刪除。您可以使用命令的 ID 擷取命令，並將其還原以供重複使用。 + 嘗試在已棄用命令上啟動新執行會產生錯誤，防止使用過時的命令。 + 若要執行已棄用命令，請先將其還原。還原之後，命令即可在目標裝置上定期使用和執行。 + 如果您在執行進行時棄用命令，它們會繼續執行，直到完成為止。您仍然可以擷取執行狀態。 ## 棄用命令資源 （主控台） 若要從主控台棄用命令，請前往 AWS IoT 主控台的 [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) 並執行下列步驟。 1. 選擇您要棄用的命令，然後在**動作**下選擇**棄用**。 1. 確認您要棄用命令，然後選擇**棄用**。 ## 棄用命令資源 (CLI) 使用 CLI `update-command` 將命令標記為已棄用。您必須先棄用命令，才能刪除。若要使用已棄用的命令，請先將其還原。 ``` aws iot update-command \ --command-id \ --deprecated ``` 例如，如果您已棄用在上述範例中更新的`ACSwitch`命令，下列程式碼會顯示執行命令的範例輸出。 ``` { "commandId": "turnOffAc", "deprecated": true, "lastUpdatedAt": "2024-05-09T23:16:51.370000-07:00" } ``` ## 檢查棄用時間和狀態 使用 `GetCommand` API 來判斷命令是否已棄用，以及上次棄用的時間。 ``` aws iot get-command --command-id ``` 此命令會產生包含命令資訊的回應，包括上次更新欄位的建立和取代時間戳記。這有助於判斷命令生命週期，以及是否要刪除或重複使用。以下顯示 `turnOffAc`命令的範例回應： ``` { "commandId": "turnOffAC", "commandArn": "arn:aws:iot:us-east-1:123456789012:command/turnOffAC", "namespace": "AWS-IoT", "payload": { "content": "testPayload.json", "contentType": "application/json" }, "createdAt": "2024-03-23T00:50:10.095000-07:00", "lastUpdatedAt": "2024-05-09T23:16:51.370000-07:00", "deprecated": false } ``` ## 還原命令資源 若要使用或傳送`ACSwitch`命令至您的裝置，請先將其還原。 若要從主控台還原命令，請前往 AWS IoT 主控台的 [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub)，選擇您要還原的命令，然後在**動作**下選擇**還原**。 若要使用 AWS IoT Core API 或 還原命令 AWS CLI，請使用 `UpdateCommand` API 操作或 `update-command` CLI。下列程式碼顯示範例請求和回應。 ``` aws iot update-command \ --command-id --no-deprecated ``` 下列程式碼顯示範例輸出。 ``` { "commandId": "ACSwitch", "deprecated": false, "lastUpdatedAt": "2024-05-09T23:17:21.954000-07:00" } ```