建立和管理命令

使用 AWS IoT Device Management 命令來設定可重複使用的遠端動作，或傳送立即指示至裝置。從 AWS IoT 主控台或使用建立和管理命令 AWS CLI。

建立和管理命令操作

建立命令資源
擷取命令的相關資訊
在中列出命令 AWS 帳戶
更新命令資源
棄用或還原命令資源
刪除命令資源

建立命令資源

在建立命令時提供下列資訊：

一般資訊

提供唯一的命令 ID，以在目標裝置上執行命令時識別命令。選擇性地指定要管理的顯示名稱、描述和標籤。
承載

對於靜態命令，請提供承載定義裝置動作。指定用於正確裝置解譯的承載格式類型。

如需動態命令，請參閱承載範本屬性。
承載範本

對於動態命令，請提供具有預留位置和參數的 payloadTemplate。選擇性地提供 defaultValue和條件。 AWS IoT Device Management 命令會在執行時間取代預留位置。缺少參數會使用其 defaultValue。所有值都必須滿足定義的條件。

支援以下區分大小寫的預留位置類型：
- ${aws:iot:commandexecution::parameter:parameter1} – 名稱為之參數值的預留位置parameter1。
- ${aws:iot:commandexecution::executionTimeoutSec} – 執行時間提供的命令執行逾時參數的預留位置。

命令預留主題使用基於承載格式類型的格式。

對於 application/json或 application/cbor內容類型，請使用此請求主題：
```
$aws/commands/<devices>/<DeviceID>/executions/+/request/<PayloadFormat>
```
對於其他內容類型或未指定的格式，請使用此請求主題。承載格式會出現在 MQTT 訊息標頭中。
```
$aws/commands/<devices>/<DeviceID>/executions/+/request
```

命令回應主題使用 json或 cbor 格式，無論承載類型為何。<PayloadFormat> 必須是 json或 cbor：


$aws/commands/<devices>/<DeviceID>/executions/<ExecutionId>/response/<PayloadFormat>

下列各節說明承載格式考量事項，以及從主控台建立命令。

靜態命令承載格式

承載支援任何最高 32 KB 的格式。指定承載格式類型，以進行安全且正確的裝置解譯。

使用格式（例如 application/json或 application/cbor) 指定承載type/subtype格式類型。預設：application/octet-stream。如需支援的格式，請參閱常見 MIME 類型。

動態命令承載格式

payloadTemplate 必須是具有至少一個預留位置的有效 JSON，最多 32 KB。

對於AwsJsonSubstitution預處理器， AWS IoT Device Management Commands 會根據預處理器組態，以 JSON 或 CBOR 格式傳送通知。

如何建立命令（主控台）

若要從主控台建立命令，請前往 Command Hub 並遵循下列步驟：

選擇建立命令。
指定唯一的命令 ID。
（選用）指定顯示名稱、描述和標籤。
上傳包含裝置動作的承載檔案。指定用於正確裝置解譯的承載格式類型。
（選用）對於具有預留位置的 JSON 承載範本，參數會預先填入內嵌資料表中以供編輯。
（選用）設定參數值類型（必要）、預設值和條件。
選擇建立命令。

使用 CreateCommand API 或 create-command CLI 命令來建立命令。

主題

命令承載
範例 IAM 政策
靜態命令建立範例
動態命令建立範例

命令承載

提供靜態承載或承載範本。靜態承載是 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"
    }
}

靜態命令建立範例

下列範例示範如何建立靜態命令。根據您的應用程式，取代：

<command-id> 具有命令的唯一識別符。例如，若要鎖定房屋的門，您可以指定 LockDoor。我們建議您使用 UUID。您也可以使用英數字元、"-" 和 "_"。
（選用） <description> <display-name>和，這是選用欄位，您可以用來為命令提供易記的名稱和有意義的描述，例如 Lock the doors of my home。
namespace，您可以使用它來指定命令的命名空間。它必須是 AWS-IoT。如需針對使用此功能的詳細資訊 AWS IoT FleetWise，請參閱遠端命令
payload 包含您在執行命令時要使用之承載及其內容類型的相關資訊。


aws iot create-command \ 
    --command-id <command-id> \
    --display-name <display-name> \
    --description <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"
}

動態命令建立範例

下列範例示範如何建立動態命令。根據您的應用程式，取代：

<command-id> 具有命令的唯一識別符。例如，若要設定光源狀態，您可以指定 Light_Power_Status。我們建議您使用 UUID。您也可以使用英數字元、"-" 和 "_"。
（選用） <description> <display-name>和，這些是選用欄位，可用來為命令提供易記的名稱和有意義的描述，例如 Turn a light ON or OFF。
namespace，您可以使用它來指定命令的命名空間。它必須是 AWS-IoT。如需針對使用此功能的詳細資訊 AWS IoT FleetWise，請參閱遠端命令
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，然後選擇您建立的命令以檢視其詳細資訊。

除了命令詳細資訊之外，您還可以查看命令歷史記錄，該歷史記錄提供有關在目標裝置上執行命令的資訊。在裝置上執行此命令後，您可以在此索引標籤上找到執行的相關資訊。

使用 GetCommand HTTP 控制平面 API 操作或 get-command 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。根據您的應用程式，將 <command-id>取代為您要擷取資訊的命令的識別符。您可以從 CLI create-command 的回應取得此資訊。


