本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 開始和監控命令執行 **重要** 對特定 AWS IoT FleetWise 功能的存取目前受到鎖定。如需詳細資訊，請參閱[AWS AWS IoT FleetWise 中的區域和功能可用性](fleetwise-regions.md)。 建立命令資源之後，您可以在目標車輛上啟動命令執行。一旦車輛開始執行命令，就可以開始更新命令執行的結果，並將狀態更新和結果資訊發佈至 MQTT 預留主題。然後，您可以擷取命令執行的狀態，並監控帳戶中執行的狀態。 本主題說明如何使用 AWS CLI or AWS IoT FleetWise 主控台將命令傳送至您的 車輛。它還說明如何監控和更新命令執行的狀態。 **Topics** + [ ## 更新命令執行結果 ](#update-remote-command-execution-cli) + [ ## 取得命令執行 ](#get-remote-command-execution-cli) + [ ## 列出您帳戶中的命令執行 ](#list-remote-command-execution-cli) + [ ## 刪除命令執行 ](#delete-remote-command-execution-cli) ## 傳送命令 （主控台） 若要從主控台傳送命令，請前往 AWS IoT FleetWise 主控台[的車輛](https://console.aws.amazon.com/iotfleetwise/home#/vehicles)頁面，並執行下列步驟。 1. 選擇您要傳送命令的車輛。 1. 選擇**執行命令**。 1. 選取命令 ID。 1. 指定命令執行逾時，然後選擇**執行命令**。 ## 傳送命令 (AWS CLI) 您可以使用[https://docs.aws.amazon.com/iot/latest/apireference/API_iot_data_StartCommandExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot_data_StartCommandExecution.html) AWS IoT 資料平面 API 操作，將命令傳送至車輛。接著，車輛會將命令轉送至汽車中介軟體服務 （例如 SOME/IP （透過 IP 的可擴展服務導向中介軟體）)，或將其發佈至車輛網路 （例如控制器區域網路 (CAN) 裝置界面）。下列為使用 AWS CLI的範例。 **Topics** + [ ### 傳送命令時的考量事項 ](#send-remote-command-considerations) + [ ### 取得帳戶特定的資料平面端點 ](#send-remote-command-endpoint) + [ ### 傳送命令範例 ](#send-remote-command-example) ### 傳送命令時的考量事項 當您在 中啟動命令執行時 AWS IoT FleetWise： + 您必須為車輛佈建 AWS IoT 物件。如需詳細資訊，請參閱[Provision AWS IoT FleetWise 車輛](provision-vehicles.md)。 + 您必須已使用 建立 命令`AWS-IoT-FleetWise`做為命名空間`role-Arn`，並提供 授予您在 AWS IoT FleetWise 中建立和執行命令的許可。如需詳細資訊，請參閱[建立命令資源](create-manage-remote-command-cli.md#create-remote-command-cli)。 + 如果您選擇在建立命令時使用為參數指定的任何預設值，則可以略過 `parameters` 欄位。如果`mandatory-parameters`未在建立時指定 ，或者如果您想要透過為參數指定自己的值來覆寫任何預設值，則必須指定 `parameters` 欄位。如需這些其他範例，請參閱 [命令使用案例](remote-command-use-cases.md)。 + 您可以為 `mandatory-parameters` 欄位指定最多三個名稱/值對。不過，在車輛上執行 命令時，只接受一個名稱/值對，而 `name` 欄位必須使用完整名稱與`$actuatorPath.`字首。 ### 取得帳戶特定的資料平面端點 執行 API 命令之前，您必須取得端點的帳戶特定`iot:Jobs`端點 URL。例如，如果您執行此命令： ``` aws iot describe-endpoint --endpoint-type iot:Jobs ``` 它會傳回帳戶特定的端點 URL，如以下範例回應所示。 ``` { "endpointAddress": ".jobs.iot..amazonaws.com" } ``` ### 傳送命令範例 若要將命令傳送至車輛，請執行下列命令。 + 將 *command-arn* 取代為您要執行之命令的 ARN。您可以從 CLI `create-command` 命令的回應取得此資訊。 + 將 *target-arn* 取代為您要執行命令的目標裝置或 AWS IoT 物件的 ARN。 **注意** 您可以指定 AWS IoT 物件的目標 ARN (AWS IoT FleetWise 車輛）。目前不支援物件群組和機群。 + 以您在 中取得的帳戶特定端點取代 *endpoint-url*[取得帳戶特定的資料平面端點](#send-remote-command-endpoint)，字首為 `https://`，例如 `https://123456789012abcd.jobs.iot.ap-south-1.amazonaws.com`。 + 將*名稱*和*值*取代為您使用 CLI `create-command` 建立命令時指定的`mandatory-parameters`欄位。 `name` 欄位是訊號目錄中定義的完整名稱，字首`$actuatorPath.`為 。例如， `name` 可以是 *\$1actuatorPath.Vehicle.Chassis.SteeringWheel.HandsOff.HandsOffSteeringMode*，`value`也可以是指示轉向模式狀態的布林值，例如 *\$1"B"： false\$1*。 + （選用） 您也可以指定其他參數 `executionTimeoutSeconds`。此選用欄位指定裝置必須以執行結果回應的時間，以秒為單位。您可以將逾時設定為最大值 24 小時。 建立命令執行後，計時器就會啟動。在計時器過期之前，如果命令執行狀態未變更為使其終止的狀態，例如 `SUCCEEDED`或 `FAILED`，則狀態會自動變更為 `TIMED_OUT`。 **注意** 裝置也可以報告`TIMED_OUT`狀態，或將此狀態覆寫為 狀態，例如 `SUCCEEDED`、 `FAILED`或 `REJECTED`，而且命令執行會變成終端機。如需詳細資訊，請參閱[命令執行逾時狀態](remote-command-concepts-states.md#remote-command-execution-status-timeout)。 ``` aws iot-jobs-data start-command-execution \ --command-arn command-arn \ --target-arn target-arn \ --execution-timeout-seconds 30 \ --endpoint-url endpoint-url \ --parameters '[ { "name": name, "value": value } ]' ``` `StartCommandExecution` API 操作會傳回命令執行 ID。您可以使用此 ID 查詢命令執行狀態、詳細資訊和命令執行歷史記錄。 ``` { "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542" } ``` 執行 命令後，您的裝置會收到包含下列資訊的通知。`issued_timestamp_ms` 欄位對應至叫用 `StartCommandExecution` API 的時間。`timeout_ms` 對應至叫用 `StartCommandExecution` API 時使用 `executionTimeoutSeconds` 參數設定的逾時值。 ``` timeout_ms: 9000000 issued_timestamp_ms: 1723847831317 ``` ## 更新命令執行結果 若要更新命令執行的狀態，您的裝置必須已建立 MQTT 連線並訂閱下列命令請求主題。 在此範例中，將 取代*``*為目標裝置的唯一識別符，可以是 `VehicleId`或物件名稱，並將 *``*取代為命令執行的識別符。 **注意** 承載必須使用 protobuf 格式。 您的裝置可選擇是否訂閱 `/accepted`和 `/rejected`回應主題。即使您的裝置尚未明確訂閱，也會收到這些回應訊息。 ``` // Request topic $aws/devices//command_executions/+/request/protobuf // Response topics (Optional) $aws/devices//command_executions//response/accepted/protobuf $aws/devices//command_executions//response/rejected/protobuf ``` 您的裝置可以將訊息發佈至命令回應主題。處理命令後，它會傳送 protobuf 編碼的回應至此主題。** 欄位必須符合請求主題中的對應欄位。 ``` $aws/devices//command_executions//response/ ``` 裝置發佈對本主題的回應後，您可以使用 `GetCommandExecution` API 擷取更新的狀態資訊。命令執行的狀態可以是此處列出的任何項目。 + `IN_PROGRESS` + `SUCCEEDED` + `FAILED` + `REJECTED` + `TIMED_OUT` 請注意，狀態為 `SUCCEEDED`、 `FAILED`和 的命令執行`REJECTED`為終端機，且狀態是由裝置回報。當命令執行為終端機時，這表示不會進一步更新其狀態或相關欄位。裝置或雲端可能會報告`TIMED_OUT`狀態。如果雲端回報，裝置稍後可能會更新狀態原因欄位。 例如，以下顯示裝置發佈的範例 MQTT 訊息。 **注意** 針對命令執行狀態，如果您的裝置使用 `statusReason` 物件來發佈狀態資訊，您必須確定： `reasonCode` 使用 模式 `[A-Z0-9_-]+`，長度不超過 64 個字元。 長度`reasonDescription`不超過 1，024 個字元。它可以使用控制字元以外的任何字元，例如新行。 ``` { "deviceId": "", "executionId": "", "status": "CREATED", "statusReason": { "reasonCode": "", "reasonDescription": "" } } ``` 如需示範如何使用 AWS IoT Core MQTT 測試用戶端訂閱主題並查看命令執行訊息的範例，請參閱《 *AWS IoT Core 開發人員指南*》中的[使用 MQTT 測試用戶端檢視命令更新](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command-execution-start-monitor.html#iot-remote-command-execution-update-mqtt)。 ## 取得命令執行 您可以使用[https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommandExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommandExecution.html) AWS IoT 控制平面 API 操作來擷取命令執行的相關資訊。您必須已使用 `StartCommandExecution` API 操作執行此命令。 若要擷取已執行命令的中繼資料，請執行下列命令。 + 將 *execution-id* 取代為 命令的 ID。您可以從 CLI `start-command-execution` 命令的回應取得此資訊。 + 將 *target-arn* 取代為您要執行命令的目標車輛或 AWS IoT 物件的 ARN。 ``` aws iot get-command-execution --execution-id execution-id \ --target-arn target-arn ``` `GetCommandExecution` API 操作會傳回回應，其中包含命令執行的 ARN、執行狀態，以及命令開始執行的時間和完成時間的相關資訊。下列程式碼顯示來自 API 請求的範例回應。 為了提供有關每個命令執行狀態的其他內容，命令功能會提供 `statusReason` 物件。物件包含兩個欄位 `reasonCode`和 `reasonDescription`。使用這些欄位，您的裝置可以提供有關命令執行狀態的其他資訊。此資訊將覆寫從雲端報告的任何預設 `reasonCode`和 `reasonDescription` 。 若要報告此資訊，您的裝置可以將更新的狀態資訊發佈至雲端。然後，當您使用 `GetCommandExecution` API 擷取命令執行狀態時，您會看到最新的狀態碼。 **注意** 執行回應中的 `completedAt` 欄位對應至裝置向雲端回報終端機狀態的時間。在`TIMED_OUT`狀態的情況下，只有在裝置報告 A 逾時時，才會設定此欄位。狀態由雲端設定`TIMED_OUT`時，`TIMED_OUT`狀態不會更新。如需逾時行為的詳細資訊，請參閱 [命令執行逾時狀態](remote-command-concepts-states.md#remote-command-execution-status-timeout)。 ``` { "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/myFrontDoor", "status": "SUCCEEDED", "statusReason": { "reasonCode": "65536", "reasonDescription": "SUCCESS" }, "createdAt": "2024-03-23T00:50:10.095000-07:00", "completedAt": "2024-03-23T00:50:10.095000-07:00", "Parameters": '{ "$actuatorPath.Vehicle.Chassis.SteeringWheel.HandsOff.HandsOffSteeringMode": { "B": true } }' } ``` ## 列出您帳戶中的命令執行 使用[https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommandExecutions.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommandExecutions.html) AWS IoT Core 控制平面 HTTP API 操作列出您帳戶中的所有命令執行。此範例使用 AWS CLI。 **Topics** + [ ### 列出命令執行時的考量事項 ](#list-remote-command-considerations) + [ ### 列出命令執行範例 ](#list-remote-command-example) ### 列出命令執行時的考量事項 以下是使用 `ListCommandExecutions` API 時的一些考量。 + 您必須指定至少 `targetArn`或 ，`commandArn`取決於您是否要列出特定命令或目標車輛的執行。API 請求不能是空的，也不能包含相同請求中的兩個欄位。 + 您必須僅提供 `startedTimeFilter`或 `completedTimeFilter`資訊。API 請求不能是空的，也不能包含相同請求中的兩個欄位。您可以使用 物件的 `before`和 `after` 欄位，列出在特定時間範圍內建立或完成的命令執行。 + `before` 和 `after` 欄位不得大於目前時間。根據預設，如果您未指定任何值， `before` 欄位是目前時間， `after` 欄位是目前時間 - 6 個月。也就是說，根據您使用的篩選條件，API 會列出過去六個月內建立或完成的所有執行。 + 您可以使用 `sort-order` 參數來指定是否要以遞增順序列出執行。根據預設，如果您未指定此欄位，則執行會以遞減順序列出。 + 當列出命令 ARN 的命令執行時，您無法根據命令執行的狀態來篩選命令執行。 ### 列出命令執行範例 下列範例示範如何在 中列出命令執行 AWS 帳戶。 執行 命令時，您必須指定是否要篩選清單，以僅顯示使用 為特定裝置建立的命令執行`targetArn`，還是使用 為特定命令指定的執行`commandArn`。 在此範例中，取代： + *``* 您以執行為目標之裝置的 Amazon Resource Number (ARN)，例如 `arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f`。 + *``* 您以執行為目標之裝置的 Amazon Resource Number (ARN)，例如 `arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f`。 + *``* 以及您想要列出建立之執行的時間，例如 `2024-11-01T03:00`。 ``` aws iot list-command-executions \ --target-arn \ --started-time-filter '{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`。 下列範例示範如何使用 命令刪除`delete-command-execution` AWS CLI 命令執行。*``* 將 取代為您要刪除之命令執行的識別符。 ``` aws iot delete-command-execution --execution-id ``` 如果 API 請求成功，則命令執行會產生 200 狀態碼。您可以使用 `GetCommandExecution` API 來驗證 帳戶中不再存在命令執行。