本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 建立和管理命令 使用 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 來驗證 命令是否不再存在於您的帳戶中。