aws iot get-command --command-id <command-id>

執行此命令會產生回應，其中包含命令、承載以及建立和上次更新的時間的相關資訊。它也提供指出命令是否已棄用或正在刪除的資訊。

例如，下列程式碼顯示範例回應。


{
    "commandId": "LockDoor",
    "commandArn": "arn:aws:iot:<region>:<account>: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，找到您建立的命令清單及其詳細資訊。

若要列出您建立的命令，請使用 ListCommands API 操作或 list-commands 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"

執行此命令會產生回應，其中包含您建立的命令清單、命令建立時間和上次更新的時間。它也提供命令狀態資訊，指出命令是否已棄用或可在目標裝置上執行。如需不同狀態和狀態原因的詳細資訊，請參閱命令執行狀態。

更新命令資源

建立命令之後，您可以更新命令的顯示名稱和描述。

注意

無法更新命令的承載。若要更新此資訊或使用修改後的承載，您需要建立新的命令。

若要從主控台更新命令，請前往 AWS IoT 主控台的 Command Hub，然後執行下列步驟。

若要更新現有的命令資源，請選擇您要更新的命令，然後在動作下選擇編輯。
指定您要使用的顯示名稱和描述，以及任何名稱/值對做為命令的標籤。
選擇編輯以使用新設定儲存命令。

使用UpdateCommand控制平面 API 操作或 update-command 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)。

此範例顯示如何更新命令的顯示名稱和描述。根據您的應用程式，將 <command-id>取代為您要擷取資訊的命令的識別符。


aws iot update-command \ 
    --command-id <command-id>    
    --displayname <display-name> \
    --description <description>

執行此命令會產生回應，其中包含有關命令和上次更新時間的更新資訊。下列程式碼顯示更新關閉 AC 之命令的顯示名稱和描述的範例請求和回應。


aws iot update-command \ 
    --command-id <LockDoor> \ 
    --displayname <Secondary lock door> \
    --description <Locks doors to my home>

執行此命令會產生下列回應。


{
    "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"
}

棄用或還原命令資源

建立命令之後，如果不想再繼續使用命令，您可以將其標記為已棄用。當您棄用命令時，所有待定命令執行都會繼續在目標裝置上執行，直到達到終端機狀態為止。一旦命令已棄用，如果您想要使用等命令，將新的命令執行傳送至目標裝置，則必須將其還原。

注意

您無法編輯已棄用的命令，或對其執行任何新的執行。若要在裝置上執行新的命令，您必須將其還原，命令狀態才會變更為可用。

如需有關棄用和還原命令以及其考量事項的其他資訊，請參閱取代指令資源。

刪除命令資源

如果您不想再使用命令，可以從您的帳戶永久移除它。如果刪除動作成功：

如果命令已棄用超過最大逾時 12 小時的持續時間，則會立即刪除命令。
如果命令未棄用，或已棄用超過最大逾時的持續時間，則命令將處於 pending deletion 狀態。最長逾時 12 小時後，系統會自動將其從您的帳戶中移除。

注意

即使有任何待定的命令執行，也可能會刪除命令。命令將處於待定刪除狀態，並會自動從您的帳戶中移除。

若要從主控台刪除命令，請前往 AWS IoT 主控台的 Command Hub，然後執行下列步驟。

選擇您要刪除的命令，然後在動作下，選擇刪除。
確認您想要刪除命令，然後選擇刪除。

命令將標記為刪除，並在 12 小時後從您的帳戶中永久移除。

使用 DeleteCommand HTTP 控制平面 API 操作或 delete-command AWS CLI 命令來刪除命令資源。如果刪除動作成功，您會看到 HTTP statusCode為 204 或 202，且命令會在逾時持續時間上限為 12 小時後自動從您的帳戶刪除。在 204 狀態的情況下，表示命令已刪除。

範例 IAM 政策

使用此 API 操作之前，請確定您的 IAM 政策授權您在裝置上執行此動作。下列範例顯示允許使用者執行 DeleteCommand動作的 IAM 政策。

在此範例中，取代：

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 命令。根據您的應用程式，將 <command-id>取代為您要刪除之命令的識別符。


aws iot delete-command --command-id <command-id>

如果 API 請求成功，則命令會產生狀態碼 202 或 204。您可以使用 GetCommand API 來驗證命令是否不再存在於您的帳戶中。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

命令工作流程

開始和監控命令執行

建立和管理命令

建立和管理命令操作

建立命令資源

一般資訊

主題

靜態命令承載格式

動態命令承載格式

如何建立命令 （主控台）

主題

命令承載

注意

範例 IAM 政策

靜態命令建立範例

動態命令建立範例

擷取命令的相關資訊

範例 IAM 政策

擷取命令範例 (AWS CLI)

在 中列出命令 AWS 帳戶

注意

範例 IAM 政策

在您的帳戶範例中列出命令

更新命令資源

注意

範例 IAM 政策

更新命令範例的相關資訊 (AWS CLI)

棄用或還原命令資源

注意

刪除命令資源

注意

範例 IAM 政策

刪除命令範例 (AWS CLI)

如何建立命令（主控台）

在中列出命令 AWS 帳戶