コマンド実行の開始とモニタリング

コマンドリソースを作成したら、ターゲット車両でコマンド実行を開始できます。車両がコマンドの実行を開始すると、コマンド実行の結果の更新を開始し、ステータスの更新と結果情報を MQTT 予約済みトピックに発行できます。その後、コマンド実行のステータスを取得し、アカウントの実行のステータスをモニタリングできます。

このトピックでは、 AWS CLI または AWS IoT FleetWise コンソールを使用して車両にコマンドを送信する方法について説明します。また、コマンド実行のステータスをモニタリングおよび更新する方法も示します。

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

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

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

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

timeout_ms: 9000000
issued_timestamp_ms: 1723847831317

コマンド実行結果を更新する

コマンド実行のステータスを更新するには、デバイスが MQTT 接続を確立し、次のコマンドリクエストトピックをサブスクライブしている必要があります。

この例では、 をターゲットデバイスの一意の識別子<device-id>、 VehicleIdまたはモノの名前、 をコマンド実行の識別子<execution-id>に置き換えます。

// 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 を使用して更新されたステータス情報を取得できます。コマンド実行のステータスは、ここにリストされているもののいずれかになります。

ステータス SUCCEEDED、、 FAILEDのいずれかのコマンド実行REJECTEDはターミナルであり、ステータスはデバイスによって報告されることに注意してください。コマンド実行がターミナルの場合、ステータスや関連フィールドはそれ以上更新されません。TIMED_OUT ステータスは、デバイスまたはクラウドによって報告される場合があります。クラウドから報告された場合、後でデバイスによってステータス理由フィールドの更新が行われることがあります。

例えば、デバイスが発行する MQTT メッセージの例を次に示します。

{
    "deviceId": "",
    "executionId": "",
    "status": "CREATED",
    "statusReason": {
        "reasonCode": "",
        "reasonDescription": ""
    }
}

AWS IoT Core MQTT テストクライアントを使用してトピックをサブスクライブし、コマンド実行メッセージを表示する方法を示す例については、 デAWS IoT Core ベロッパーガイドの「MQTT テストクライアントを使用したコマンドの更新の表示」を参照してください。

コマンド実行の取得

GetCommandExecution AWS IoT コントロールプレーン API オペレーションを使用して、コマンド実行に関する情報を取得できます。StartCommandExecution API オペレーションを使用してこのコマンドをすでに実行している必要があります。

実行されたコマンドのメタデータを取得するには、次のコマンドを実行します。

aws iot get-command-execution --execution-id execution-id \ 
    --target-arn target-arn

GetCommandExecution API オペレーションは、コマンド実行の ARN、実行ステータス、コマンドの実行開始時刻と完了時刻に関する情報を含むレスポンスを返します。次のコードは、API リクエストからのレスポンスの例を示しています。

各コマンド実行のステータスに関する追加のコンテキストを提供するために、 コマンド機能は statusReason オブジェクトを提供します。オブジェクトには、 reasonCodeと の 2 つのフィールドが含まれていますreasonDescription。これらのフィールドを使用すると、デバイスはコマンド実行のステータスに関する追加情報を提供できます。この情報は、クラウドから報告されたデフォルトの reasonDescription reasonCodeと を上書きします。

この情報を報告するために、デバイスは更新されたステータス情報をクラウドに発行できます。次に、 GetCommandExecution API を使用してコマンド実行ステータスを取得すると、最新のステータスコードが表示されます。

{
    "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 を使用する際の考慮事項を以下に示します。

コマンド実行を一覧表示する例

次の例は、 でコマンド実行を一覧表示する方法を示しています 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"
        }
    ]
}

コマンド実行を削除する

コマンド実行が不要になった場合は、アカウントから完全に削除できます。

次の例は、 コマンドを使用してdelete-command-execution AWS CLI コマンド実行を削除する方法を示しています。を削除するコマンド実行の識別子<execution-id>に置き換えます。

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

API リクエストが成功すると、コマンド実行は 200 のステータスコードを生成します。GetCommandExecution API を使用して、コマンド実行がアカウントに存在しなくなったことを確認できます。