翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# コマンド
**重要**
現在、特定の AWS IoT FleetWise 機能へのアクセスはゲートされています。詳細については、「[AWS AWS IoT FleetWise でのリージョンと機能の可用性](fleetwise-regions.md)」を参照してください。
このドキュメントでは、[AWS IoT FleetWise のコマンド機能](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-command-concepts-states.html#commands-iotfw-namespace)を使用する方法について説明します。でコマンド機能を使用する方法については AWS IoT Device Management、[「 コマンド](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command.html)」を参照してください。
お客様は、安全かつ適用法に準拠した方法でコマンドをデプロイすることに全責任を負います。お客様の責任に関する詳細については、[AWS IoT サービスのAWS サービス規約](https://aws.amazon.com/service-terms/)をご覧ください。
コマンド機能を使用して、クラウドから車両でコマンドを実行します。コマンドは一度に 1 つのデバイスを対象とし、デバイス側のログの取得や、デバイスの状態の変更開始など、低レイテンシーで高スループットの用途に使用できます。
*コマンド*は、 によって管理されるリソースです AWS IoT Device Management。これには、車両にコマンド実行を送信するときに適用される再利用可能な設定が含まれています。特定のユースケースの一連のコマンドを事前定義することも、それらを使用して繰り返しのユースケースの再利用可能な設定を作成することもできます。たとえば、車両のドアをロックしたり、温度をリモートで変更したりするために、アプリで使用できるコマンドを設定できます。
AWS IoT コマンド機能を使用すると、次のことができます。
+ コマンドリソースを作成し、設定を再利用して複数のコマンドをターゲットデバイスに送信し、デバイスで実行します。
+ 各コマンドをデバイスで実行する粒度を制御します。たとえば、車両を AWS IoT モノとしてプロビジョニングし、車両のドアをロックまたはロック解除するコマンドを送信できます。
+ 前のコマンドが完了するのを待たずに、ターゲットデバイスで複数のコマンドを同時に実行します。
+ コマンドイベントの通知を有効にし、コマンドの実行時と完了時にデバイスからステータスと結果情報を取得します。
以下のトピックでは、コマンドを作成、送信、受信、管理する方法について説明します。
**Topics**
+ [コマンドの概念](remote-command-concepts-states.md)
+ [車両とコマンド](remote-command-vehicles.md)
+ [コマンドの作成と管理](create-manage-remote-command-cli.md)
+ [コマンド実行を開始およびモニタリングする](send-monitor-remote-command-cli.md)
+ [例: コマンドを使用して車両のステアリングモードを制御する (AWS CLI)](remote-command-tutorial.md)
+ [コマンドの使用シナリオ](remote-command-use-cases.md)
# コマンドの概念
**重要**
現在、特定の AWS IoT FleetWise 機能へのアクセスはゲートされています。詳細については、「[AWS AWS IoT FleetWise でのリージョンと機能の可用性](fleetwise-regions.md)」を参照してください。
コマンドは、クラウドからターゲットデバイスに送信される手順です。ターゲットデバイスは車両にすることができ、*AWS IoT モノ*レジストリにモノとして登録する必要があります。コマンドには、車両のアクチュエータが実行する必要があるアクションを定義するパラメータを含めることができます。その後、車両はコマンドとそのパラメータを解析し、それらを処理して対応するアクションを実行します。その後、コマンド実行のステータスでクラウドアプリケーションに応答します。
詳細なワークフローについては、「」を参照してください[車両とコマンド](remote-command-vehicles.md)。
**Topics**
+ [コマンドキーの概念](#remote-command-concepts)
+ [コマンド実行ステータス](#remote-command-execution-status-codes)
## コマンドキーの概念
コマンド機能を使用するためのいくつかの重要な概念と、それが最後の既知の状態 (LKS) 状態テンプレートとどのように連携するかを以下に示します。
**コマンド**
コマンドは、エンジンをオンにしたり、ウィンドウの位置を変更したりするなどのアクションを実行するために、物理的な車両に指示を送信するために使用できるエンティティです。特定のユースケースの一連のコマンドを事前定義することも、それらを使用して繰り返しのユースケースの再利用可能な設定を作成することもできます。たとえば、車両のドアをロックしたり、温度をリモートで変更したりするために、アプリで使用できるコマンドを設定できます。
**名前空間**
コマンド機能を使用する場合は、コマンドの名前空間を指定する必要があります。 AWS IoT FleetWise でコマンドを作成するときは、名前空間`AWS-IoT-FleetWise`として を選択する必要があります。この名前空間を使用する場合は、車両でコマンドを実行するために使用されるパラメータを指定する必要があります。 AWS IoT Device Management 代わりに でコマンドを作成する場合は、代わりに `AWS-IoT`名前空間を使用する必要があります。詳細については、「 デ*AWS IoT Device Management ベロッパーガイド*」の[「 コマンド](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command.html)」を参照してください。
**コマンドの状態**
作成するコマンドは使用可能な状態になります。つまり、車両でコマンド実行を開始するために使用できます。コマンドが古くなった場合は、そのコマンドを非推奨にすることができます。非推奨状態のコマンドの場合、既存のコマンド実行は完了するまで実行されます。コマンドを更新したり、新しい実行を実行したりすることはできません。新しく実行を送信するには、コマンドを復元して使用可能にする必要があります。
コマンドが不要になった場合は削除することもできます。コマンドを削除対象としてマークすると、コマンドが最大タイムアウトの 24 時間より長い期間非推奨になっている場合、コマンドはすぐに削除されます。コマンドが非推奨になっていない場合、または非推奨状態にある期間が最大タイムアウト期間より短い場合、そのコマンドは [保留中の削除] の状態になります。コマンドは 24 時間後にアカウントから自動的に削除されます。
**パラメータ**
コマンドを作成するときは、オプションで、コマンドの実行時にターゲット車両が実行するパラメータを指定できます。作成するコマンドは再利用可能な設定であり、複数のコマンド実行を車両に送信して同時に実行するために使用できます。または、実行時にのみパラメータを指定し、コマンドを作成して車両に送信するワンタイムオペレーションを実行することもできます。
**ターゲット車両**
コマンドを実行する場合は、コマンドを受信して特定のアクションを実行するターゲット車両を指定する必要があります。ターゲット車両はすでに*モノ*として登録されている必要があります AWS IoT。コマンドを車両に送信すると、指定したパラメータと値に基づいてコマンドのインスタンスの実行が開始されます。
**アクチュエータ**
コマンドを実行する場合は、コマンドを受信する車両のアクチュエータと、実行するアクションを決定する値を指定する必要があります。オプションでアクチュエータのデフォルト値を設定して、不正確なコマンドを送信しないようにできます。たとえば、コマンドが誤ってドアのロックを解除しないように、ドアロックアクチュエータ`LockDoor`にデフォルト値の を使用できます。アクチュエータの一般的な情報については、「」を参照してください[主要なコンセプト](how-iotfleetwise-works.md#key-concepts)。
**データ型サポート**
コマンド機能に使用されるアクチュエータでは、次のデータ型がサポートされています。
配列は、テレマティクスデータ、コマンド、または最後の既知の状態 (LKS) ではサポートされていません。配列データ型は、ビジョンシステムデータにのみ使用できます。
+ 浮動小数点タイプ。次のタイプがサポートされます。
+ 浮動小数点数 (32 ビット)
+ ダブル (64 ビット)
+ 整数 (署名付きと署名なしの両方）。次の整数型がサポートされています。
+ int8 および uint8
+ int16 および uint16
+ int32 および uint32
+ ロング。次のロングタイプがサポートされています。
+ ロング (int64)
+ 符号なしロング (uint64)
+ String
+ ブール値
**コマンドの実行**
コマンド実行は、ターゲットデバイスで実行されるコマンドのインスタンスです。車両は、コマンドの作成時またはコマンド実行の開始時に指定したパラメータを使用してコマンドを実行します。その後、車両は指定されたオペレーションを実行し、実行のステータスを返します。
特定の車両に対して、複数のコマンドを同時に実行できます。各車両に対して実行できる同時実行の最大数については、[AWS IoT Device Management 「 コマンドクォータ](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#commands-limits)」を参照してください。
**Last known state (LKS) 状態テンプレート**
状態テンプレートは、車両所有者が車両の状態を追跡するメカニズムを提供します。車両の最後の既知の状態 (LKS) をほぼリアルタイムでモニタリングするには、状態テンプレートを作成して車両に関連付けることができます。
コマンド機能を使用すると、状態データの収集と処理に使用できる「オンデマンド」オペレーションを実行できます。たとえば、現在の車両状態を 1 回リクエスト (フェッチ) したり、以前にデプロイされた LKS 状態テンプレートをアクティブ化または非アクティブ化して、車両データのレポートを開始または停止したりできます。状態テンプレートでコマンドを使用する方法を示す例については、「」を参照してください[コマンドの使用シナリオ](remote-command-use-cases.md)。
## コマンド実行ステータス
コマンド実行を開始すると、車両は実行のステータスを発行し、実行に関する追加情報としてステータスの理由を指定できます。以下のセクションでは、さまざまなコマンド実行ステータスとステータスコードについて説明します。
**Topics**
+ [コマンド実行ステータスの理由コードと説明](#remote-command-execution-status-reason-codes)
+ [コマンド実行ステータスとステータスコード](#remote-command-execution-status-codes)
+ [コマンド実行のタイムアウトステータス](#remote-command-execution-status-timeout)
### コマンド実行ステータスの理由コードと説明
コマンド実行ステータスの更新を報告するには、 *AWS IoT Core デベロッパーガイド*で説明されている [コマンド予約トピック](https://docs.aws.amazon.com/iot/latest/developerguide/reserved-topics.html#reserved-topics-commands)を使用して、車両は `UpdateCommandExecution` API を使用して更新されたステータス情報をクラウドに発行できます。ステータス情報をレポートする場合、デバイスは、 `StatusReason` オブジェクトを使用して各コマンド実行のステータス、および オブジェクト`reasonDescription`に含まれるフィールド`reasonCode`と に関する追加のコンテキストを提供できます。
### コマンド実行ステータスとステータスコード
次の表は、さまざまなコマンド実行ステータスコードと、コマンド実行が移行できる許可されたステータスを示しています。また、コマンド実行が「終了」かどうか (つまり、それ以上のステータスの更新は予定されていない）、変更が車両またはクラウドによって開始されたかどうか、さまざまな事前定義されたステータスコード、およびそれらがクラウドによって報告されたステータスにどのようにマッピングされるかも表示されます。
+ が事前定義されたステータスコードと `statusReason` オブジェクト AWS IoT FleetWise を使用する方法については、*「 Edge Agent for AWS IoT FleetWise ソフトウェアドキュメント*」の[「コマンドステータス](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/include/aws/iotfleetwise/ICommandDispatcher.h)」を参照してください。
+ ターミナル実行と非ターミナル実行、およびステータス間の遷移の詳細については、「 デ*AWS IoT Core ベロッパーガイド*」の[「コマンド実行ステータス](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command-concepts.html#iot-command-execution-status)」を参照してください。
**コマンド実行のステータスと開始元**
| コマンド実行ステータス | 説明 | 開始元はデバイスかクラウドか | 実行の終了かどうか | 許可されたステータスの移行 | 事前定義されたステータスコード |
| --- | --- | --- | --- | --- | --- |
| CREATED | コマンドの実行を開始する API リクエスト (StartCommandExecution API) が成功すると、コマンドの実行ステータスは に変わりますCREATED。 | Cloud | いいえ | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/iot-fleetwise/latest/developerguide/remote-command-concepts-states.html) | なし |
| IN\$1PROGRESS | 車両がコマンドの実行を開始すると、レスポンストピックにメッセージを発行してステータスを に更新できますIN\$1PROGRESS。 | デバイス | いいえ | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/iot-fleetwise/latest/developerguide/remote-command-concepts-states.html) | COMMAND\$1STATUS\$1COMMAND\$1IN\$1PROGRESS |
| SUCCEEDED | 車両がコマンドを正常に処理し、実行を完了すると、レスポンストピックにメッセージを発行してステータスを に更新できますSUCCEEDED。 | デバイス | はい | 該当しない | COMMAND\$1STATUS\$1SUCCEEDED |
| FAILED | 車両がコマンドの実行に失敗すると、レスポンストピックにメッセージを発行してステータスを に更新できますFAILED。 | デバイス | はい | 該当しない | COMMAND\$1STATUS\$1EXECUTION\$1FAILED |
| REJECTED | 車両がコマンドの受け入れに失敗した場合、レスポンストピックにメッセージを発行してステータスを に更新できますREJECTED。 | デバイス | はい | 該当しない | なし |
| TIMED\$1OUT | コマンドの実行ステータスは、次のいずれか`TIMED_OUT`の理由で に変わる可能性があります。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/iot-fleetwise/latest/developerguide/remote-command-concepts-states.html) このステータスの詳細については、「」を参照してください[コマンド実行のタイムアウトステータス](#remote-command-execution-status-timeout)。 | デバイスとクラウド | いいえ | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/iot-fleetwise/latest/developerguide/remote-command-concepts-states.html) | COMMAND\$1STATUS\$1EXECUTION\$1TIMEOUT |
### コマンド実行のタイムアウトステータス
コマンド実行タイムアウトは、クラウドとデバイスの両方で報告できます。コマンドがデバイスに送信されると、タイマーが開始されます。指定した期間内にデバイスから応答を受信しなかった場合、クラウドは`TIMED_OUT`ステータスを報告します。この場合、 `TIMED_OUT`ステータスのコマンド実行は非ターミナルです。
デバイスは、このステータスを 、、 `SUCCEEDED` `FAILED`などのターミナルステータスに上書きできます`REJECTED`。コマンドの実行時にタイムアウトが発生したことを報告することもできます。この場合、コマンドの実行ステータスは のまま`TIMED_OUT`ですが、`StatusReason`オブジェクトのフィールドはデバイスによって報告された情報に基づいて更新されます。`TIMED_OUT` ステータスのコマンド実行がターミナルになりました。
詳細については、 デ*AWS IoT Core ベロッパーガイド*の[「コマンド実行タイムアウトに関する考慮事項](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command-execution-start-monitor.html#iot-command-execution-timeout)」を参照してください。
# 車両とコマンド
**重要**
現在、特定の AWS IoT FleetWise 機能へのアクセスはゲートされています。詳細については、「[AWS AWS IoT FleetWise でのリージョンと機能の可用性](fleetwise-regions.md)」を参照してください。
お客様は、安全かつ適用法に準拠した方法でコマンドをデプロイすることに全責任を負います。
コマンド機能を使用するには:
1. まず、コマンドリソースを作成します。必要に応じて、コマンドの実行に必要な情報を含むパラメータを指定します。
1. コマンドを受け取り、指定されたアクションを実行するターゲット車両を指定します。
1. これで、ターゲットデバイスで コマンドを実行し、コマンド実行の詳細を確認してステータスを取得し、CloudWatch ログを使用して問題のトラブルシューティングをさらに行うことができます。
以下のセクションでは、車両とコマンド間のワークフローを示します。
**Topics**
+ [ワークフローの概要](#remote-command-vehicles-overview)
+ [車両ワークフロー](#iot-remote-command-devices-workflow)
+ [コマンドワークフロー](#iot-remote-command-commands-workflow)
+ [(オプション) コマンド通知](#remote-command-notifications)
## ワークフローの概要
次の手順では、車両とコマンド間のコマンドワークフローの概要を示します。コマンド HTTP API オペレーションのいずれかを使用すると、リクエストは Sigv4 認証情報を使用して署名されます。
**注記**
`StartCommandExecution` API オペレーションを除き、HTTP プロトコルで実行されるすべてのオペレーションはコントロールプレーンエンドポイントを使用します。
1.
**MQTT 接続を確立し、コマンドトピックをサブスクライブする**
コマンドワークフローを準備するには、デバイスは`iot:Data-ATS`エンドポイントとの MQTT 接続を確立し、上記のコマンドリクエストトピックをサブスクライブする必要があります。オプションで、デバイスは受け入れられた応答トピックと拒否された応答トピックをサブスクライブすることもできます。
1.
**車両モデルとコマンドリソースを作成する**
および `CreateCommand`コントロールプレーン API オペレーションを使用して、車両`CreateVehicle`とコマンドリソースを作成できるようになりました。コマンドリソースには、車両でコマンドが実行されたときに適用される設定が含まれています。
1.
**ターゲットデバイスでコマンド実行を開始する**
アカウント固有の`iot:Jobs`エンドポイントで`StartCommandExecution`データプレーン API を使用して、車両でコマンド実行を開始します。API は、protobuf エンコードされたペイロードメッセージをコマンドリクエストトピックに発行します。
1.
**コマンド実行の結果を更新する**
車両はコマンドと受信したペイロードを処理し、`UpdateCommandExecution`API を使用してコマンド実行の結果をレスポンストピックに発行します。車両が応答トピックを受け入れたコマンドと拒否したコマンドをサブスクライブしている場合、応答がクラウドサービスによって受け入れられたか拒否されたかを示すメッセージが表示されます。
1.
**(オプション) コマンド実行結果を取得する**
コマンド実行の結果を取得するには、`GetCommandExecution`コントロールプレーン API オペレーションを使用できます。車両がコマンド実行結果をレスポンストピックに発行すると、この API は更新された情報を返します。
1.
**(オプション) コマンドイベントのサブスクライブと管理**
コマンド実行ステータスの更新に関する通知を受け取るには、 コマンドイベントトピックをサブスクライブします。その後、`CreateTopicRule`コントロールプレーン API を使用して、コマンドイベントデータを AWS Lambda 関数や Amazon SQS などの他のアプリケーションにルーティングし、その上にアプリケーションを構築できます。
## 車両ワークフロー
次の手順では、 コマンド機能を使用する際の車両のワークフローについて詳しく説明します。
**注記**
このセクションで説明するオペレーションでは、MQTT プロトコルを使用します。
1.
**MQTT 接続を確立する**
コマンド機能を使用するように車両を準備するには、まず AWS IoT Core メッセージブローカーに接続する必要があります。車両は、 メッセージブローカーに接続 AWS IoT Core して MQTT 接続を確立する `iot:Connect`アクションを実行することを許可されている必要があります。のデータプレーンエンドポイントを検索するには AWS アカウント、次に示すように `DescribeEndpoint` API または `describe-endpoint` CLI コマンドを使用します。
```
aws iot describe-endpoint --endpoint-type iot:Data-ATS
```
このコマンドを実行すると、以下に示すように、アカウント固有のデータプレーンエンドポイントが返されます。
```
account-specific-prefix.iot.region.amazonaws.com
```
1.
**Susbcribe to commands リクエストトピック**
接続が確立されると、デバイスは AWS IoT コマンド MQTT リクエストトピックにサブスクライブできます。コマンドを作成してターゲットデバイスでコマンド実行を開始すると、メッセージブローカーによって protobuf エンコードされたペイロードメッセージがリクエストトピックに発行されます。その後、デバイスはペイロードメッセージを受信し、コマンドを処理することができます。この例では、 をターゲット車両の一意の識別子*``*に置き換えます。この ID は、車両の一意の識別子またはモノの名前にすることができます。
**注記**
デバイスに送信するペイロードメッセージは、protobuf 形式を使用する必要があります。
```
$aws/commands/things//executions/+/request/protobuf
```
1.
**(オプション) コマンドレスポンストピックをサブスクライブする**
必要に応じて、これらのコマンドレスポンストピックをサブスクライブして、クラウドサービスがデバイスからのレスポンスを承諾したか拒否したかを示すメッセージを受信できます。
**注記**
車両が `/accepted`および `/rejected`レスポンストピックをサブスクライブすることはオプションです。車両は、これらのトピックに明示的にサブスクライブしていない場合でも、これらのレスポンスメッセージを自動的に受信します。
```
$aws/commands/things//executions//response/protobuf/accepted
$aws/commands/things//executions//response/protobuf/rejected
```
1.
**コマンド実行の結果を更新する**
その後、ターゲット車両は コマンドを処理します。次に、 `UpdateCommandExecution` API を使用して、実行の結果を次の MQTT レスポンストピックに発行します。
**注記**
特定の車両とコマンドの実行の場合、** は、デバイスがサブスクライブしたリクエストトピックの対応するフィールドと一致する必要があります。
```
$aws/commands/things//executions//response/protobuf
```
`UpdateCommandExecution` API は、TLS で認証された MQTT に対するデータプレーン API オペレーションです。
+ クラウドサービスがコマンド実行結果を正常に処理すると、MQTT が承諾したトピックにメッセージが発行されます。受け入れられたトピックは次の形式を使用します。
```
$aws/commands/things//executions//response/protobuf/accepted
```
+ クラウドサービスがコマンド実行結果を処理できなかった場合、MQTT 拒否トピックにレスポンスが発行されます。拒否されたトピックは次の形式を使用します。
```
$aws/commands/things//executions//response/protobuf/rejected
```
この API の詳細と例については、「」を参照してください[コマンド実行結果を更新する](send-monitor-remote-command-cli.md#update-remote-command-execution-cli)。
## コマンドワークフロー
次の手順では、コマンドワークフローについて詳しく説明します。
**注記**
このセクションで説明するオペレーションでは、HTTP プロトコルを使用します。
1.
**車両を登録する**
これで、 コマンド機能を使用するように車両を準備できたので、車両を登録し、車両に送信されるコマンドを作成することで、アプリケーションを準備できます。車両を登録するには、[https://docs.aws.amazon.com/iot-fleetwise/latest/APIReference/API_CreateVehicle.html](https://docs.aws.amazon.com/iot-fleetwise/latest/APIReference/API_CreateVehicle.html)コントロールプレーン API オペレーションを使用して車両モデル (モデルマニフェスト) のインスタンスを作成します。詳細と例については、[「車両の作成](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/create-vehicle.html)」を参照してください。
1.
**コマンドを作成する**
HTTP コントロールプレーン API [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html) オペレーションを使用して、ターゲットとする車両に適用されるコマンドをモデル化します。コマンドの実行時に使用するパラメータとデフォルト値を指定し、必ず `AWS-IoT-FleetWise`名前空間を使用してください。この API の使用に関する詳細と例については、「」を参照してください[コマンドリソースを作成する](create-manage-remote-command-cli.md#create-remote-command-cli)。
1.
**コマンド実行を開始する**
[https://docs.aws.amazon.com/iot/latest/apireference/API_iotdata_StartCommandExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iotdata_StartCommandExecution.html) データプレーン API オペレーションを使用して、車両で作成したコマンドを実行できるようになりました。 AWS IoT Device Management はコマンドとコマンドパラメータを取得し、受信リクエストを検証します。次に、必要なパラメータを使用して AWS IoT FleetWise API を呼び出し、車両固有のペイロードを生成します。その後、ペイロードは MQTT AWS IoT Device Management 経由でデバイスがサブスクライブしたコマンドリクエストトピックにデバイスに送信されます。この API の使用に関する詳細と例については、「」を参照してください[コマンドを送信する (AWS CLI)](send-monitor-remote-command-cli.md#send-remote-command-cli)。
```
$aws/commands/things//executions/+/request/protobuf
```
**注記**
コマンドがクラウドから送信され、MQTT 永続セッションが使用中のときにデバイスがオフラインだった場合、コマンドはメッセージブローカーで待機します。デバイスがタイムアウト時間前にオンラインに戻り、コマンドリクエストトピックをサブスクライブしている場合、デバイスはコマンドを処理し、結果をレスポンストピックに発行できます。タイムアウト時間前にデバイスがオンラインに戻らない場合、コマンドの実行はタイムアウトし、ペイロードメッセージは期限切れになります。
1.
**コマンド実行を取得する**
デバイスで コマンドを実行したら、[https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommandExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommandExecution.html)コントロールプレーン API オペレーションを使用して、コマンド実行の結果を取得してモニタリングします。API を使用して、最後に更新された日時、実行が完了した日時、指定されたパラメータなど、実行データに関する追加情報を取得することもできます。
**注記**
最新のステータス情報を取得するには、デバイスがコマンド実行結果をレスポンストピックに公開している必要があります。
この API の詳細と使用例については、「」を参照してください[コマンド実行の取得](send-monitor-remote-command-cli.md#get-remote-command-execution-cli)。
## (オプション) コマンド通知
コマンドイベントにサブスクライブして、コマンド実行のステータスが変更されたときに通知を受け取ることができます。次の手順は、コマンドイベントにサブスクライブして処理する方法を示しています。
1.
**トピックルールを作成する**
コマンドイベントトピックにサブスクライブして、コマンド実行のステータスが変更されたときに通知を受け取ることができます。トピックルールを作成して、車両によって処理されたデータを AWS Lambda 関数などの他のアプリケーションにルーティングすることもできます。トピックルールは、 AWS IoT コンソールまたは[https://docs.aws.amazon.com/iot/latest/apireference/API_CreateTopicRule.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateTopicRule.html) AWS IoT Core コントロールプレーン API オペレーションを使用して作成できます。詳細については、[「Creating and AWS IoT rule](https://docs.aws.amazon.com/iot/latest/developerguide/iot-create-rule.html)」を参照してください。
この例では、`` を通知を受信するコマンドの識別子に置き換え、`` をコマンド実行のステータスに置き換えます。
```
$aws/events/commandExecution//
```
**注記**
すべてのコマンドとコマンド実行ステータスの通知を受け取るには、ワイルドカード文字を使用し、次のトピックにサブスクライブします。
```
$aws/events/commandExecution/+/#
```
1.
**コマンドイベントを受信して処理する**
前のステップでコマンドイベントをサブスクライブするトピックルールを作成した場合は、受信したコマンドプッシュ通知を管理できます。オプションで、作成したトピックルールを使用して、Amazon SQS AWS Lambda、Amazon SNS、 AWS Step Functions などのアプリケーションを構築することもできます。
次のコードは、受信するコマンドイベント通知のサンプルペイロードを示しています。
```
{
"executionId": "2bd65c51-4cfd-49e4-9310-d5cbfdbc8554",
"status":"FAILED",
"statusReason": {
"reasonCode": "4",
"reasonDescription": ""
},
"eventType": "COMMAND_EXECUTION",
"commandArn":"arn:aws:iot:us-east-1:123456789012:command/0b9d9ddf-e873-43a9-8e2c-9fe004a90086",
"targetArn":"arn:aws:iot:us-east-1:123456789012:thing/5006c3fc-de96-4def-8427-7eee36c6f2bd",
"timestamp":1717708862107
}
```
# コマンドの作成と管理
**重要**
現在、特定の AWS IoT FleetWise 機能へのアクセスはゲートされています。詳細については、「[AWS AWS IoT FleetWise でのリージョンと機能の可用性](fleetwise-regions.md)」を参照してください。
再利用可能なリモートアクションを設定するか、デバイスに 1 回限りの即時の指示を送信できます。この機能を使用すると、デバイスがほぼリアルタイムで実行できる手順を指定できます。コマンドを使用すると、ターゲット車両の再利用可能なリモートアクションを設定できます。コマンドを作成したら、特定の車両を対象とするコマンド実行を開始できます。
このトピックでは、 AWS IoT Core API または を使用してコマンドリソースを作成および管理する方法を示します AWS CLI。コマンドリソースで次のアクションを実行する方法を示します。
**Topics**
+ [コマンドリソースを作成する](#create-remote-command-cli)
+ [コマンドに関する情報を取得する](#get-remote-command-cli)
+ [アカウントのコマンドを一覧表示する](#list-remote-command-cli)
+ [コマンドリソースを更新または廃止する](#update-remote-command-cli)
+ [コマンドリソースを削除する](#delete-remote-command-cli)
## コマンドリソースを作成する
[https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html) AWS IoT Core コントロールプレーン API オペレーションまたは AWS IoT FleetWise コンソールを使用してコマンドを作成できます。
### コマンドを作成する (コンソール)
AWS IoT FleetWise コンソールを使用してコマンドを作成できます。
**コマンドを作成するには**
1. [AWS IoT FleetWise コンソール](https://console.aws.amazon.com/iotfleetwise)を開きます。
1. ナビゲーションペインで、 **コマンド**を選択します。
1. **[コマンドを作成]** を選択します。
1. 車両で実行するコマンドを識別するのに役立つ一意のコマンド ID を指定します。
1. (オプション) オプションの表示名と説明を指定します。
1. (オプション) アクチュエータとデフォルトのパラメータ値を選択します。パラメータは、ターゲット車両がコマンドを受信したときに実行できるアクションを指定します。パラメータを追加しない場合は、コマンドの実行時にパラメータを指定する必要があります。
1. コマンドのペイロードを生成するアクセス許可を付与する IAM ロールを選択します。[「アクセスの制御](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/controlling-access.html#generate-command-payload)」を参照してください。
1. **[コマンドを作成]** を選択します。
### コマンドを作成する (AWS CLI)
次の例は、 パラメータを使用してコマンドを作成する方法を示しています。
#### コマンドを作成する際の考慮事項
でコマンドを作成する場合 AWS IoT FleetWise:
+ 車両でコマンドを作成および実行するアクセス許可を付与`roleArn`する を指定する必要があります。KMS キーが有効な場合など、ポリシーの例の詳細については、「」を参照してください[を使用してコマンドのペイロードを生成する AWS IoT Device Management アクセス許可を付与する AWS IoT FleetWise](controlling-access.md#generate-command-payload)。
+ 名前空間`AWS-IoT-FleetWise`として を指定する必要があります。
+ 代わりに、 `mandatory-parameters`フィールドをスキップして実行時に指定できます。または、パラメータを使用してコマンドを作成し、オプションでデフォルト値を指定することもできます。デフォルト値を指定した場合、実行時にこれらの値を使用するか、独自の値を指定して上書きできます。これらのその他の例については、「」を参照してください[コマンドの使用シナリオ](remote-command-use-cases.md)。
+ `mandatory-parameters` フィールドに最大 3 つの名前と値のペアを指定できます。ただし、車両で コマンドを実行する場合、1 つの名前と値のペアのみが受け入れられ、 `name`フィールドは`$actuatorPath.`プレフィックスで完全修飾名を使用する必要があります。
+ *command-id* をコマンドの一意の識別子に置き換えます。UUID、英数字、「-」、「\$1」を使用できます。
+ *role-arn* を、 などのコマンドを作成および実行するアクセス許可を付与する IAM ロールに置き換えます`"arn:aws:iam:accountId:role/FwCommandExecutionRole"`。
+ (オプション) *display-name* をコマンドのわかりやすい名前に置き換え、 *description* をコマンドのわかりやすい説明に置き換えます。
+ `mandatory-parameters` オブジェクト*の名前*と*値を*、作成するコマンドの必要な情報に置き換えます。`name` フィールドは、 をプレフィックス`$actuatorPath.`とするシグナルカタログで定義されている完全修飾名です。たとえば、 `name`は *\$1actuatorPath.Vehicle.Chassis.SteeringWheel.HandsOff.HandsOffSteeringMode* にすることができ、*\$1"B": false\$1* のようなステアリングモードのステータスを示すブール値`value`にすることができます。
```
aws iot create-command --command-id command-id \
--role-arn role-arn \
--description description \
--display-name display-name \
--namespace "AWS-IoT-FleetWise" \
--mandatory-parameters '[
{
"name": name,
"value": value
}
]'
```
`CreateCommand` API オペレーションは、 コマンドの ID と ARN (Amazon リソースネーム) を含むレスポンスを返します。
```
{
"commandId": "HandsOffSteeringMode",
"commandArn": "arn:aws:iot:ap-south-1:123456789012:command/HandsOffSteeringMode"
}
```
## コマンドに関する情報を取得する
[https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommand.html) AWS IoT Core コントロールプレーン API オペレーションを使用して、コマンドリソースに関する情報を取得できます。
コマンドリソースに関する情報を取得するには、次のコマンドを実行します。*command-id* を、コマンドの作成時に使用された識別子に置き換えます。
```
aws iot get-command --command-id command-id
```
`GetCommand` API オペレーションは、以下の情報を含むレスポンスを返します。
+ コマンドの ID と ARN (Amazon リソースネーム）。
+ コマンドが作成され、最後に更新された日時。
+ 車両で実行できるかどうかを示すコマンド状態。
+ コマンドの作成時に指定したパラメータ。
```
{
"commandId": "HandsOffSteeringMode",
"commandArn": "arn:aws:iot:ap-south-1:123456789012:command/HandsOffSteeringMode"",
"namespace": "AWS-IoT-FleetWise",
"mandatoryParameters":[
{
"name": "$actuatorPath.Vehicle.Chassis.SteeringWheel.HandsOff.HandsOffSteeringMode",
"value": {"B": false }
}
],
"createdAt": "2024-03-23T11:24:14.919000-07:00",
"lastUpdatedAt": "2024-03-23T11:24:14.919000-07:00",
"deprecated": false,
"pendingDeletion": false
}
```
## アカウントのコマンドを一覧表示する
[https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommands.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommands.html) AWS IoT Core コントロールプレーン API オペレーションを使用して、作成したアカウント内のすべてのコマンドを一覧表示できます。
アカウントのコマンドを一覧表示するには、次のコマンドを実行します。デフォルトでは、API は両方の名前空間用に作成されたコマンドを返します。リストをフィルタリングして、作成されたコマンドのみを表示するには AWS IoT FleetWise、次のコマンドを実行します。
**注記**
リストを昇順または降順にソートしたり、特定のコマンドパラメータ名を持つコマンドのみを表示するようにリストをフィルタリングしたりすることもできます。
```
aws iot list-commands --namespace "AWS-IoT-FleetWise"
```
`ListCommands` API オペレーションは、次の情報を含むレスポンスを返します。
+ コマンドの ID と ARN (Amazon リソースネーム）。
+ コマンドが作成され、最後に更新された日時。
+ コマンドを車両で実行できるかどうかを示すコマンド状態。
## コマンドリソースを更新または廃止する
[https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateCommand.html) AWS IoT Core コントロールプレーン API オペレーションまたは AWS IoT FleetWise コンソールを使用して、コマンドリソースを更新できます。コマンドの表示名と説明を更新できます。コマンドが現在使用されていない場合は、そのコマンドを非推奨にすることもできます。
**注記**
コマンドの実行時に使用する名前空間情報またはパラメータを変更することはできません。
### コマンドを更新する (コンソール)
**コマンドを更新する**
コンソールからコマンドを更新するには、 AWS IoT FleetWise コンソールの[コマンド](https://console.aws.amazon.com/iotfleetwise/home#/commands)ページに移動し、次の手順を実行します。
1. 更新するコマンドを選択し、**編集**を選択します。
1. コマンドの詳細を編集し、**変更の保存**を選択します。
**コマンドを非推奨にする**
コンソールからコマンドを非推奨にするには、 AWS IoT FleetWise コンソールの[コマンド](https://console.aws.amazon.com/iotfleetwise/home#/commands)ページに移動し、次の手順を実行します。
1. 非推奨にするコマンドを選択し、**非推奨**を選択します。
1. 非推奨を確認し、**非推奨**を選択します。
### コマンドを更新する (AWS CLI)
**コマンドを更新する**
コマンドリソースを更新するには、次のコマンドを実行します。*command-id* を更新したいコマンドの識別子に置き換え、更新された *display-name* と*説明*を指定します。
```
aws iot update-command \
--command-id command-id \
--display-name display-name \
--description description
```
`UpdateCommand` API オペレーションは次のレスポンスを返します。
```
{
"commandId": "HandsOffSteeringMode",
"deprecated": false,
"lastUpdatedAt": "2024-05-09T23:16:51.370000-07:00"
}
```
**コマンドを非推奨にする**
コマンドを廃止するのは、デバイスへの使用を停止する場合や、古い場合です。次の例は、コマンドを非推奨にする方法を示しています。
```
aws iot update-command \
--command-id command-id \
--deprecated
```
`UpdateCommand` API オペレーションは、 コマンドの ID と ARN (Amazon リソースネーム) を含むレスポンスを返します。
```
{
"commandId": "HandsOffSteeringMode",
"deprecated": true,
"lastUpdatedAt": "2024-05-09T23:16:51.370000-07:00"
}
```
コマンドが廃止されると、既存のコマンド実行は、終了するまで車両上で実行され続けます。新しいコマンド実行を実行するには、 `UpdateCommand` API を使用してコマンドを復元し、使用可能にする必要があります。コマンドの廃止と復元、およびその考慮事項の詳細については、「 *AWS IoT Core デベロッパーガイド*」の[「コマンドリソースの廃止](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command-deprecate)」を参照してください。
## コマンドリソースを削除する
[https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteCommand.html) AWS IoT Core コントロールプレーン API オペレーションまたは AWS IoT FleetWise コンソールを使用して、コマンドリソースを削除できます。
**注記**
削除の操作は永続的で、元には戻せません。コマンドはアカウントから完全に削除されます。
### コマンドを削除する (コンソール)
コンソールからコマンドを削除するには、 AWS IoT FleetWise コンソールの[コマンド](https://console.aws.amazon.com/iotfleetwise/home#/commands)ページに移動し、次の手順を実行します。
1. 削除するコマンドを選択し、**削除**を選択します。
1. コマンドを削除することを確認し、**削除**を選択します。
### コマンドを削除する (AWS CLI)
コマンドリソースを削除するには、次のコマンドを実行します。*command-id* は、削除するコマンドの識別子に置き換えます。次の例は、コマンドリソースを削除する方法を示しています。
```
aws iot delete-command --command-id command-id
```
削除リクエストが成功した場合:
+ コマンドが最大タイムアウトの 24 時間を超えて非推奨になった場合、コマンドはすぐに削除され、HTTP `statusCode`は 204 になります。
+ コマンドが非推奨になっていない場合、または最大タイムアウトより短い期間非推奨になっている場合、コマンドは `pending deletion`状態になり、HTTP は 202 `statusCode` になります。コマンドは、最大タイムアウトの 24 時間後にアカウントから自動的に削除されます。
# コマンド実行を開始およびモニタリングする
**重要**
現在、特定の 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 を使用して、コマンド実行がアカウントに存在していないことを確認できます。
# 例: コマンドを使用して車両のステアリングモードを制御する (AWS CLI)
**重要**
現在、特定の AWS IoT FleetWise 機能へのアクセスはゲートされています。詳細については、「[AWS AWS IoT FleetWise でのリージョンと機能の可用性](fleetwise-regions.md)」を参照してください。
次の例は、 を使用して コマンド機能を使用する方法を示しています AWS CLI。この例では、 AWS IoT FleetWise 車両をターゲットデバイスとして使用して、ステアリングモードをリモートで制御するコマンドを送信する方法を示します。
**Topics**
+ [車両ステアリングモードの例の概要](#iot-remote-command-tutorial-overview)
+ [前提条件](#iot-remote-command-tutorial-prereq)
+ [リモートコマンドを使用するための IAM ポリシー](#remote-command-policy)
+ [AWS IoT コマンドを実行する (AWS CLI)](#iot-remote-command-tutorial-run)
+ [クリーンアップ](#remote-command-tutorial-clean)
## 車両ステアリングモードの例の概要
この例では、次の操作を行います。
1. を使用して オペレーションのコマンドリソースを作成し`create-command` AWS CLI 、車両のステアリングモードを変更します。
1. を使用して、コマンドが作成された時刻や最後に更新された時刻など、コマンドに関する情報を取得します`get-command` AWS CLI。
1. `start-command-execution` AWS CLI ステアリングモードを必須パラメータとする を使用して、 コマンドを車両に送信します。このパラメータはデバイスで実行されます。
1. を使用してコマンド実行の結果を取得します`get-command-execution` AWS CLI。実行が完了した日時を確認し、実行結果やコマンドの実行完了にかかった時間などの追加の詳細を取得できます。
1. 使用しなくなったコマンドとコマンド実行を削除して、クリーンアップアクティビティを実行します。
## 前提条件
この例を実行する前に:
+ 車両を AWS IoT レジストリの AWS IoT モノ AWS IoT FleetWise としてプロビジョニングします。また、モノに証明書を追加してアクティブ化し、モノにポリシーをアタッチする必要があります。その後、デバイスはクラウドに接続し、コマンドを実行できます。詳細については、[「車両のプロビジョニング](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/provision-vehicles.html)」を参照してください。
+ 「」に示すように、 コマンドを使用して API オペレーションを実行するアクセス許可を付与する IAM ユーザーと IAM ポリシーを作成します[リモートコマンドを使用するための IAM ポリシー](#remote-command-policy)。
## リモートコマンドを使用するための IAM ポリシー
次の表は、 コマンド機能のすべてのコントロールプレーンおよびデータプレーン API オペレーションへのアクセスを許可する IAM ポリシーの例を示しています。アプリケーションのユーザーは、表に示すように、すべてのリモートコマンド API オペレーションを実行するアクセス許可を持ちます。
**API オペレーション:**
| API アクション | コントロール/データプレーン | プロトコル | 説明 | [リソース] |
| --- | --- | --- | --- | --- |
| CreateCommand | コントロールプレーン | HTTP | コマンドリソースを作成します。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| GetCommand | コントロールプレーン | HTTP | コマンドに関する情報を取得します。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| UpdateCommand | コントロールプレーン | HTTP | コマンドまたは に関する情報を更新して非推奨にします | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| ListCommands | コントロールプレーン | HTTP | アカウントのコマンドを一覧表示します | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| DeleteCommand | コントロールプレーン | HTTP | コマンドを削除します。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| StartCommandExecution | データプレーン | HTTP | コマンドの実行を開始します | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| UpdateCommandExecution | データプレーン | MQTT | コマンド実行を更新する | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| GetCommandExecution | コントロールプレーン | HTTP | コマンド実行に関する情報を取得します。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| ListCommandExecutions | コントロールプレーン | HTTP | アカウントのコマンド実行を一覧表示します | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| DeleteCommandExecution | コントロールプレーン | HTTP | コマンド実行を削除します。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
この例では、次のように置き換えます。
+ `us-east-1` など AWS リージョン、 で を使用します`ap-south-1`。
+ `111122223333` を `57EXAMPLE833` などの AWS アカウント 番号に置き換えます。
+ `command-id`、`command-id1`、および `command-id2`で、 `LockDoor`や などの一意のコマンド識別子を指定します`TurnOffAC`。
+ `thing-name` などの AWS IoT モノの名前を指定します`my_car`。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"iot:CreateCommand",
"iot:GetCommand",
"iot:ListCommands",
"iot:UpdateCommand",
"iot:DeleteCommand"
],
"Effect": "Allow",
"Resource": [
"arn:aws:iot:us-east-1:111122223333:command/command-id1",
"arn:aws:iot:us-east-1:111122223333:command/command-id2"
]
},
{
"Action": [
"iot:GetCommandExecution",
"iot:ListCommandExecutions",
"iot:DeleteCommandExecution"
],
"Effect": "Allow",
"Resource": [
"arn:aws:iot:us-east-1:111122223333:command/command-id",
"arn:aws:iot:us-east-1:111122223333:thing/thing-name"
]
},
{
"Action": "iot:StartCommandExecution",
"Effect": "Allow",
"Resource": [
"arn:aws:iot:us-east-1:111122223333:command/command-id",
"arn:aws:iot:us-east-1:111122223333:thing/thing-name"
]
}
]
}
```
------
## AWS IoT コマンドを実行する (AWS CLI)
以下は、 を使用してコマンドオペレーション AWS CLI を実行し、車両のステアリングモードを変更する方法を示しています。
1.
**ステアリングモードオペレーションのコマンドリソースを作成する**
`create-command` CLI を使用して、デバイスに送信するコマンドを作成します。この例では、以下を指定します。
+ *`TurnOffSteeringMode`* としての `command-id`
+ `role-arn` として `"arn:aws:iam:accountId:role/FwCommandExecutionRole"` を指定`role-arn`する必要があります。これは、車両でコマンドを作成および実行するアクセス許可を付与する IAM ロールであるためです。詳細については、「[を使用してコマンドのペイロードを生成する AWS IoT Device Management アクセス許可を付与する AWS IoT FleetWise](controlling-access.md#generate-command-payload)」を参照してください。
+ `display-name` *`Turn off steering mode`*「」として
+ `namespace` は である必要があります `AWS-IoT-FleetWise`
+ `mandatory-parameters` を「\$1actuatorPath.Vehicle.Chassis.SteeringWheel.TurnOffSteeringMode`name`」とし、defaultValue を「\$1actuatorPath.Vehicle.Chassis.SteeringWheel.TurnOffSteeringMode」とする名前と値のペア*actuatorPath.Vehicle.Chassis.SteeringWheel.TurnOffSteeringMode* `{ "S": "true" }`
**注記**
必須パラメータを指定せずにコマンドを作成することもできます。次に、`start-command-execution`CLI を使用してコマンドを実行するときに使用するパラメータを指定する必要があります。例については、[コマンドの使用シナリオ](remote-command-use-cases.md)を参照してください。
**重要**
`AWS-IoT-FleetWise` 名前空間を使用する場合は、 の一部として指定された `Name`フィールドが `$actuatorPath.` プレフィックス`mandatory-parameters`を使用し、 `Value`フィールドが文字列データ型を使用していることを確認する必要があります。
```
aws iot create-command \
--command-id TurnOffSteeringMode \
--role-arn "arn:aws:iam:accountId:role/FwCommandExecutionRole" \
--display-name "Turn off steering mode" \
--namespace AWS-IoT-FleetWise \
--mandatory-parameters '[
{
"name": "$actuatorPath.Vehicle.Chassis.SteeringWheel.TurnOffSteeringMode",
"defaultValue": { "S": "true" }
}
]'
```
次の出力は、 CLI からのレスポンスの例を示しています。ここで、 `ap-south-1` と `123456789012`は AWS リージョン および AWS アカウント ID の例です。
```
{
"commandId": "TurnOffSteeringMode",
"commandArn": "arn:aws:iot:ap-south-1:123456789012:command/TurnOffSteeringMode"
}
```
このコマンドを使用するその他の例については、「」を参照してください[コマンドリソースを作成する](create-manage-remote-command-cli.md#create-remote-command-cli)。
1.
**コマンドに関する情報を取得する**
次のコマンドを実行して、コマンドに関する情報を取得します。ここで、 `command-id`は、上記の `create-command`オペレーションの出力のコマンド ID です。
**注記**
複数のコマンドを作成する場合は、 `ListCommands` API を使用してアカウント内のすべてのコマンドを一覧表示し、 `GetCommand` API を使用して特定のコマンドに関する追加情報を取得できます。詳細については、「[アカウントのコマンドを一覧表示する](create-manage-remote-command-cli.md#list-remote-command-cli)」を参照してください。
```
aws iot get-command --command-id TurnOffSteeringMode
```
このコマンドを実行すると、次のレスポンスが生成されます。コマンドが作成された時刻と最後に更新された時刻、指定したパラメータ、およびコマンドをデバイスで実行できるかどうかが表示されます。
```
{
"commandId": "TurnOffSteeringMode",
"commandArn": "arn:aws:iot:ap-south-1:123456789012:command/TurnOffSteeringMode",
"namespace": "AWS-IoT-FleetWise",
"mandatoryParameters":[
{
"name": "$actuatorPath.Vehicle.Chassis.SteeringWheel.TurnOffSteeringMode",
"defaultValue": {"S": "true" }
}
],
"createdAt": "2024-03-23T00:50:10.095000-07:00",
"lastUpdatedAt": "2024-03-23T00:50:10.095000-07:00",
"deprecated": false
}
```
このコマンドの使用に関するその他の例については、「」を参照してください[コマンドに関する情報を取得する](create-manage-remote-command-cli.md#get-remote-command-cli)。
1.
**コマンド実行を開始する**
次のコマンドを実行してコマンドの実行を開始します。ここで、 `command-arn`は、上記の `get-command`オペレーションの出力のコマンド ARN です。`target-arn` は、 コマンドを実行するターゲットデバイスの ARN です。たとえば、 です*`myVehicle`*。
この例では、コマンドの作成時にパラメータにデフォルト値を指定しているため、CLI `start-command-execution` はコマンドの実行時にこれらの値を使用できます。CLI の使用時にパラメータに別の値を指定することで、デフォルト値を上書きすることもできます。
```
aws iot-data start-command-execution \
--command-arn arn:aws:iot:ap-south-1:123456789012:command/TurnOffSteeringMode \
--target-arn arn:aws:iot:ap-south-1:123456789012:thing/myVehicle
```
このコマンドを実行すると、コマンド実行 ID が返されます。この ID を使用して、コマンド実行ステータス、詳細、およびコマンド実行履歴をクエリすることができます。
```
{
"executionId": "07e4b780-7eca-4ffd-b772-b76358da5542"
}
```
CLI の使用に関するその他の例については、「」を参照してください[コマンドを送信する (AWS CLI)](send-monitor-remote-command-cli.md#send-remote-command-cli)。
1.
**コマンド実行に関する情報を取得する**
次のコマンドを実行して、ターゲットデバイスで実行したコマンドに関する情報を取得します。上から`start-command-execution`操作の出力として`execution-id`取得した と、ターゲットとするデバイスの ARN `target-arn`である を指定します。
**注記**
最新のステータス情報を取得するには、デバイスが MQTT API を使用するコマンドの `UpdateCommandExecution` MQTT 予約レスポンストピックに更新されたステータス情報を公開している必要があります。詳細については、「[コマンド実行結果を更新する](send-monitor-remote-command-cli.md#update-remote-command-execution-cli)」を参照してください。
複数のコマンド実行を開始する場合は、 `ListCommandExecutions` API を使用してアカウント内のすべてのコマンド実行を一覧表示し、 `GetCommandExecution` API を使用して特定の実行に関する追加情報を取得できます。詳細については、「[アカウントのコマンド実行を一覧表示する](send-monitor-remote-command-cli.md#list-remote-command-execution-cli)」を参照してください。
```
aws iot get-command-execution \
--execution-id <"07e4b780-7eca-4ffd-b772-b76358da5542"> \
--target-arn arn:aws:iot:us-east-1::thing/myVehicle
```
このコマンドを実行すると、コマンドの実行、実行ステータス、実行を開始した時刻、完了時刻に関する情報が返されます。たとえば、次のレスポンスは、ターゲットデバイスでコマンドの実行が成功し、ステアリングモードがオフになったことを示しています。
```
{
"executionId": "07e4b780-7eca-4ffd-b772-b76358da5542",
"commandArn": "arn:aws:iot:ap-south-1:123456789012:command/TurnOffSteeringMode",
"targetArn": "arn:aws:iot:ap-south-1:123456789012:thing/myVehicle",
"result": "SUCCEEDED",
"statusReason": {
"reasonCode": "65536",
"reasonDescription": "SUCCESS"
},
"result": {
"KeyName": {
"S": "",
"B": true,
"BIN": null
}
},
"createdAt": "2024-03-23T00:50:10.095000-07:00",
"completedAt": "2024-03-23T00:50:10.095000-07:00",
"parameters": '{
"$actuatorPath.Vehicle.Chassis.SteeringWheel.TurnOffSteeringMode":
{ "S": "true" }
}'
}
```
## クリーンアップ
コマンドを作成してデバイスで実行したので、このコマンドを使用する予定がない場合は、削除できます。進行中の保留中のコマンド実行は、削除リクエストの影響を受けずに引き続き実行されます。
**注記**
または、コマンドが古く、後でターゲットデバイスで実行する必要がある場合は、そのコマンドを非推奨にすることもできます。
1.
**(オプション) コマンドリソースを非推奨にする**
次のコマンドを実行してコマンドを非推奨にします。ここで、 `command-id`は上記の `get-command`オペレーションの出力のコマンド ID です。
```
aws iot update-command \
--command-id TurnOffSteeringMode \
--deprecated
```
このコマンドを実行すると、コマンドが廃止されたことを示す出力が返されます。CLI を使用してコマンドを復元することもできます。
**注記**
`update-command` CLI を使用して、コマンドの表示名と説明を更新することもできます。詳細については、「[コマンドリソースを更新または廃止する](create-manage-remote-command-cli.md#update-remote-command-cli)」を参照してください。
```
{
"commandId": "TurnOffSteeringMode",
"deprecated": true,
"lastUpdatedAt": "2024-05-09T23:16:51.370000-07:00"
}
```
1.
**コマンドを削除する**
次のコマンドを実行して、 で指定された コマンドを削除します`command-id`。
**注記**
削除アクションは永続的であり、元に戻すことはできません。
```
aws iot delete-command --command-id TurnOffSteeringMode
```
削除リクエストが成功すると、コマンドを非推奨にしたか、いつ非推奨にしたかに応じて、HTTP `statusCode`が 202 または 204 になります。詳細と例については、「[コマンドリソースを削除する](create-manage-remote-command-cli.md#delete-remote-command-cli)」を参照してください。
`get-command` CLI を使用して、コマンドがアカウントから削除されたことを確認できます。
1.
**(オプション) コマンド実行を削除する**
デフォルトでは、すべてのコマンド実行は、作成日から 6 か月以内に削除されます。この情報は、 `GetCommandExecution` API の `timeToLive`パラメータを使用して表示できます。
または、実行ステータスが 、、または のいずれかである場合など`SUCCEEDED``FAILED`、コマンド実行がターミナルになった場合は`REJECTED`、コマンド実行を削除できます。次のコマンドを実行して実行を削除します。ここで、 `execution-id`は上記の `get-command-execution`オペレーションの出力にある実行 ID です。
```
aws iot delete-command-execution \
--execution-id "07e4b780-7eca-4ffd-b772-b76358da5542"
```
`get-command-execution` CLI を使用して、コマンド実行がアカウントから削除されたことを確認できます。
# コマンドの使用シナリオ
**重要**
現在、特定の AWS IoT FleetWise 機能へのアクセスはゲートされています。詳細については、「[AWS AWS IoT FleetWise でのリージョンと機能の可用性](fleetwise-regions.md)」を参照してください。
コマンド機能を使用する場合、以下のシナリオでコマンドを作成して実行できます。
+ 作成時にパラメータを省略し、コマンド ID のみを指定できます。この場合、ターゲットデバイスで コマンドを実行するときに使用するパラメータを指定する必要があります。
+ 1 つ以上のパラメータを指定し、コマンドの作成時にデフォルト値を設定できます。デフォルト値を指定すると、不正確なコマンドの送信を防ぐことができます。
+ 1 つ以上のパラメータを指定し、コマンドの作成時にそれらの値を設定できます。複数のパラメータを指定できますが、そのうちの 1 つのみが実行されます。このパラメータの `Name`フィールドは `$actuatorPath`プレフィックスを使用する必要があります。
このセクションでは、 `CreateCommand`および `StartCommandExecution` API の使用シナリオと、 パラメータの使用シナリオについて説明します。また、状態テンプレートでコマンドを使用する例もいくつか示します。
**Topics**
+ [パラメータなしでコマンドを作成する](#remote-command-use-case1)
+ [パラメータのデフォルト値を使用したコマンドの作成](#remote-command-use-case2)
+ [パラメータ値を使用したコマンドの作成](#remote-command-use-case3)
+ [状態テンプレートでのコマンドの使用](#remote-command-use-cases-templates)
## パラメータなしでコマンドを作成する
次のユースケースは、 `CreateCommand` API または CLI `create-command` を使用してパラメータなしでコマンドを作成する方法を示しています。コマンドを作成するときは、コマンド ID とロール ARN のみを指定する必要があります。
このユースケースは、同じコマンドを車両に複数回送信する場合など、繰り返し発生するユースケースで特に役立ちます。この場合、コマンドは特定のアクチュエータに関連付けられておらず、任意のアクチュエータでコマンドを柔軟に実行できます。`StartCommandExecution` API または CLI `start-command-execution` を使用してコマンドを実行する場合は、代わりに実行時にパラメータを指定する必要があります。これには、アクチュエータと物理信号値が含まれます。
### `mandatory-parameters` 入力なしでコマンドを作成する
このユースケースは、必須パラメータを入力せずにコマンドを作成する方法を示しています。
```
aws iot create-command \
--command-id "UserJourney1" \
--role-arn "arn:aws:iam:accountId:role/FwCommandExecutionRole" \
--description "UserJourney1 - No mandatory parameters" \
--namespace "AWS-IoT-FleetWise"
```
### `mandatory-parameters` 入力なしで作成されたコマンドの実行
この最初の例では、上記で作成した コマンドにより、制限なしで任意のアクチュエータでコマンドを実行できます。を 10 の値`actuator1`に設定するには、以下を実行します。
```
aws iot-jobs-data start-command-execution \
--command-arn arn:aws:iot:region:111122223333:command/UserJourney1 \
--target-arn arn:aws:iot:region:111122223333:thing/target-vehicle \
--parameters '{
"$actuatorPath.Vehicle.actuator1": {"S": "10"}
}'
```
同様に、 を の値`actuator3`に設定するコマンドを実行できます`true`。
```
aws iot-jobs-data start-command-execution \
--command-arn arn:aws:iot:region:111122223333:command/UserJourney1 \
--target-arn arn:aws:iot:region:111122223333:thing/target-vehicle \
--parameters '{
"$actuatorPath.Vehicle.actuator3": {"S": "true"}
}'
```
## パラメータのデフォルト値を使用したコマンドの作成
このコマンドでは、指定されたアクチュエータに対してのみコマンドを実行できます。デフォルト値を指定すると、不正確なコマンドの送信を防ぐことができます。たとえば、ドアをロックおよびロック解除する`LockDoor`コマンドをデフォルト値で設定して、コマンドが誤ってドアをロック解除しないようにできます。
このユースケースは、同じコマンドを複数回送信し、車両のドアのロックやロック解除など、同じアクチュエータに対して異なるアクションを実行する場合に特に便利です。アクチュエータをデフォルト値に設定する場合は、qny を `start-command-execution` CLI `parameters`に渡す必要はありません。`start-command-execution` CLI `parameters`で に別の値を指定すると、デフォルト値が上書きされます。
### のデフォルト値を使用したコマンドの作成 `mandatory-parameters`
次のコマンドは、アクチュエータ 1 のデフォルト値を指定する方法を示しています。
```
aws iot create-command \
--command-id "UserJourney2" \
--namespace "AWS-IoT-FleetWise" \
--role-arn "arn:aws:iam:accountId:role/FwCommandExecutionRole" \
--mandatory-parameters '[
{
"name": "$actuatorPath.Vehicle.actuator1",
"defaultValue": {"S": "0"}
}
]'
```
### のデフォルト値で作成されたコマンドの実行 `mandatory-parameters`
コマンド`UserJourney2`を使用すると、実行時に入力値を渡すことなくコマンドを実行できます。この場合、実行時の実行では、作成時に指定されたデフォルト値が使用されます。
```
aws iot-data start-command-execution \
--command-arn arn:aws:iot:region:111122223333:command/UserJourney3 \
--target-arn arn:aws:iot:region:111122223333:thing/target-vehicle
```
ランタイム中に同じアクチュエーターであるアクチュエーター 1 に別の値を渡すこともできます。これにより、デフォルト値が上書きされます。
```
aws iot-jobs-data start-command-execution \
--command-arn arn:aws:iot:region:111122223333:command/UserJourney3 \
--target-arn arn:aws:iot:region:111122223333:thing/target-vehicle \
--parameters '{
"$actuatorPath.Vehicle.actuator1": {"S": "139"}
}'
```
## パラメータ値を使用したコマンドの作成
このコマンドでは、指定されたアクチュエータに対してのみコマンドを実行できます。また、実行時にアクチュエータの値を設定する必要もあります。
このユースケースは、エンドユーザーが車両でアクチュエータを実行するときに、一部のアクチュエータに対して特定の指定されたアクションのみを実行できるようにする場合に特に役立ちます。
**注記**
`mandatory-parameters` 入力には 個以上の名前と値のペアがあり、一部またはすべてのデフォルト値を使用できます。実行時に、アクチュエータでの実行時に使用するパラメータを決定できます。ただし、アクチュエータ名に `$actuatorPath.`プレフィックスが付いた完全修飾名が使用されている場合です。
### のデフォルト値を使用しないコマンドの作成 `mandatory-parameters`
このコマンドでは、指定されたアクチュエータに対してのみコマンドを実行できます。また、実行時にアクチュエータの値を設定する必要もあります。
```
aws iot create-command \
--command-id "UserJourney2" \
--namespace "AWS-IoT-FleetWise" \
--role-arn "arn:aws:iam:accountId:role/FwCommandExecutionRole" \
--mandatory-parameters '[
{
"name": "$actuatorPath.Vehicle.actuator1"
}
]'
```
### のデフォルト値なしで作成されたコマンドの実行 `mandatory-parameters`
コマンドを実行する場合、この場合は actuator1 の値を指定する必要があります。以下に示すコマンドを実行すると、 の値が `actuator1`に正常に設定されます`10`。
```
aws iot-data start-command-execution \
--command-arn arn:aws:iot:region:111122223333:command/UserJourney2 \
--target-arn arn:aws:iot:region:111122223333:thing/target-vehicle \
--parameters '{
"$actuatorPath.Vehicle.actuator1": {"S": "10"}
}'
```
## 状態テンプレートでのコマンドの使用
コマンド API オペレーションを使用して、状態データの収集と処理を行うこともできます。例えば、ワンタイム状態スナップショットを取得したり、状態テンプレートを有効または無効にして、車両状態データの収集を開始または停止したりできます。次の例は、 状態テンプレートで コマンド機能を使用する方法を示しています。詳細については、[データ収集と処理のための状態テンプレートの操作](state-template-api-operations.md)を参照してください。
**注記**
`mandatory-parameters` 入力の一部として指定する名前フィールドには、 `$stateTemplate` プレフィックスを使用する必要があります。
### 例 1: デフォルト値を使用して状態テンプレートのコマンドを作成する
この例では、 CLI `create-command` を使用して状態テンプレートをアクティブ化する方法を示します。
```
aws iot create-command \
--command-id \
--display-name "Activate State Template" \
--namespace AWS-IoT-FleetWise \
--mandatory-parameters '[
{
"name": "$stateTemplate.name"
},
{
"name": "$stateTemplate.operation",
"defaultValue": {"S": "activate"}
}
]'
```
同様に、次のコマンドは、状態テンプレートに `start-command-execution` CLI を使用する方法の例を示しています。
```
aws iot-data start-command-execution \
--command-arn arn:aws:iot:region:111122223333:command/ \
--target-arn arn:aws:iot:region:111122223333:thing/ \
--parameters '{
"$stateTemplate.name": {"S": "ST345"}
}'
```
### 例 2: デフォルト値なしで状態テンプレートのコマンドを作成する
次のコマンドは、パラメータのデフォルト値なしで複数の状態テンプレートを作成します。これにより、これらのパラメータとその値を使用して コマンドを強制的に実行できます。
```
aws iot create-command \
--command-id \
--display-name "Activate State Template" \
--namespace AWS-IoT-FleetWise \
--mandatory-parameters '[
{
"name": "$stateTemplate.name",
"defaultValue": {"S": "ST123"}
},
{
"name": "$stateTemplate.operation",
"defaultValue": {"S": "activate"}
},
{
"name": "$stateTemplate.deactivateAfterSeconds",
"defaultValue": {"L": "120"}
}
]'
```
次のコマンドは、上記の例で `start-command-execution` CLI を使用する方法を示しています。
```
aws iot-data start-command-execution \
--command-arn arn:aws:iot:region:111122223333:command/ \
--target-arn arn:aws:iot:region:111122223333:thing/ \
--parameters '{
"$stateTemplate.name": {"S": "ST345"},
"$stateTemplate.operation": {"S": "activate"},
"$stateTemplate.deactivateAfterSeconds" : {"L": "120"}
```