翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# コマンド実行を開始およびモニタリングする
**重要**
現在、特定の AWS IoT FleetWise 機能へのアクセスはゲートされています。詳細については、「[AWS AWS IoT FleetWise でのリージョンと機能の可用性](fleetwise-regions.md)」を参照してください。
コマンドリソースを作成したら、ターゲット車両でコマンド実行を開始できます。車両がコマンドの実行を開始すると、コマンド実行の結果の更新を開始し、ステータスの更新と結果情報を MQTT 予約済みトピックに発行できます。その後、コマンド実行のステータスを取得し、アカウントでの実行のステータスをモニタリングすることができます。
このトピックでは、 AWS CLI または 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. [**Run command**] を選択してください。
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`として を使用してコマンドを作成し、 AWS IoT FleetWise でコマンドを作成および実行するアクセス許可を付与`role-Arn`する を指定する必要があります。詳細については、「[コマンドリソースを作成する](create-manage-remote-command-cli.md#create-remote-command-cli)」を参照してください。
+ コマンドの作成時にパラメータに指定されたデフォルト値を使用する場合は、 `parameters`フィールドをスキップできます。が作成時に指定`mandatory-parameters`されていない場合、またはパラメータに独自の値を指定してデフォルト値を上書きする場合は、 `parameters`フィールドを指定する必要があります。これらのその他の例については、「」を参照してください[コマンドの使用シナリオ](remote-command-use-cases.md)。
+ `mandatory-parameters` フィールドに最大 3 つの名前と値のペアを指定できます。ただし、車両で コマンドを実行する場合、1 つの名前と値のペアのみが受け入れられ、 `name`フィールドは`$actuatorPath.`プレフィックスで完全修飾名を使用する必要があります。
### アカウント固有のデータプレーンエンドポイントを取得する
API コマンドを実行する前に、エンドポイントのアカウント固有の`iot:Jobs`エンドポイント URL を取得する必要があります。たとえば、次のコマンドを実行するとします。
```
aws iot describe-endpoint --endpoint-type iot:Jobs
```
以下のレスポンスの例に示すように、アカウント固有のエンドポイント URL が返されます。
```
{
"endpointAddress": ".jobs.iot..amazonaws.com"
}
```
### コマンドの例を送信する
車両にコマンドを送信するには、次のコマンドを実行します。
+ *command-arn* を、実行するコマンドの ARN に置き換えます。この情報は、`create-command` CLI コマンドのレスポンスから取得できます。
+ *target-arn* を、コマンドを実行するターゲットデバイスの ARN または AWS IoT モノに置き換えます。
**注記**
AWS IoT モノ (AWS IoT FleetWise 車両) のターゲット ARN を指定できます。モノのグループとフリートは現在サポートされていません。
+ *endpoint-url* を、 で取得したアカウント固有のエンドポイントに置き換えます。`https://`たとえば[アカウント固有のデータプレーンエンドポイントを取得する](#send-remote-command-endpoint)、 というプレフィックスが付きます`https://123456789012abcd.jobs.iot.ap-south-1.amazonaws.com`。
+ name **と *value* を、 CLI `create-command` を使用してコマンドを作成したときに指定した `mandatory-parameters`フィールドに置き換えます。
`name` フィールドは、 をプレフィックス`$actuatorPath.`とするシグナルカタログで定義されている完全修飾名です。たとえば、 `name`は *\$1actuatorPath.Vehicle.Chassis.SteeringWheel.HandsOff.HandsOffSteeringMode* にすることができ、*\$1"B": false\$1* のようなステアリングモードのステータスを示すブール値`value`にすることができます。
+ (オプション) 追加のパラメータ を指定することもできます`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 が呼び出された時刻に対応します。は、 `StartCommandExecution` API を呼び出すときに `executionTimeoutSeconds`パラメータを使用して設定されたタイムアウト値`timeout_ms`に対応します。
```
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 に置き換えます。この情報は、`start-command-execution` CLI コマンドのレスポンスから取得できます。
+ *target-arn* を、コマンドを実行するターゲット車両の ARN または AWS IoT モノに置き換えます。
```
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 を使用してコマンド実行ステータスを取得すると、最新のステータスコードが表示されます。
**注記**
実行レスポンスの `completedAt` フィールドは、デバイスが終了ステータスをクラウドに報告する時間に対応します。`TIMED_OUT` ステータスの場合、このフィールドはデバイスがタイムアウトを報告した場合にのみ設定されます。`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 は過去 6 か月以内に作成または完了したすべての実行を一覧表示します。
+ `sort-order` パラメータを使用して、実行を昇順で一覧表示するかどうかを指定できます。デフォルトでは、このフィールドを指定しない場合、実行は降順に表示されます。
+ コマンド ARN のコマンド実行を一覧表示するときに、ステータスに基づいてコマンド実行をフィルタリングすることはできません。
### コマンド実行を一覧表示する例
次の例は、 AWS アカウントのコマンド実行を一覧表示する方法を示しています。
コマンドを実行するときは、リストをフィルタリングして、`targetArn` を使用して特定のデバイスに対して作成されたコマンド実行のみを表示するか、`commandArn` を使用して指定された特定のコマンドの実行のみを表示するかを指定する必要があります。
この例では、次のように置き換えます。
+ *``* を、`arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f` などの、実行のターゲットとするデバイスの Amazon リソース番号 (ARN) に置き換えます。
+ *``* を、`arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f` などの、実行のターゲットとするデバイスの Amazon リソース番号 (ARN) に置き換えます。
+ *``* は、特定の日時以降に作成された実行を一覧表示する場合の日時に置き換えます。たとえば、`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 を使用して、コマンド実行がアカウントに存在していないことを確認できます。