本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
您可以使用 AWS IoT Device Management 命令功能來設定可重複使用的遠端動作，或傳送一次性的立即指示至您的裝置。下列各節說明如何從 AWS IoT 主控台和使用 建立和管理命令 AWS CLI。
建立命令資源
建立命令時，您必須提供下列資訊。
-
一般資訊
建立命令時，您必須提供命令 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這些操作來建立命令資源。
命令承載
建立 命令時，您必須提供承載。您提供的承載是 base64 編碼。當您的裝置收到 命令時，裝置端邏輯可以處理承載並執行指定的動作。為了確保您的裝置正確接收 命令和承載，我們建議您指定承載內容類型。
注意
建立 命令之後，您無法修改承載。若要修改承載，您必須建立新的命令。
範例IAM政策
使用API此操作之前，請確定您的IAM政策授權您在裝置上執行此動作。下列範例顯示允許使用者執行 CreateCommand動作的 IAM政策。
在此範例中，取代：
-
regionap-south-1 -
account-id123456789012 -
command-idLockDoor
{
"Version": "2012-10-17",
"Statement":
{
"Action": "iot:CreateCommand",
"Effect": "Allow",
"Resource": "arn:aws:iot:<region>:<account_id>:command/command-id"
}
}建立命令範例
下列範例示範如何建立 命令。根據您的應用程式，取代：
-
<command-id>LockDoor -
（選用）
<description><display-name>Lock the doors of my home -
namespace，您可以使用它來指定命令的命名空間。它必須是AWS-IoT。 -
payload包含您在執行 命令時要使用的承載及其內容類型的相關資訊。
aws iot create-command \ --command-id<command-id>\ --display-name\ --description<display-name><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
除了命令詳細資訊之外，您還可以查看命令歷史記錄，該歷史記錄提供有關在目標裝置上執行命令的資訊。在裝置上執行此命令後，您可以在此索引標籤上找到執行的相關資訊。
使用GetCommandHTTP控制平面API操作或 get-command AWS CLI 命令來擷取命令資源的相關資訊。您必須已使用 CreateCommandAPI請求或 create-command 建立 命令CLI。
範例IAM政策
使用API此操作之前，請確定您的IAM政策授權您在裝置上執行此動作。下列範例顯示允許使用者執行 GetCommand動作的 IAM政策。
在此範例中，取代：
-
regionap-south-1。 -
account-id123456789023 -
command-idLockDoor
{
"Version": "2012-10-17",
"Statement":
{
"Action": "iot:GetCommand",
"Effect": "Allow",
"Resource": "arn:aws:iot:<region>:<account_id>:command/command-id"
}
}擷取命令範例 (AWS CLI)
下列範例說明如何使用 擷取命令的相關資訊get-command AWS CLI。根據您的應用程式，將 <command-id>create-command 的回應取得此資訊CLI。
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
若要列出您建立的命令，請使用 ListCommandsAPI操作或 list-commands CLI。
範例IAM政策
使用API此操作之前，請確定您的IAM政策授權您在裝置上執行此動作。下列範例顯示允許使用者執行ListCommands動作的 IAM政策。
在此範例中，取代：
-
regionap-south-1。 -
account-id123456789012
{
"Version": "2012-10-17",
"Statement":
{
"Action": "iot:ListCommands",
"Effect": "Allow",
"Resource": "arn:aws:iot:<region>:<account_id>:command/*"
}
}在您的帳戶範例中列出命令
下列命令說明如何列出您帳戶中的命令。
aws iot list-commands --namespace "AWS-IoT"
執行此命令會產生回應，其中包含您建立的命令清單、建立命令的時間，以及上次更新的時間。它也提供命令狀態資訊，指出命令是否已棄用或可在目標裝置上執行。如需不同狀態和狀態原因的詳細資訊，請參閱 命令執行狀態。
更新命令資源
建立命令之後，您可以更新命令的顯示名稱和描述。
注意
無法更新 命令的承載。若要更新此資訊或使用修改後的承載，您需要建立新的命令。
若要從主控台更新命令，請前往 AWS IoT 主控台的 Command Hub
-
若要更新現有的命令資源，請選擇您要更新的命令，然後在動作下選擇編輯。
-
指定您要使用的顯示名稱和描述，以及任何名稱值對做為命令的標籤。
-
選擇編輯以使用新設定儲存命令。
使用UpdateCommand控制平面API操作或 update-command AWS CLI 來更新命令資源。使用此 API，您可以：
-
編輯您建立之命令的顯示名稱和描述。
-
棄用命令資源，或還原已棄用的命令。
範例IAM政策
使用API此操作之前，請確定您的IAM政策授權您在裝置上執行此動作。下列範例顯示允許使用者執行 UpdateCommand動作的 IAM政策。
在此範例中，取代：
-
regionap-south-1。 -
account-id123456789012 -
command-idLockDoor
{
"Version": "2012-10-17",
"Statement":
{
"Action": "iot:UpdateCommand",
"Effect": "Allow",
"Resource": "arn:aws:iot:<region>:<account_id>: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: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 小時後從您的帳戶永久移除。
使用DeleteCommandHTTP控制平面API操作或 delete-command AWS CLI 命令來刪除命令資源。如果刪除動作成功，您會看到 204 或 202 HTTPstatusCode的 ，且命令會在最長逾時持續時間為 12 小時後自動從您的帳戶刪除。在 204 狀態的情況下，表示命令已刪除。
範例IAM政策
使用API此操作之前，請確定您的IAM政策授權您在裝置上執行此動作。下列範例顯示允許使用者執行 DeleteCommand動作的 IAM政策。
在此範例中，取代：
-
regionap-south-1。 -
account-id123456789012 -
command-idLockDoor
{
"Version": "2012-10-17",
"Statement":
{
"Action": "iot:DeleteCommand",
"Effect": "Allow",
"Resource": "arn:aws:iot:<region>:<account_id>:command/command-id"
}
}刪除命令範例 (AWS CLI)
下列範例示範如何使用 命令刪除delete-command AWS CLI 命令。根據您的應用程式，<command-id>
aws iot delete-command --command-id<command-id>
如果API請求成功，則命令會產生 202 或 204 的狀態碼。您可以使用 GetCommandAPI來驗證 命令是否不再存在於您的帳戶中。
