建立和管理命令

您可以使用 AWS IoT Device Management 命令功能來設定可重複使用的遠端動作，或傳送一次性的立即指示至您的裝置。下列各節說明如何從 AWS IoT 主控台和使用建立和管理命令 AWS CLI。

建立和管理命令操作

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

建立命令資源

建立命令時，您必須提供下列資訊。

一般資訊

建立命令時，您必須提供命令 ID，這是唯一的識別符，協助您在目標裝置上執行命令時識別命令。您也可以選擇性地指定顯示名稱、描述和標籤，以進一步協助您管理命令。
承載

您也必須提供承載，以定義裝置必須執行的動作。選用時，建議您指定承載格式類型，讓裝置正確解譯承載。

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

如果您指定 application/json或的承載內容類型application/cbor，則請求主題將如下。
```
$aws/commands/<devices>/<DeviceID>/executions/+/request/<PayloadFormat>
```
如果您指定 application/json或以外的承載內容類型application/cbor，或如果您未指定承載格式類型，則請求主題將如下。在此情況下，承載格式會包含在 MQTT 訊息標頭中。
```
$aws/commands/<devices>/<DeviceID>/executions/+/request
```

命令回應主題會傳回使用 json或cbor獨立於承載格式類型的格式。回應主題將使用下列格式，其中 <PayloadFormat> 必須是 json或 cbor。


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

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

命令承載格式

承載可以使用您選擇的任何格式。承載的大小上限不得超過 32 KB。為了確保裝置可以安全且正確地解譯承載，我們建議您指定承載格式類型。

您可以使用格式指定承載type/subtype格式類型，例如 application/json或 application/cbor。根據預設，它會設定為 application/octet-stream。如需有關您可以指定的承載格式的資訊，請參閱常見 MIME 類型。

如何建立命令（主控台）

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

若要建立新的命令資源，請選擇建立命令。
指定唯一的命令 ID，協助您識別要在目標裝置上執行的命令。
（選用）將選用的顯示名稱、描述和任何名稱/值對指定為命令的標籤。
從本機儲存上傳承載檔案，其中包含裝置需要執行的動作。選用時，建議您指定承載格式類型，讓裝置正確解譯檔案並處理指示。
選擇建立命令。

本節說明 HTTP 控制平面 API 操作、 CreateCommand和對應的 AWS CLI 命令，您可以執行create-command這些操作來建立命令資源。

主題

命令承載
範例 IAM 政策
建立命令範例

命令承載

建立命令時，您必須提供承載。您提供的承載是 base64 編碼。當您的裝置收到命令時，裝置端邏輯可以處理承載並執行指定的動作。為了確保您的裝置正確接收命令和承載，我們建議您指定承載內容類型。

注意

建立命令之後，您就無法修改承載。若要修改承載，您必須建立新的命令。

範例 IAM 政策

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

在此範例中，取代：

region 搭配您的 AWS 區域，例如 ap-south-1。
account-id 使用您的 AWS 帳戶號碼，例如 123456789012。
command-id 具有 AWS IoT 命令 ID 的唯一識別符，例如 LockDoor。如果您想要傳送多個命令，您可以在 IAM 政策的資源區段下指定這些命令。

建立命令範例

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

<command-id> 具有命令的唯一識別符。例如，若要鎖定您房屋的 doc-history，您可以指定 LockDoor。我們建議您使用 UUID。您也可以使用英數字元、"-" 和 "_"。
（選用） <description> <display-name>和，這是選用欄位，您可以用來為命令提供易記的名稱和有意義的描述，例如 Lock the doors of my home。
namespace，您可以使用它來指定命令的命名空間。它必須是 AWS-IoT。
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:ap-south-1:123456789012:command/LockDoor"
}

擷取命令的相關資訊

建立命令之後，您可以從主控台並使用擷取其 AWS IoT 相關資訊 AWS CLI。您可以取得下列資訊。

命令 ID、Amazon 資源名稱 (ARN)、您為命令指定的任何顯示名稱和描述。
命令狀態，指出命令是否可在目標裝置上執行，或是否已被取代或刪除。
您提供的承載及其格式類型。
命令建立和上次更新的時間。

若要從主控台擷取命令，請前往 AWS IoT 主控台的 Command Hub，然後選擇您建立的命令以檢視其詳細資訊。

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

使用 GetCommand HTTP 控制平面 API 操作或 get-command AWS CLI 命令來擷取命令資源的相關資訊。您必須已經使用 CreateCommand API 請求或 CLI create-command 建立命令。

範例 IAM 政策

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

在此範例中，取代：

region 搭配您的 AWS 區域，例如 ap-south-1。
account-id 使用您的 AWS 帳戶號碼，例如 123456789023。
command-id 您的 AWS IoT 唯一命令識別符，例如 LockDoor。如果您想要擷取多個命令，您可以在 IAM 政策的資源區段下指定這些命令。

擷取命令範例 (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 區域，例如 ap-south-1。
account-id 使用您的 AWS 帳戶號碼，例如 123456789012。

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

下列命令說明如何列出您帳戶中的命令。


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 區域，例如 ap-south-1。
account-id 使用您的 AWS 帳戶號碼，例如 123456789012。
command-id 您的 AWS IoT 唯一命令識別符，例如 LockDoor。如果您想要擷取多個命令，您可以在 IAM 政策的資源區段下指定這些命令。

更新命令範例的相關資訊 (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:ap-south-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 政策授權您在裝置上執行此動作。下列範例顯示 IAM 政策，允許使用者執行 DeleteCommand動作的許可。

在此範例中，取代：

region 搭配您的 AWS 區域，例如 ap-south-1。
account-id 使用您的 AWS 帳戶號碼，例如 123456789012。
command-id 您的 AWS IoT 唯一命令識別符，例如 LockDoor。如果您想要擷取多個命令，您可以在 IAM 政策的資源區段下指定這些命令。

刪除命令範例 (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 帳戶