啟動命令執行更新命令執行的結果擷取命令執行使用MQTT測試用戶端檢視命令更新在中列出命令執行 AWS 帳戶刪除命令執行

啟動和監控命令執行

建立命令資源後，您可以在目標裝置上啟動命令執行。一旦裝置開始執行命令，即可開始更新命令執行的結果，並將狀態更新和結果資訊發佈至MQTT預留主題。然後，您可以擷取命令執行的狀態，並監控您帳戶中的執行狀態。

本節說明如何使用 AWS IoT 主控台和啟動和監控命令 AWS CLI。

啟動和監控命令操作

啟動命令執行
更新命令執行的結果
擷取命令執行
使用MQTT測試用戶端檢視命令更新
在中列出命令執行 AWS 帳戶
刪除命令執行

啟動命令執行

重要

您全權負責以安全且符合適用法律的方式部署命令。

開始命令執行之前，您必須確定：

您已在 AWS IoT 命名空間中建立命令，並提供承載資訊。當您開始執行命令時，裝置會處理承載中的指示，並執行指定的動作。如需建立命令的詳細資訊，請參閱建立命令資源。
您的裝置已訂閱命令的MQTT預留主題。當您啟動命令執行時，承載資訊將發佈至下列預留MQTT請求主題。

在這種情況下， <devices>可以是 IoT 物件或MQTT用戶端，也可以<DeviceID>是物件名稱或用戶端 ID。支援的<PayloadFormat>是 JSON和 CBOR。如需命令主題的詳細資訊，請參閱命令主題。
```
$aws/commands/<devices>/<DeviceID>/executions/+/request/<PayloadFormat>
```
如果 <PayloadFormat> 不是 JSON和 CBOR，則以下顯示命令主題格式。
```
$aws/commands/<devices>/<DeviceID>/executions/+/request
```

當您想要執行命令時，您必須指定將接收命令的目標裝置，並執行指定的指示。如果裝置尚未在 AWS IoT 登錄檔中註冊，目標裝置可以是 AWS IoT 實物，也可以是用戶端 ID。收到命令承載後，裝置可以開始執行命令並執行指定的動作。

AWS IoT 物件

命令的目標裝置可以是您已在 AWS IoT 物件登錄檔中註冊的 AWS IoT 物件。中的物件 AWS IoT 可讓您更輕鬆地搜尋和管理裝置。

當您 AWS IoT 從 Connect 裝置頁面或使用 CreateThing 將裝置連接到時，您可以將裝置註冊為物件API。您可以從 AWS IoT 主控台的物件中樞頁面或使用 DescribeThing ，找到要執行命令的現有物件API。如需如何將裝置註冊為 AWS IoT 物件的詳細資訊，請參閱使用登錄檔管理物件。

用戶端 ID

如果您的裝置尚未向註冊為物件 AWS IoT，您可以改為使用用戶端 ID。

用戶端 ID 是您指派給裝置或用戶端的唯一識別符。用戶端 ID 是在MQTT通訊協定中定義，且可包含英數字元、底線或破折號。每個連線的裝置都必須是唯一的 AWS IoT。

注意

如果您的裝置已在 AWS IoT 登錄檔中註冊為物件，則用戶端 ID 可以與物件名稱相同。
如果您的命令執行以特定MQTT用戶端 ID 為目標，若要從以用戶端 ID 為基礎的命令主題接收命令承載，您的裝置必須使用相同的用戶端 ID 連線至 AWS IoT 。

用戶端 ID 通常是您的裝置連線時可以使用的MQTT用戶端 ID AWS IoT Core。此 ID 由 AWS IoT 用來識別每個特定裝置，以及管理連線和訂閱。

逾時表示您的裝置可以提供命令執行結果的持續時間，以秒為單位。

建立命令執行後，計時器會啟動。如果裝置離線或無法在逾時持續時間內報告執行結果，則命令執行將會逾時，且執行狀態將報告為 TIMED_OUT。

此欄位是選用的，如果您不指定任何值，則預設為 10 秒。您也可以將逾時設定為最大值 12 小時。

逾時值和`TIMED_OUT`執行狀態

雲端和裝置都可以報告逾時。

命令傳送至裝置後，計時器便會啟動。如果未在指定的逾時持續時間內從裝置收到回應，如上所述。在此情況下，雲端會將命令執行狀態設定為 TIMED_OUT，原因碼為 $NO_RESPONSE_FROM_DEVICE。

這可能會發生在下列任一情況下。

