開始和監控命令執行

指定要接收和執行 命令的目標裝置。將物件名稱用於已註冊的裝置，或將用戶端 ID 用於未註冊的裝置。收到承載後，裝置會執行 命令並執行指定的動作。

AWS IoT 物件

目標裝置可以是在 AWS IoT 登錄檔中註冊的物件。物件可簡化裝置搜尋和管理。

從 Connect 裝置頁面或使用 將裝置註冊為實物CreateThing。從物件中樞或使用 尋找現有的物件DescribeThing。如需註冊詳細資訊，請參閱使用登錄檔管理物件。

用戶端 ID

對於未註冊的裝置，請使用用戶端 ID。

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

用戶端 ID 是連線至 時使用的 MQTT 用戶端 ID 裝置 AWS IoT Core。 AWS IoT 使用此 ID 來識別裝置和管理連線和訂閱。

逾時會指定裝置提供執行結果的持續時間 （以秒為單位）。

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

預設：10 秒。上限：12 小時。

逾時值和TIMED_OUT執行狀態

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

傳送 命令後，計時器會啟動。如果沒有裝置回應在逾時內到達，則雲端會將執行狀態設定為 ，TIMED_OUT原因碼為 $NO_RESPONSE_FROM_DEVICE。

發生下列情況時，會發生這種情況：

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

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

使用 MQTT 持久性工作階段

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

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

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

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

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

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

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

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

範例 IAM 政策

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

在此範例中，取代：

{
  "Effect": "Allow",
  "Action": [
      "iot:StartCommandExecution"
  ],
  "Resource": [
      "arn:aws:iot:region:account-id:command/command-id",
      "arn:aws:iot:region:account-id:devices/device-id"
  ]
}

若要查看 支援的條件金鑰清單StartCommandExecution，請參閱《IAM 使用者指南》中的 的條件金鑰 AWS IoT。

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

執行 API 命令之前，您必須取得端點的帳戶特定端點 URL。如果您使用的是雙堆疊端點 (IPv4 和 IPv6)，請使用 iot:Data-ATS。iot:Jobs 端點僅適用於 IPv4。例如，如果您執行此命令：

aws iot describe-endpoint --endpoint-type iot:Data-ATS

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

{
    "endpointAddress":
    "<account-specific-prefix>-ats.iot.<region>.api.com"
}

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

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

在此範例中，取代：

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

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

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

在此範例中，取代：

MQTT 用戶端 ID 的 IAM 政策範例

下列程式碼顯示使用 MQTT 用戶端 ID 時的範例裝置政策。

IoT 物件的 IAM 政策範例

下列程式碼顯示使用 AWS IoT 物件時的範例裝置政策。

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

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

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

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

裝置回報執行狀態的更新

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

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

使用 UpdateCommandExecution API 時的考量事項

以下是使用 UpdateCommandExecution API 時的一些重要考量。

UpdateCommandExecution API 範例

以下程式碼顯示您的裝置如何使用 UpdateCommandExecution API 報告執行狀態的範例、提供狀態額外資訊statusReason的欄位，以及提供執行結果相關資訊的結果欄位，例如在此情況下的汽車電池百分比。

{
  "status": "IN_PROGRESS",
  "statusReason": {
    "reasonCode": "200",
    "reasonDescription": "Execution_in_progress"
  },
  "result": {
        "car_battery": {
            "s": "car battery at 50 percent"
        }
    }
}

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

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

範例 IAM 政策

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

在此範例中，取代：

{
  "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 命令的相關資訊。下列範例顯示如何擷取已執行之命令的相關資訊，以關閉方向盤模式。

在此範例中，取代：

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

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

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

{
    "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542",
    "commandArn": "arn:aws:iot:us-east-1:123456789012:command/LockDoor",
    "targetArn": "arn:aws:iot:us-east-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"    
}

您可以使用下列其中一種方法，從主控台查看所有命令執行。

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

範例 IAM 政策

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

在此範例中，取代：

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

列出命令執行範例

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

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

在此範例中，取代：

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

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

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

在此範例中，取代：

{
  "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 狀態碼。您可以使用 GetCommandExecution API 來驗證 帳戶中不再存在命令執行。