啟動和監控命令執行

重要

對特定 AWS IoT FleetWise 功能的存取目前受到鎖定。如需詳細資訊，請參閱AWSAWS IoT FleetWise 中的區域和功能可用性。

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

本主題說明如何使用 AWS CLI or AWS IoT FleetWise 主控台將命令傳送至您的車輛。它還說明如何監控和更新命令執行的狀態。

主題

更新命令執行結果
取得命令執行
列出您帳戶中的命令執行
刪除命令執行

若要從主控台傳送命令，請前往 AWS IoT FleetWise 主控台的車輛頁面，並執行下列步驟。

選擇您要傳送命令的車輛。
選擇執行命令。
選取命令 ID。
指定命令執行逾時，然後選擇執行命令。

您可以使用StartCommandExecution AWS IoT 資料平面 API 操作，將命令傳送至車輛。接著，車輛會將命令轉送至汽車中介軟體服務（例如 SOME/IP （透過 IP 的可擴展服務導向中介軟體）)，或將其發佈至車輛網路（例如控制器區域網路 (CAN) 裝置界面）。下列為使用 AWS CLI的範例。

傳送命令時的考量事項

當您在中啟動命令執行時 AWS IoT FleetWise：

您必須為車輛佈建 AWS IoT 物件。如需詳細資訊，請參閱Provision AWS IoT FleetWise 車輛。
您必須已使用建立命令AWS-IoT-FleetWise做為命名空間role-Arn，並提供授予您在 AWS IoT FleetWise 中建立和執行命令的許可。如需詳細資訊，請參閱建立命令資源。
如果您選擇在建立命令時使用為參數指定的任何預設值，則可以略過 parameters 欄位。如果mandatory-parameters未在建立時指定，或者如果您想要透過為參數指定自己的值來覆寫任何預設值，則必須指定 parameters 欄位。如需這些其他範例，請參閱命令使用案例。
您可以為 mandatory-parameters 欄位指定最多三個名稱/值對。不過，在車輛上執行命令時，只接受一個名稱/值對，而 name 欄位必須使用完整名稱與$actuatorPath.字首。

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

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


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

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


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

傳送命令範例

若要將命令傳送至車輛，請執行下列命令。

將 command-arn 取代為您要執行之命令的 ARN。您可以從 CLI create-command 命令的回應取得此資訊。
將 target-arn 取代為您要執行命令的目標裝置或 AWS IoT 物件的 ARN。

注意
您可以指定 AWS IoT 物件的目標 ARN (AWS IoT FleetWise 車輛）。目前不支援物件群組和機群。
以您在中取得的帳戶特定端點取代 endpoint-url取得帳戶特定的資料平面端點，字首為 https://，例如 https://123456789012abcd.jobs.iot.ap-south-1.amazonaws.com。
將名稱和值取代為您使用 CLI create-command 建立命令時指定的mandatory-parameters欄位。

name 欄位是訊號目錄中定義的完整名稱，字首$actuatorPath.為。例如， name可以是 $actuatorPath.Vehicle.Chassis.SteeringWheel.HandsOff.HandsOffSteeringMode，value也可以是指示轉向模式狀態的布林值，例如 {"B"： false}。
（選用）您也可以指定其他參數 executionTimeoutSeconds。此選用欄位指定裝置必須以執行結果回應的時間，以秒為單位。您可以將逾時設定為最大值 24 小時。

建立命令執行後，計時器會啟動。在計時器過期之前，如果命令執行狀態未變更為使其終止的狀態，例如 SUCCEEDED或 FAILED，則狀態會自動變更為 TIMED_OUT。

注意
裝置也可以報告TIMED_OUT狀態，或將此狀態覆寫為狀態，例如 SUCCEEDED、 FAILED或 REJECTED，而且命令執行會變成終端機。如需詳細資訊，請參閱命令執行逾時狀態。


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 連線並訂閱下列命令請求主題。

在此範例中，將取代<device-id>為目標裝置的唯一識別符，可以是 VehicleId或物件名稱，並將 <execution-id>取代為命令執行的識別符。

注意

承載必須使用 protobuf 格式。
您的裝置可選擇是否訂閱 /accepted和 /rejected回應主題。即使您的裝置尚未明確訂閱，也會收到這些回應訊息。


// Request topic
$aws/devices/<DeviceID>/command_executions/+/request/protobuf

// Response topics (Optional)
$aws/devices/<DeviceID>/command_executions/<ExecutionId>/response/accepted/protobuf
$aws/devices/<DeviceID>/command_executions/<ExecutionId>/response/rejected/protobuf

您的裝置可以將訊息發佈至命令回應主題。處理命令之後，它會傳送 protobuf 編碼的回應至此主題。<DeviceID> 欄位必須符合請求主題中的對應欄位。


$aws/devices/<DeviceID>/command_executions/<ExecutionId>/response/<PayloadFormat>

裝置發佈對本主題的回應後，您可以使用 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 測試用戶端檢視命令更新。

取得命令執行

您可以使用GetCommandExecution 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狀態不會更新。如需逾時行為的詳細資訊，請參閱命令執行逾時狀態。


{
    "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 }
    }' 
}

列出您帳戶中的命令執行

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

主題

列出命令執行時的考量事項
列出命令執行範例

列出命令執行時的考量事項

以下是使用 ListCommandExecutions API 時的一些考量。

您必須commandArn根據要列出特定命令targetArn或目標車輛的執行，至少指定或。API 請求不能是空的，也不能包含相同請求中的兩個欄位。
您必須僅提供 startedTimeFilter或 completedTimeFilter資訊。API 請求不能是空的，也不能包含相同請求中的兩個欄位。您可以使用物件的 before和 after 欄位，列出在特定時間範圍內建立或完成的命令執行。
before 和 after 欄位不得大於目前時間。根據預設，如果您未指定任何值， before 欄位是目前時間， after 欄位是目前時間 - 6 個月。也就是說，根據您使用的篩選條件，API 會列出過去六個月內建立或完成的所有執行。
您可以使用 sort-order 參數來指定是否要以遞增順序列出執行。根據預設，如果您未指定此欄位，則執行會以遞減順序列出。
當列出命令 ARN 的命令執行時，您無法根據命令執行的狀態來篩選命令執行。

列出命令執行範例

下列範例示範如何在中列出命令執行 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。

下列範例示範如何使用命令刪除delete-command-execution AWS CLI 命令執行。<execution-id> 將取代為您要刪除之命令執行的識別符。


aws iot delete-command-execution --execution-id <execution-id>

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

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

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

文件慣用形式

建立和管理命令

範例：使用命令