裝置在執行命令時離線。
裝置無法在指定的持續時間內完成執行命令。
裝置無法在逾時持續時間內報告更新的狀態資訊。

在此執行個體中，當從雲端報告 TIMED_OUT的執行狀態時，命令執行為非終端機。您的裝置可以發佈回應，將狀態覆寫為任何終端狀態、 SUCCEEDEDFAILED或 REJECTED。命令執行現在會變成終端機，不接受任何進一步的更新。

您的裝置也可以透過報告執行命令時發生逾時，來更新雲端啟動TIMED_OUT的狀態。在此情況下，命令執行狀態會保持在，TIMED_OUT但statusReason物件會根據裝置報告的資訊更新。命令執行現在會變成終端機，而且不會接受進一步的更新。

使用MQTT持久性工作階段

您可以設定MQTT持久性工作階段以搭配 AWS IoT Device Management 命令功能使用。此功能在例如當您的裝置離線時特別有用，而且您希望確保裝置在逾時持續時間之前恢復上線時仍能收到命令，並執行指定的指示。

根據預設，MQTT持久性工作階段到期設定為 60 分鐘。如果您的命令執行逾時設定為超過此持續時間的值，則執行時間超過 60 分鐘的命令執行可能會遭到訊息代理程式拒絕，而且可能會失敗。若要執行持續時間超過 60 分鐘的命令，您可以請求增加持久性工作階段到期時間。

注意

為了確保您正確使用MQTT持久性工作階段功能，請確定清除開始旗標設定為零。如需詳細資訊，請參閱MQTT持久性工作階段。

若要從主控台開始執行命令，請前往 AWS IoT 主控台的 Command Hub 頁面，並執行下列步驟。

若要執行您建立的命令，請選擇執行命令。
檢閱您建立的命令、承載檔案和格式類型，以及預留MQTT主題的相關資訊。
指定您要為其執行命令的目標裝置。如果裝置已向註冊，則可以指定為 AWS IoT 物件 AWS IoT，如果裝置尚未註冊，則可以使用用戶端 ID。如需詳細資訊，請參閱目標裝置考量事項
（選用）設定命令的逾時值，決定命令在逾時之前執行的持續時間。如果您的命令需要執行超過 60 分鐘，您可能需要增加MQTT持久性工作階段的到期時間。如需詳細資訊，請參閱命令執行逾時考量。
選擇執行命令。

使用StartCommandExecutionHTTP資料平面API操作來啟動命令執行。API 請求和回應與命令執行 ID 相關聯。裝置完成執行命令後，即可將訊息發佈至命令回應主題，向雲端報告狀態和執行結果。對於自訂回應碼，您擁有的應用程式碼可以處理回應訊息並將結果發佈到其中 AWS IoT。

如果您的裝置已訂閱命令請求主題， StartCommandExecutionAPI會將承載訊息發佈至主題。承載可以使用您選擇的任何格式。如需詳細資訊，請參閱命令承載。


$aws/commands/<devices>/<DeviceID>/executions/+/request/<PayloadFormat>

如果承載格式不是 JSON或 CBOR，則以下顯示命令請求主題的格式。


$aws/commands/<devices>/<DeviceID>/executions/+/request

範例IAM政策

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

在此範例中，取代：

region 搭配您的 AWS 區域，例如 ap-south-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"
  ]
}

取得帳戶特定的資料平面端點

執行 API命令之前，您必須取得URL端點的帳戶特定iot:Jobs端點。例如，如果您執行此命令：


aws iot describe-endpoint --endpoint-type iot:Jobs

它將傳回帳戶特定的端點，URL如以下範例回應所示。


{
    "endpointAddress": "<account-specific-prefix>.jobs.iot.<region>.amazonaws.com"
}

啟動命令執行範例 (AWS CLI)

下列範例示範如何使用命令開始執行start-command-execution AWS CLI 命令。

在此範例中，取代：

<command-arn> 使用您要執行之命令ARN的。您可以從 create-commandCLI命令的回應取得此資訊。例如，如果您正在執行變更方向盤模式的命令，請使用 arn:aws:iot:region:account-id:command/SetComfortSteeringMode。
<target-arn> 目標ARN裝置的物件，可以是您要執行命令的 IoT 物件或MQTT用戶端。例如，如果您要執行目標裝置的命令myRegisteredThing，請使用 arn:aws:iot:region:account-id:thing/myRegisteredThing。
<endpoint-url> 使用您在中取得的帳戶特定端點取得帳戶特定的資料平面端點，字首為 https://。例如：https://123456789012abcd.jobs.iot.ap-south-1.amazonaws.com。
（選用）您也可以在執行StartCommandExecutionAPI操作時指定其他參數 executionTimeoutSeconds。此選用欄位指定裝置必須完成執行命令的時間，以秒為單位。根據預設，值為 10 秒。當命令執行狀態為時CREATED，計時器會啟動。如果在計時器過期之前未收到命令執行結果，則狀態會自動變更為 TIMED_OUT。


aws iot-jobs-data start-command-execution \ 
    --command-arn <command-arn>  \
    --target-arn <target-arn> \  
    --endpoint <endpoint-url> \ 
    --executionTimeoutSeconds 900

執行此命令會傳回命令執行 ID。您可以使用此 ID 來查詢命令執行狀態、詳細資訊和命令執行歷史記錄。

注意

如果命令已棄用，則StartCommandExecutionAPI請求會失敗，但出現驗證例外狀況。若要修正此錯誤，請先使用 UpdateCommand 還原命令API，然後執行 StartCommandExecution請求。


{
    "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542"
}

更新命令執行的結果

使用UpdateCommandExecutionMQTT資料平面API操作更新命令執行的狀態或結果。

注意

使用此之前API：

您的裝置必須已建立MQTT連線並訂閱命令請求和回應主題。如需詳細資訊，請參閱高階命令工作流程。
您必須已使用 StartCommandExecutionAPI操作執行此命令。

使用此操作之前API，請確定您的IAM政策授權您的裝置執行這些動作。以下顯示範例政策，授權您的裝置執行動作。如需允許使用者執行UpdateCommandExecution動作的其他範例IAM政策，請參閱連線和發佈政策範例。

在此範例中，取代：

Region ， AWS 區域例如 ap-south-1。
AccountID 您的 AWS 帳戶號碼，例如 123456789012。
ThingName 您以命令執行為目標的 AWS IoT 物件名稱，例如 myRegisteredThing。
commands-request-topic 和 commands-response-topic，以及 AWS IoT 命令請求和回應主題的名稱。如需詳細資訊，請參閱高階命令工作流程。

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

在請求主題收到命令執行後，裝置會處理命令。然後UpdateCommandExecutionAPI，它會使用將命令執行的狀態和結果更新為下列回應主題。


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

在此範例中， <DeviceID> 是目標裝置的唯一識別符，而 <execution-id>是目標裝置上命令執行的識別符。<PayloadFormat> 可以是 JSON或 CBOR。

注意

如果您尚未向註冊裝置 AWS IoT，您可以使用用戶端 ID 做為識別符，而不是物件名稱。


$aws/commands/clients/<ClientID>/executions/<ExecutionId>/response/<PayloadFormat>

裝置回報執行狀態的更新

您的裝置可以使用 API來報告命令執行的任何下列狀態更新。如需這些狀態的詳細資訊，請參閱命令執行狀態。

IN_PROGRESS：當裝置開始執行命令時，它可以將狀態更新為 IN_PROGRESS。
SUCCEEDED：當裝置成功處理命令並完成執行時，裝置可以將訊息發佈至回應主題，做為 SUCCEEDED。
FAILED：如果裝置無法執行命令，它可以將訊息以形式發佈到回應主題FAILED。
REJECTED：如果裝置無法接受命令，它可以將訊息發佈至回應主題，做為 REJECTED。
TIMED_OUT：TIMED_OUT由於下列任何原因，命令執行狀態可能會變更為。
- 未收到命令執行的結果。這可能是因為未在指定的持續時間內完成執行，或裝置無法將狀態資訊發佈至回應主題。
- 裝置報告嘗試執行命令時發生逾時。

如需 TIMED_OUT 狀態的詳細資訊，請參閱逾時值和TIMED_OUT執行狀態。

使用時的考量事項 `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 中的AWSIoTLogsV2日誌群組中檢視錯誤 CloudWatch。如需啟用記錄和檢視日誌的資訊，請參閱設定 AWS IoT 記錄。

`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。您可以取得下列資訊。

注意

若要擷取最新的命令執行狀態，您的裝置必須使用將狀態資訊發佈至回應主題UpdateCommandExecutionMQTTAPI，如下所述。在裝置發佈至此主題之前， GetCommandExecutionAPI會將狀態報告為 CREATED或 TIMED_OUT。

您建立的每個命令執行都會有：

執行 ID，這是命令執行的唯一識別符。
命令執行的狀態。當您在目標裝置上執行命令時，命令執行會進入 CREATED 狀態。然後，它可以轉換到其他命令執行狀態，如下所述。
命令執行的結果。
唯一的命令 ID 和已建立執行的目標裝置。
開始日期，顯示建立命令執行的時間。

您可以使用下列其中一種方法，從主控台擷取命令執行。

從命令中樞頁面

前往 AWS IoT 主控台的 Command Hub 頁面，並執行這些步驟。
1. 選擇您在目標裝置上建立執行的命令。
2. 在命令詳細資訊頁面的命令歷史記錄索引標籤中，您會看到您建立的執行。選擇您要擷取資訊的執行。
3. 如果您的裝置使用 UpdateCommandExecution API 提供結果資訊，您可以在此頁面的結果索引標籤中找到此資訊。
從物件中樞頁面

如果您在執行命令時選擇 AWS IoT 物件做為目標裝置，您可以從物件中樞頁面檢視執行詳細資訊。
1. 前往 AWS IoT 主控台中的物件中樞頁面，然後選擇您為其建立命令執行的物件。
2. 在物件詳細資訊頁面的命令歷史記錄中，您會看到您建立的執行。選擇您要擷取資訊的執行。
3. 如果您的裝置使用 UpdateCommandExecution API 提供結果資訊，您可以在此頁面的結果索引標籤中找到此資訊。

使用GetCommandExecution AWS IoT Core 控制平面HTTPAPI操作擷取命令執行的相關資訊。您必須已使用 StartCommandExecutionAPI操作執行此命令。

範例IAM政策

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

在此範例中，取代：

region 搭配您的 AWS 區域，例如 ap-south-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 命令的相關資訊。下列範例示範如何擷取已執行的命令相關資訊，以關閉方向盤模式。

在此範例中，取代：

<execution-id> 具有您要擷取資訊的命令執行識別符。
<target-arn> 使用您要鎖定執行目標之裝置的 Amazon Resource Number (ARN)。您可以從 start-command-executionCLI命令的回應取得此資訊。
或者，如果您的裝置使用 UpdateCommandExectionAPI來提供執行結果，您可以指定是否GetCommandExecutionAPI使用 GetCommandExecution 將命令執行結果包含在的回應中API。


aws iot get-command-execution  
    --execution-id <execution-id> \ 
    --target-arn <target-arn> \
    --include-result

執行此命令會產生回應，其中包含命令執行ARN的、執行狀態，以及開始執行的時間和完成時間的相關資訊。它也提供statusReason物件，其中包含狀態的其他資訊。如需不同狀態和狀態原因的詳細資訊，請參閱命令執行狀態。

下列程式碼顯示請求的範例回應API。

注意

執行回應中的 completedAt 欄位對應至裝置向雲端回報終端機狀態的時間。在TIMED_OUT狀態的情況下，只有在裝置報告逾時時，才會設定此欄位。狀態由雲端設定TIMED_OUT時，TIMED_OUT狀態不會更新。如需逾時行為的詳細資訊，請參閱命令執行逾時考量。


{
    "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542",
    "commandArn": "arn:aws:iot:ap-south-1:123456789012:command/LockDoor",
    "targetArn": "arn:aws:iot:ap-south-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預留請求主題，則會看到發佈至此主題的承載訊息。

然後，裝置會收到承載指示，並在 IoT 裝置上執行指定的操作。然後，它會使用 UpdateCommandExecutionAPI將命令執行結果和狀態資訊發佈至 command. AWS IoT Device Management listens 的MQTT預留回應主題，以更新回應主題，並將更新的資訊和發佈日誌至 AWS CloudTrail 和 Amazon CloudWatch。然後，您可以從主控台或使用 GetCommandExecution 擷取最新的命令執行資訊API。

下列步驟說明如何使用MQTT測試用戶端來觀察訊息。

在 AWS IoT 主控台中開啟MQTT測試用戶端。
在訂閱索引標籤上，輸入下列主題，然後選擇訂閱，其中 <thingId>是您已註冊之裝置的物件名稱 AWS IoT。

注意
您可以在 AWS IoT 主控台的物件中樞頁面找到裝置的物件名稱，或者，如果裝置尚未註冊為物件，您可以在 AWS IoT 從 Connect 裝置頁面連線至時註冊裝置。
```
$aws/commands/things/<thingId>/executions/+/request
```

（選用）在訂閱索引標籤上，您也可以輸入下列主題，然後選擇訂閱。


$aws/commands/things/+/executions/+/response/accepted/json
$aws/commands/things/+/executions/+/response/rejected/json

當您啟動命令執行時，將使用裝置已訂閱的請求主題，將訊息承載傳送至裝置$aws/commands/things/<thingId>/executions/+/request。在MQTT測試用戶端中，您應該會看到命令承載，其中包含裝置處理命令的指示。
裝置開始執行命令後，可以將狀態更新發佈到下列MQTT保留回應主題，以用於命令。
```
$aws/commands/<devices>/<device-id>/executions/<executionId>/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 頁面，並執行這些步驟。
1. 選擇您在目標裝置上建立執行的命令。
2. 在命令詳細資訊頁面中，前往命令歷史記錄索引標籤，您會看到您建立的執行清單。
從物件中樞頁面

如果您在執行命令時選擇 AWS IoT 物件做為目標裝置，並為單一裝置建立多個命令執行，您可以從物件中樞頁面檢視裝置的執行。
1. 前往 AWS IoT 主控台中的物件中樞頁面，然後選擇您為其建立執行的物件。
2. 在物件詳細資訊頁面的命令歷史記錄中，您會看到為裝置建立的執行清單。

使用ListCommandExecutions AWS IoT Core 控制平面HTTPAPI操作列出您帳戶中的所有命令執行。

範例IAM政策

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

在此範例中，取代：

region ， AWS 區域例如 ap-south-1。
account-id 您的 AWS 帳戶號碼，例如 123456789012。
command-id 使用您唯一的 AWS IoT 命令識別符，例如 LockDoor。


{
  "Effect": "Allow",
  "Action": "iot:ListCommandExecutions",
  "Resource": *
}

列出命令執行範例

下列範例示範如何在中列出命令執行 AWS 帳戶。

執行命令時，您必須指定是否要篩選清單，以僅顯示使用為特定裝置建立的命令執行targetArn，還是使用指定的特定命令執行commandArn。

在此範例中，取代：

<target-arn> 搭配您以執行為目標之裝置的 Amazon Resource Number (ARN)，例如 arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f。
<target-arn> 搭配您以執行為目標之裝置的 Amazon Resource Number (ARN)，例如 arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f。
<after> ，以及您想要列出建立之執行的時間，例如 2024-11-01T03:00。


aws iot list-command-executions \ 
--target-arn <target-arn> \ 
--started-time-filter '{after=<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"
        }
    ]
}

如需不同狀態和狀態原因的詳細資訊，請參閱命令執行狀態。

刪除命令執行

如果您不想再使用命令執行，可以從您的帳戶永久移除它。

注意

命令執行只有在進入終端機狀態時，才能刪除，例如 SUCCEEDED、 FAILED或 REJECTED。
此操作只能使用 AWS IoT Core API或執行 AWS CLI。無法從主控台使用。

使用此操作之前API，請確定您的IAM政策授權您的裝置執行這些動作。以下顯示授權您的裝置執行動作的範例政策。

在此範例中，取代：

Region ， AWS 區域例如 ap-south-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 命令。根據您的應用程式，將 <execution-id>取代為您要刪除的命令執行識別符，並將 <target-arn>取代為目標裝置的 ARN 。


aws iot delete-command-execution \ 
--execution-id <execution-id> \ 
--target-arn <target-arn>

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

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

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

文件慣用形式

建立和管理命令

棄用命令資源

啟動和監控命令執行

啟動和監控命令操作

啟動命令執行

重要

AWS IoT 物件

用戶端 ID

注意

逾時值和TIMED_OUT執行狀態

使用MQTT持久性工作階段

注意

範例IAM政策

取得帳戶特定的資料平面端點

啟動命令執行範例 (AWS CLI)

注意

更新命令執行的結果

注意

MQTT 用戶端 ID IAM的政策範例

IoT 物件IAM的政策範例

注意

裝置回報執行狀態的更新

使用 時的考量事項 UpdateCommandExecution API

UpdateCommandExecution API 範例

擷取命令執行

注意

從命令中樞頁面

從物件中樞頁面

範例IAM政策

擷取命令執行範例

注意

使用MQTT測試用戶端檢視命令更新

注意

在 中列出命令執行 AWS 帳戶

從命令中樞頁面

從物件中樞頁面

範例IAM政策

列出命令執行範例

刪除命令執行

注意

逾時值和`TIMED_OUT`執行狀態

使用時的考量事項 `UpdateCommandExecution` API

`UpdateCommandExecution` API 範例

在中列出命令執行 AWS 帳戶