翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# AWS IoT Device Management コマンド
**重要**
このドキュメントでは、 AWS IoT Device Managementで[コマンド機能](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command-concepts.html#command-iot-namespace)を使用する方法について説明します。 AWS IoT FleetWiseでこの機能を使用する方法については、「[リモートコマンド](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-commands.html)」を参照してください。
お客様は、安全かつ適用法に準拠した方法でコマンドをデプロイすることに全責任を負います。お客様の責任に関する詳細については、[AWS IoT サービスのAWS サービス規約](https://aws.amazon.com/service-terms/)をご覧ください。
AWS IoT Device Management コマンドを使用して、クラウドから に接続されているデバイスに命令を送信します AWS IoT。コマンドは一度に 1 つのデバイスをターゲットとし、デバイス側のログの取得やデバイスの状態変更の開始など、低レイテンシーで高スループットのアプリケーションに使用できます。
*コマンド*は、 によって管理される再利用可能なリソースです AWS IoT Device Management。これには、デバイスに公開される前に適用される設定が含まれています。電球のオンや車両のドアのロック解除など、特定のユースケースの一連のコマンドを事前に定義できます。
AWS IoT コマンド機能を使用すると、次のことができます。
+ 静的または動的なペイロードを使用して再利用可能なコマンドテンプレートを作成し、特定のデバイスで実行します。
+ AWS IoT モノまたは未登録の MQTT クライアントとして登録されたターゲットデバイス。
+ 同じデバイスで複数のコマンドを同時に実行します。
+ イベント通知を有効にし、デバイスがコマンドを処理するときに実行ステータスを追跡します。
以下のトピックでは、コマンドの作成、デバイスへのコマンドの送信、デバイスによって報告されたステータスの取得方法について説明します。
**Topics**
+ [クイックスタート](iot-commands-quickstart.md)
+ [コマンドの概念とステータス](iot-remote-command-concepts.md)
+ [高レベルのコマンドワークフロー](iot-remote-command-workflow.md)
+ [コマンドの作成と管理](iot-remote-command-create-manage.md)
+ [コマンド実行を開始およびモニタリングする](iot-remote-command-execution-start-monitor.md)
+ [コマンドリソースを非推奨にする](iot-remote-command-deprecate.md)
# クイックスタート
最初のコマンドを送信するには、次の手順に従います。
1. **前提条件** - IoT Core、IoT Core に接続されたデバイス、 コマンド API オペレーションの IAM アクセス許可、デバイスにインストールされた MQTT クライアントライブラリにオンボードされていることを確認します。
1. **コマンドの作成** - 静的ペイロード、またはデバイスアクションを指定するペイロードテンプレートを使用してコマンドを定義します。「[コマンドリソースを作成する](iot-remote-command-create-manage.md#iot-remote-command-create)」を参照してください。
1. **デバイスを識別する** - デバイスを IoT モノとして登録するか、MQTT クライアント ID を書き留めます。「[ターゲットデバイスに関する考慮事項](iot-remote-command-execution-start-monitor.md#iot-command-execution-target)」を参照してください。
1. アクセス**許可の設定** - デバイスがコマンドを受信してレスポンスを発行できるようにする IAM ポリシーを設定します。
1. **トピックをサブスクライブ**する - コマンドのリクエストおよびレスポンストピックをサブスクライブするようにデバイスを設定します。「[コマンドのターゲットデバイスを選択して MQTT トピックをサブスクライブする](iot-remote-command-workflow.md#command-choose-target)」を参照してください。
1. **コマンドを実行する** - ターゲットデバイスでコマンドの実行を開始します。「[コマンド実行を開始するコマンド実行を開始する (コンソール)コマンド実行を開始する (AWS CLI)](iot-remote-command-execution-start-monitor.md#iot-remote-command-execution-start)」を参照してください。
**一般的なユースケース:**
+ *リモート診断* - ログの取得、診断の実行、デバイスのヘルスチェック
+ *設定の更新* - 設定の変更、パラメータの更新、機能の切り替え
+ *デバイスコントロール* - ロック/ロック解除、電源オン/オフ、モード変更
# コマンドの概念とステータス
AWS IoT コマンドを使用して、クラウドから接続されたデバイスに指示を送信します。この機能を使用する方法
1. デバイスでの実行に必要な設定を含むペイロードを使用してコマンドを作成します。
1. ペイロードを受信し、アクションを実行するターゲットデバイスを指定します。
1. ターゲットデバイスで コマンドを実行し、ステータス情報を取得します。問題のトラブルシューティングについては、CloudWatch logs」を参照してください。
ワークフローの詳細については、「[高レベルのコマンドワークフロー](iot-remote-command-workflow.md)」を参照してください。
**Topics**
+ [コマンドキーの概念](#iot-command-concepts)
+ [コマンドの状態](#iot-command-states)
+ [コマンド実行ステータス](#iot-command-execution-status)
## コマンドキーの概念
以下の主要な概念は、 コマンド機能を理解するのに役立ちます。用語は、このドキュメント全体で一貫して使用されます。
+ *コマンド* - デバイスの指示を定義する再利用可能なテンプレート
+ *実行* - デバイスで実行されているコマンドのインスタンス
+ *モノの名前* - IoT レジストリに登録されているデバイスの識別子
+ *クライアント ID* - 未登録デバイスの MQTT 識別子
+ *ペイロード* - デバイスに送信される命令データ
+ *トピック* - コマンド通信用の MQTT チャネル
**コマンド**
コマンドは、MQTT メッセージとしてクラウドから IoT デバイスに送信される手順です。ペイロードを受信すると、デバイスは指示を処理し、設定の変更、センサーの読み取り値の送信、ログのアップロードなどの対応するアクションを実行します。その後、デバイスは結果をクラウドに返し、リモートモニタリングと制御を可能にします。
**名前空間**
コマンドを作成するときは、その名前空間を指定します。 AWS IoT Device Management コマンドには、デフォルトの`AWS-IoT`名前空間を使用し、ペイロードまたは payloadTemplate を指定します。 AWS IoT FleetWise コマンドには、 `AWS-IoT-FleetWise`名前空間を使用します。詳細については、「 *AWS IoT FleetWise デベロッパーガイド*」の[「リモートコマンド](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-commands.html)」を参照してください。
**ペイロード**
コマンドを作成するときは、デバイスが実行する必要があるアクションを定義する静的ペイロードを指定します。ペイロードは、サポートされている任意の形式を使用できます。デバイスがペイロードを正しく解釈できるように、ペイロード形式タイプを指定することをお勧めします。MQTT5 プロトコルを使用するデバイスは、MQTT 標準に従って形式を識別できます。JSON または CBOR の形式インジケータは、 コマンドリクエストトピックで使用できます。
**ペイロードテンプレート**
ペイロードテンプレートは、指定したパラメータ値に基づいて実行時に異なるペイロードを生成するプレースホルダーを持つコマンドペイロードを定義します。たとえば、温度値ごとに個別のペイロードを作成する代わりに、温度プレースホルダーを使用して 1 つのテンプレートを作成し、実行時に値を指定します。これにより、複数の同様のペイロードが維持されなくなります。
**ターゲットデバイス**
コマンドを実行するには、モノの名前 ( に登録されているデバイスの場合 AWS IoT) または MQTT クライアント ID (未登録デバイスの場合) を使用してターゲットデバイスを指定します。クライアント ID は、デバイスの接続に使用される[MQTT](mqtt.md)プロトコルで定義された一意の識別子です AWS IoT。詳細については、「[ターゲットデバイスに関する考慮事項](iot-remote-command-execution-start-monitor.md#iot-command-execution-target)」を参照してください。
**コマンドトのピック**
コマンドを実行する前に、デバイスはコマンドリクエストトピックをサブスクライブする必要があります。コマンドを実行すると、ペイロードはこのトピックのデバイスに送信されます。実行後、デバイスはコマンドレスポンストピックに結果とステータスを発行します。詳細については、「[コマンドトのピック](reserved-topics.md#reserved-topics-commands)」を参照してください。
**コマンドの実行**
実行は、ターゲットデバイスで実行されるコマンドのインスタンスです。実行を開始すると、ペイロードがデバイスに配信され、一意の実行 ID が生成されます。デバイスは コマンドを実行し、進捗状況を に報告します AWS IoT。デバイス側のロジックは、予約済みトピックに対する実行動作とステータスレポートを決定します。
### パラメータ値の条件
ペイロードテンプレートを使用してコマンドを作成するときは、値条件を定義して、実行前にパラメータ値を検証します。値条件により、パラメータが要件を満たし、無効な実行が防止されます。
**[CommandParameterValue](https://docs.aws.amazon.com//iot/latest/apireference/API_CommandParameterValue.html) タイプでサポートされている演算子**
**数値型 (INTEGER、LONG、DOUBLE、UNSIGNEDLONG)**
+ `EQUALS` - 値は指定された数に等しくなければなりません
+ `NOT_EQUALS` - 値は指定された数と等しくすることはできません
+ `GREATER_THAN` - 値は指定された数より大きい必要があります
+ `GREATER_THAN_EQUALS` - 値は指定された数以上である必要があります
+ `LESS_THAN` - 値は指定された数より小さくする必要があります
+ `LESS_THAN_EQUALS` - 値は指定された数以下である必要があります
+ `IN_RANGE` - 値は指定された範囲内 (含む) である必要があります
+ `NOT_IN_RANGE` - 値は指定された範囲外である必要があります (含む)
+ `IN_SET` - 値は指定された数値のいずれかと一致する必要があります
+ `NOT_IN_SET` - 値は指定された数値のいずれにも一致しない必要があります
**文字列タイプ (STRING)**
+ `EQUALS` - 値は指定された文字列と等しくなければなりません
+ `NOT_EQUALS` - 値は指定された文字列と等しくすることはできません
+ `IN_SET` - 値は指定された文字列のいずれかと一致する必要があります
+ `NOT_IN_SET` - 値は指定された文字列のいずれにも一致してはいけません
**ブール型**
+ 値条件はサポートされていません
**バイナリタイプ**
+ 値条件はサポートされていません
**例: 温度制御コマンド**
```
{
"commandId": "SetTemperature",
"namespace": "AWS-IoT",
"payloadTemplate": "{\"temperature\": \"${aws:iot:commandexecution::parameter:temperature}\"}",
"parameters": [
{
"name": "temperature",
"type": "INTEGER",
"valueConditions": [
{
"comparisonOperator": "IN_RANGE",
"operand": {
"numberRange": {
"min": "60",
"max": "80"
}
}
}
]
}
]
}
```
この例では、 `temperature`パラメータは 60～80 (両端を含む) である必要があります。この範囲外の値の実行リクエストは検証に失敗します。
**注記**
値条件は、[StartCommandExecution API](https://docs.aws.amazon.com//iot/latest/apireference/API_iot-jobs-data_StartCommandExecution.html) の呼び出し時に評価されます。失敗した検証はエラーを返し、実行の作成を防ぎます。
### パラメータ値の優先度と評価
ペイロードテンプレートを使用してコマンド実行を開始する場合、パラメータ値は次の優先度を使用して解決されます。
1. **実行リクエストパラメータ** - `StartCommandExecution`リクエストで指定された値が最優先されます
1. **コマンドのデフォルト値** - 実行リクエストでパラメータが指定されていない場合、パラメータの `defaultValue`が使用されます。
1. **値なし** - どちらも指定されていない場合、実行リクエストの生成に必要なパラメータとして実行が失敗します
値条件は、優先度で上記で導出された最終的なパラメータ値と、実行の作成前に評価されます。検証が失敗した場合、実行リクエストはエラーを返します。
**例: を使用した SetTemperature コマンド `defaultValue`**
```
{
"parameters": [
{
"name": "temperature",
"type": "INTEGER",
"defaultValue": {"I": 72},
"valueConditions": [
{
"comparisonOperator": "IN_RANGE",
"operand": {"numberRange": {"min": "60", "max": "80"}}
}
]
}
]
}
```
実行を開始する場合:
+ リクエスト`"temperature": {"I": 75}`で を指定すると、75 が使用されます。
+ 温度パラメータを省略すると、デフォルト値の 72 が使用されます。
+ 両方の値が範囲条件に対して検証されます [60,80]
## コマンドの状態
のコマンド AWS アカウント は、*使用可能*、*非推奨*、または*保留中の *3 つの状態のいずれかになります。
**使用可能**
作成が成功すると、コマンドは使用可能状態になり、デバイスで実行できます。
**非推奨**
不要になったら、非推奨のコマンドにマークを付けます。廃止されたコマンドは新しい実行を開始できませんが、保留中の実行は完了し続けます。新しい実行を有効にするには、 コマンドを Available 状態に復元します。
**削除保留中**
コマンドを削除対象としてマークすると、最大タイムアウト (デフォルト: 12 時間) より長く非推奨になると、自動的に削除されます。このアクションは永続的です。非推奨または非推奨がタイムアウトより短い場合、コマンドは削除保留中状態になり、タイムアウトの有効期限が切れた後に削除されます。
## コマンド実行ステータス
ターゲットデバイスで実行を開始すると、 `CREATED`ステータスになり、デバイスレポートに基づいて他のステータスに移行できます。ステータス情報を取得し、実行を追跡できます。
**注記**
デバイスで複数のコマンドを同時に実行できます。同時実行制御を使用して、デバイスごとの実行を制限し、オーバーロードを防止します。デバイスあたりの最大同時実行数については、[AWS IoT Device Management 「 コマンドクォータ](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#commands-limits)」を参照してください。
次の表は、実行の進行状況に基づく実行ステータスとその移行を示しています。
**コマンド実行のステータスと開始元**
| コマンド実行ステータス | 開始元はデバイスかクラウドか | 実行の終了かどうか | 許可されたステータスの移行 |
| --- | --- | --- | --- |
| CREATED | Cloud | いいえ | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/iot/latest/developerguide/iot-remote-command-concepts.html) |
| IN\$1PROGRESS | デバイス | いいえ | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/iot/latest/developerguide/iot-remote-command-concepts.html) |
| TIMED\$1OUT | デバイスとクラウド | いいえ | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/iot/latest/developerguide/iot-remote-command-concepts.html) |
| SUCCEEDED | デバイス | はい | 該当しない |
| FAILED | デバイス | はい | 該当しない |
| REJECTED | デバイス | はい | 該当しない |
デバイスは、コマンド予約 MQTT トピックを使用して、ステータスと結果の更新をいつでも発行できます。追加のコンテキストを提供するために、デバイスは `statusReason` オブジェクトの フィールド`reasonCode`と `reasonDescription`フィールドを使用できます。
次の図は、実行ステータスの遷移を示しています。
![\[コマンド実行ステータスがさまざまなステータス間でどのように移行するかを示す画像。\]](http://docs.aws.amazon.com/ja_jp/iot/latest/developerguide/images/command-execution-status-transitions.png)
**注記**
がタイムアウト期間内にデバイスレスポンス AWS IoT を検出しない場合、 を一時的なステータス`TIMED_OUT`として設定し、再試行と状態の変更を許可します。デバイスが を明示的に報告した場合`TIMED_OUT`、これはそれ以上の移行なしでターミナルステータスになります。詳細については、「[非終了のコマンド実行](#iot-command-execution-status-nonterminal)」を参照してください。
以下のセクションでは、ターミナルと非ターミナルの実行とそのステータスについて説明します。
**Topics**
+ [非終了のコマンド実行](#iot-command-execution-status-nonterminal)
+ [終了のコマンド実行](#iot-command-execution-status-terminal)
### 非終了のコマンド実行
デバイスからの更新を受け入れることができる場合、実行は非ターミナルです。非ターミナル実行は*アクティブ*と見なされます。次のステータスは非ターミナルです。
+
**CREATED**
AWS IoT コンソールから実行を開始するか、 `StartCommandExecution` API を使用すると、リクエストが成功するとステータスが に変更されます`CREATED`。このステータスから、実行は他の非ターミナルステータスまたはターミナルステータスに移行できます。
+
**IN\$1PROGRESS**
ペイロードを受信すると、デバイスは指示の実行と指定されたアクションの実行を開始できます。実行中、デバイスはコマンドレスポンストピックにレスポンスを発行し、ステータスを に更新できます`IN_PROGRESS`。から`IN_PROGRESS`、実行は 以外の任意のターミナルまたは非ターミナルステータスに移行できます`CREATED`。
**注記**
`UpdateCommandExecution` API は、 `IN_PROGRESS`ステータスで複数回呼び出すことができます。`statusReason` オブジェクトを使用して追加の実行の詳細を指定します。
+
**TIMED\$1OUT**
クラウドとデバイスの両方がこのステータスをトリガーできます。`CREATED` または `IN_PROGRESS`ステータスの実行は、次の理由で `TIMED_OUT` に変わる可能性があります。
+ コマンドを送信すると、タイマーが開始されます。デバイスが指定された期間内に応答しない場合、クラウドはステータスを に変更します`TIMED_OUT`。この場合、実行は非ターミナルです。
+ デバイスは、ステータスを任意のターミナルステータスに上書きしたり、タイムアウトを報告してステータスを に設定したりできます`TIMED_OUT`。この場合、ステータスは のままですが`TIMED_OUT`、`StatusReason`オブジェクトフィールドはデバイス情報に基づいて変わります。実行はターミナルになります。
詳細については、「[タイムアウト値と `TIMED_OUT` 実行ステータス](iot-remote-command-execution-start-monitor.md#iot-command-execution-timeout-status)」を参照してください。
### 終了のコマンド実行
デバイスからの更新を受け入れなくなると、実行はターミナルになります。次のステータスは終了です。実行は、、`CREATED`、`IN_PROGRESS`または の非ターミナルステータスからターミナルステータスに移行できます`TIMED_OUT`。
+
**成功**
デバイスが正常に実行を完了すると、コマンドレスポンストピックへのレスポンスを発行し、ステータスを に更新できます`SUCCEEDED`。
+
**FAILED**
デバイスが実行を完了できなかった場合、コマンドレスポンストピックにレスポンスを発行し、ステータスを に更新できます`FAILED`。`statusReason` オブジェクトの フィールド`reasonCode`と `reasonDescription`フィールド、または CloudWatch ログを使用して、障害のトラブルシューティングを行います。
+
**拒否**
デバイスが無効なリクエストまたは互換性のないリクエストを受信すると、ステータスが の `UpdateCommandExecution` API を呼び出すことができます`REJECTED`。`statusReason` オブジェクトの フィールド`reasonCode`と `reasonDescription`フィールド、または CloudWatch ログを使用して、問題をトラブルシューティングします。
# 高レベルのコマンドワークフロー
このワークフローは、デバイスが AWS IoT Device Management コマンドとやり取りする方法を示しています。すべての HTTP API リクエストは、署名に [Sigv4 認証情報](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html)を使用します。
![\[AWS IoT Device Management デバイスコマンドの概要ワークフロー。\]](http://docs.aws.amazon.com/ja_jp/iot/latest/developerguide/images/device-command-workflow.png)
**Topics**
+ [コマンドの作成と管理](#command-create-command)
+ [コマンドのターゲットデバイスを選択して MQTT トピックをサブスクライブする](#command-choose-target)
+ [ターゲットデバイスのコマンド実行を開始してモニタリングする](#command-command-executions)
+ [(オプション) コマンドイベントの通知を有効にする](#iot-remote-command-commands-notifications)
## コマンドの作成と管理
デバイスのコマンドを作成および管理するには、次の手順を実行します。
1.
**コマンドリソースを作成する**
コマンド[ハブから、または API を使用してコマンド](https://console.aws.amazon.com/iot/home#/commandHub)を作成します。 [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html)
1.
**ペイロードを指定する**
任意の形式でペイロードを指定します。デバイスが正しく解釈されるようにコンテンツタイプを指定します。
ペイロードテンプレートを使用する動的コマンドの場合、最終的なペイロードは、指定したパラメータを使用して実行時に生成されます。テンプレートは JSON 形式のみをサポートしますが、生成されたペイロードは JSON または CBOR として送信できます。
1.
**(オプション) 作成したコマンドを管理する**
作成後に表示名と説明を更新します。不要になったコマンドを非推奨としてマークするか、完全に削除します。ペイロード情報を変更するには、新しいコマンドを作成します。
## コマンドのターゲットデバイスを選択して MQTT トピックをサブスクライブする
ターゲットデバイスを選択し、コマンドを受信してレスポンスを発行するための MQTT トピックを設定します。
1.
**コマンドのターゲットデバイスを選択する**
コマンドを受信して実行するターゲットデバイスを選択します。登録済みデバイスにはモノの名前、未登録デバイスにはクライアント ID を使用します。詳細については、「[ターゲットデバイスに関する考慮事項](iot-remote-command-execution-start-monitor.md#iot-command-execution-target)」を参照してください。
1.
**AWS IoT デバイスポリシーを設定する**
実行を受信して更新を発行するアクセス許可を付与する IAM ポリシーを設定します。ポリシーの例[サンプルの IAM ポリシー](iot-remote-command-execution-start-monitor.md#iot-remote-command-execution-update-policy)については、「」を参照してください。
1.
**MQTT 接続を確立する**
デバイスをメッセージブローカーに接続し、リクエストとレスポンスのトピックにサブスクライブします。デバイスには アクセス`iot:Connect`許可が必要です。`DescribeEndpoint` API または `describe-endpoint` CLI コマンドを使用してデータプレーンエンドポイントを検索します。
```
aws iot describe-endpoint --endpoint-type iot:Data-ATS
```
このコマンドを実行すると、以下に示すように、アカウント固有のデータプレーンエンドポイントが返されます。
```
account-specific-prefix.iot.region.amazonaws.com
```
1.
**コマンドトピックをサブスクライブする**
コマンドリクエストトピックをサブスクライブします。実行を開始すると、メッセージブローカーはこのトピックにペイロードを発行します。デバイスは コマンドを受け取り、処理します。
(オプション) レスポンストピック (`accepted` または `rejected`) をサブスクライブして、クラウドサービスがデバイスのレスポンスを承認したか拒否したかの確認を受け取ります。
この例では、次のように置き換えます。
+ *``* を、ターゲットとするデバイスが IoT のモノとして登録されているか、MQTT クライアントとして指定されているかに応じて、`thing` または `client` に置き換えます。
+ *``* をターゲットデバイスの一意の識別子に置き換えます。この ID には、一意の MQTT クライアント ID またはモノの名前を使用することができます。
**注記**
ペイロードタイプが JSON または CBOR でない場合は、コマンドリクエストトピックに ** フィールドが存在しない可能性があります。ペイロード形式を取得するには、MQTT5 を使用して MQTT メッセージヘッダーから形式情報を取得することをお勧めします。詳細については、「[コマンドトのピック](reserved-topics.md#reserved-topics-commands)」を参照してください。
```
$aws/commands///executions/+/request/
$aws/commands///executions/+/response/accepted/
$aws/commands///executions/+/response/rejected/
```
## ターゲットデバイスのコマンド実行を開始してモニタリングする
コマンドを作成し、コマンドのターゲットを指定したら、次の手順を実行してターゲットデバイスで実行を開始できます。
1.
**ターゲットデバイスでコマンド実行を開始する**
[Command Hub から、](https://console.aws.amazon.com/iot/home#/commandHub)またはアカウント固有のエンドポイントで `StartCommandExecution` API を使用して実行を開始します。`iot:Data-ATS` デュアルスタック (IPv4/IPv6) または IPv4 のみ`iot:Jobs`に使用します。
API は、ペイロードを コマンドリクエストトピックに発行します。
**注記**
デバイスがオフラインで MQTT 永続セッションを使用している場合、 コマンドはメッセージブローカーで待機します。タイムアウト前にデバイスが再接続すると、 コマンドを処理して結果を発行できます。タイムアウトが期限切れになると、実行はタイムアウトし、ペイロードは破棄されます。
1.
**コマンド実行の結果を更新する**
デバイスはペイロードを受け取り、 コマンドを処理し、指定されたアクションを実行し、`UpdateCommandExecution`MQTT ベースの API を使用してコマンドレスポンストピックに結果を発行します。受け入れられたトピックと拒否されたトピックにサブスクライブすると、デバイスはクラウドサービスが応答を承諾したか拒否したかの確認を受け取ります。
リクエストトピックで指定した内容に応じて、** はモノまたはクライアントにすることができ、** は AWS IoT モノの名前または MQTT クライアント ID にすることができます。
**注記**
** は、コマンドレスポンストピックで JSON または CBOR のみを使用できます。
```
$aws/commands///executions//response/
```
1.
**(オプション) コマンド実行結果を取得する**
AWS IoT コンソールまたは を使用して実行結果を取得します`GetCommandExecution`。デバイスは、最新の情報について、 コマンドレスポンストピックに結果を発行する必要があります。最終更新時刻、結果、完了時刻などの詳細を表示します。
## (オプション) コマンドイベントの通知を有効にする
実行ステータスが変更されたときに通知のコマンドイベントをサブスクライブします。イベントメッセージ形式やペイロード属性など、コマンド実行イベントの詳細については、「」を参照してください[コマンド実行イベント](command-events.md)。
1.
**トピックルールを作成する**
ステータス変更通知の コマンドイベントトピックにサブスクライブします。 AWS IoT コンソールまたは を使用して AWS Lambda、Amazon SQS や AWS Step Functions などの他の AWS IoT サービスにデバイスデータをルーティングするトピックルールを作成します[AWS IoT ルールの作成](iot-create-rule.md)。
この例では、`` を通知を受信するコマンドの識別子に置き換え、`` をコマンド実行のステータスに置き換えます。
```
$aws/events/commandExecution//
```
**注記**
すべてのコマンドとコマンド実行ステータスの通知を受け取るには、ワイルドカード文字を使用し、次のトピックにサブスクライブします。
```
$aws/events/commandExecution/+/#
```
1.
**コマンドイベントを受信して処理する**
サブスクライブされたイベントを使用して、コマンドプッシュ通知を管理し、アプリケーションを構築します。
次のコードは、受信するコマンドイベント通知のサンプルペイロードを示しています。
```
{
"executionId": "2bd65c51-4cfd-49e4-9310-d5cbfdbc8554",
"status":"FAILED",
"statusReason": {
"reasonCode": "DEVICE_TOO_BUSY",
"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 Device Management コマンドを使用して、再利用可能なリモートアクションを設定するか、デバイスにすぐに指示を送信します。 AWS IoT コンソールまたは を使用して、 コマンドを作成および管理します AWS CLI。
**Topics**
+ [コマンドリソースを作成する](#iot-remote-command-create)
+ [コマンドに関する情報を取得する](#iot-remote-command-get)
+ [でコマンドを一覧表示する AWS アカウント](#iot-remote-command-list)
+ [コマンドリソースを更新する](#iot-remote-command-update)
+ [コマンドリソースを非推奨にする、または復元する](#iot-remote-command-deprecatecmd)
+ [コマンドリソースを削除する](#iot-remote-command-delete)
## コマンドリソースを作成する
コマンドを作成するときは、次の情報を入力します。
+
**一般的な情報**
ターゲットデバイスで実行するときにコマンドを識別する一意のコマンド ID を指定します。必要に応じて、管理用の表示名、説明、タグを指定します。
+ **ペイロード**
静的コマンドの場合は、デバイスアクションを定義するペイロードを指定します。正しいデバイス解釈のためにペイロード形式タイプを指定します。
動的コマンドについては、「ペイロードテンプレート属性」を参照してください。
+ **ペイロードテンプレート**
動的コマンドの場合は、プレースホルダーとパラメータを含む payloadTemplate を指定します。オプションで `defaultValue`および 条件を指定します。 AWS IoT Device Management コマンドは、実行時にプレースホルダーを置き換えます。欠落しているパラメータは defaultValue を使用します。すべての値は、定義された条件を満たす必要があります。
以下の大文字と小文字を区別するプレースホルダータイプがサポートされています。
+ `${aws:iot:commandexecution::parameter:parameter1}` – という名前のパラメータの値のプレースホルダー`parameter1`。
+ `${aws:iot:commandexecution::executionTimeoutSec}` – 実行時に指定されたコマンド実行タイムアウトパラメータのプレースホルダー。
### ペイロードとコマンドのトピック
コマンド予約 トピックは、ペイロード形式タイプに基づく形式を使用します。
+ `application/json` または `application/cbor`コンテンツタイプの場合は、次のリクエストトピックを使用します。
```
$aws/commands///executions/+/request/
```
+ 他のコンテンツタイプまたは指定されていない形式の場合は、このリクエストトピックを使用します。ペイロード形式は MQTT メッセージヘッダーに表示されます。
```
$aws/commands///executions/+/request
```
コマンドレスポンス Topic は、ペイロードタイプに関係なく `json`または `cbor`形式を使用します。** は `json`または である必要があります`cbor`。
```
$aws/commands///executions//response/
```
### コマンドリソースの作成 (コンソール)
以下のセクションでは、ペイロード形式の考慮事項とコンソールからのコマンド作成について説明します。
**Topics**
+ [静的コマンドペイロード形式](#iot-commands-payload-format)
+ [動的コマンドペイロード形式](#iot-commands-dynamic-payload-format)
+ [コマンドの作成方法 (コンソール)](#iot-commands-console-how)
#### 静的コマンドペイロード形式
ペイロードは、最大 32 KB の任意の形式をサポートします。安全で正しいデバイス解釈のためにペイロード形式タイプを指定します。
形式 (例: `application/json`または `application/cbor`) を使用してペイロード`type/subtype`形式タイプを指定します。デフォルト: `application/octet-stream`。サポートされている形式については、[「一般的な MIME タイプ](https://developer.mozilla.org/en-US/docs/Web/HTTP/MIME_types/Common_types)」を参照してください。
#### 動的コマンドペイロード形式
payloadTemplate は、少なくとも 1 つのプレースホルダー、最大 32 KB の有効な JSON である必要があります。
`AwsJsonSubstitution` プリプロセッサの場合、 AWS IoT Device Management コマンドはプリプロセッサ設定に基づいて JSON または CBOR 形式で通知を送信します。
#### コマンドの作成方法 (コンソール)
コンソールからコマンドを作成するには、[Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) に移動し、次の手順に従います。
1. **[コマンドを作成]** を選択します。
1. 一意のコマンド ID を指定します。
1. (オプション) 表示名、説明、タグを指定します。
1. デバイスアクションを含むペイロードファイルをアップロードします。正しいデバイス解釈のためにペイロード形式タイプを指定します。
1. (オプション) プレースホルダーを含む JSON ペイロードテンプレートの場合、パラメータは編集のためにインラインテーブルに事前入力されます。
1. (オプション) パラメータ値タイプ (必須）、デフォルト値、および条件を設定します。
1. **[コマンドを作成]** を選択します。
### コマンドリソースの作成 (CLI)
[https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html) API または [https://docs.aws.amazon.com/cli/latest/reference/iot/create-command.html](https://docs.aws.amazon.com/cli/latest/reference/iot/create-command.html) CLI コマンドを使用して、 コマンドを作成します。
**Topics**
+ [コマンドのペイロード](#iot-commands-payload)
+ [サンプルの IAM ポリシー](#iot-remote-command-create-iam)
+ [静的コマンド作成の例](#iot-remote-command-create-example)
+ [動的コマンド作成の例](#iot-remote-dynamic-command-create-example)
#### コマンドのペイロード
静的ペイロードまたはペイロードテンプレートを指定します。静的ペイロードは base64 でエンコードされます。ペイロードテンプレートの場合、最終的なペイロードはパラメータ値を使用して実行時に を生成します。デバイスはペイロードを処理し、指定されたアクションを実行します。正しいデバイス受信のためのペイロードコンテンツタイプを指定します。
**注記**
コマンドの作成後にペイロードを変更することはできません。ペイロードを変更する新しいコマンドを作成します。
#### サンプルの IAM ポリシー
この API オペレーションを使用する前に、デバイスでこのアクションを実行することを IAM ポリシーが許可していることを確認してください。以下に、`CreateCommand` アクションの実行をユーザーに許可する IAM ポリシーの例を示しています。
この例では、次のように置き換えます。
+ `region` を `us-east-1` などお客様ご自身の AWS リージョンに置き換えます。
+ `account-id` を `123456789012` などの AWS アカウント 番号に置き換えます。
+ `command-id` など、 AWS IoT コマンド ID の一意の識別子を持つ `LockDoor`。複数のコマンドを送信する場合は、IAM ポリシーの「*Resource*」セクションでこれらのコマンドを指定できます。
****
```
{
"Version":"2012-10-17",
"Statement": {
"Action": "iot:CreateCommand",
"Effect": "Allow",
"Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id"
}
}
```
#### 静的コマンド作成の例
次の例は、静的コマンドを作成する方法を示しています。用途に応じて、以下を置き換えてください。
+ *``* をコマンドの一意の識別子で置き換えます。たとえば、家のドアをロックするには、 を指定できます*`LockDoor`*。UUID を使用することをお勧めします。英数字、「-」、「\$1」を使用することもできます。
+ (オプション) *``* および *``* は、*`Lock the doors of my home`* など、コマンドのわかりやすい名前と意味を持つ説明を提供するために使用できるオプションのフィールドです。
+ `namespace` は、コマンドの名前空間を指定するために使用できます。これは `AWS-IoT` である必要があります。にこの機能を使用する方法については AWS IoT FleetWise、[「リモートコマンド](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-commands.html)」を参照してください。
+ `payload` には、コマンドの実行時に使用するペイロードとそのコンテンツタイプに関する情報が含まれています。
```
aws iot create-command \
--command-id \
--display-name \
--description \
--namespace AWS-IoT \
--payload '{"content":"eyAibWVzc2FnZSI6ICJIZWxsbyBJb1QiIH0=","contentType":"application/json"}'
```
このコマンドを実行すると、コマンドの ID と ARN (Amazon リソース名) を含むレスポンスが生成されます。たとえば以下は、作成時に `LockDoor` コマンドを指定した場合の、コマンド実行の出力例です。
```
{
"commandId": "LockDoor",
"commandArn": "arn:aws:iot:us-east-1:123456789012:command/LockDoor"
}
```
#### 動的コマンド作成の例
次の例は、動的コマンドを作成する方法を示しています。用途に応じて、以下を置き換えてください。
+ *``* をコマンドの一意の識別子で置き換えます。例えば、照明の電源ステータスを設定するには、 を指定できます*`Light_Power_Status`*。UUID を使用することをお勧めします。英数字、「-」、「\$1」を使用することもできます。
+ (オプション) *``* および *``* は、*`Turn a light ON or OFF`* など、コマンドのわかりやすい名前と意味を持つ説明を提供するために使用できるオプションのフィールドです。
+ `namespace` は、コマンドの名前空間を指定するために使用できます。これは `AWS-IoT` である必要があります。にこの機能を使用する方法については AWS IoT FleetWise、[「リモートコマンド](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-commands.html)」を参照してください。
+ `payloadTemplate` には、プレースホドラーを含む JSON 形式の playoad テンプレートが含まれています。
+ `preprocessor` には、payloadTemplateの処理方法を決定するプリプロセッサの設定が含まれています。
+ `mandatoryParameter` には、payloadTemplate のプレースホルダーに対応するパラメータ、そのタイプ、デフォルト値、および条件が含まれます。
```
aws iot create-command \
--command-id Light_Power_Status \
--description "Turn a light ON or OFF" \
--namespace AWS-IoT \
--payload-template '{"powerStatus":"${aws:iot:commandexecution::parameter:powerStatus}"}' \
--preprocessor awsJsonSubstitution={outputFormat=JSON} \
--mandatory-parameters "name=powerStatus, defaultValue={S=OFF}, valueConditions=[{comparisonOperator=IN_SET, operand={strings=['ON','OFF']}}]"
```
このコマンドを実行すると、コマンドの ID と ARN (Amazon リソース名) を含むレスポンスが生成されます。たとえば以下は、作成時に `Light_Power_Status` コマンドを指定した場合の、コマンド実行の出力例です。
```
{
"commandId": "Light_Power_Status",
"commandArn": "arn:aws:iot:us-east-1:123456789012:command/Light_Power_Status"
}
```
## コマンドに関する情報を取得する
コマンドを作成した後は、 AWS IoT コンソールから AWS CLIを使用してそのコマンドに関する情報を取得できます。取得できる情報は次のとおりです。
+ コマンド ID、Amazon リソースネーム (ARN)、コマンドに指定した表示名と説明。
+ ターゲットデバイス上でコマンドを実行できるかどうか、または非推奨なのか、削除されているかを示すコマンドの状態。
+ 指定したペイロードまたは payloadTemplate。
+ 指定したプリプロセッサ。
+ 指定した mandatoryParameters。
+ コマンドが作成され、最後にアップデートされた時刻。
### コマンドリソースを取得する (コンソール)
コンソールからコマンドを取得するには、 AWS IoT コンソールの [コマンドハブ](https://console.aws.amazon.com/iot/home#/commandHub)に移動し、作成したコマンドを選択して詳細を表示します。
コマンドの詳細に加えて、ターゲットデバイスでのコマンドの実行に関する情報を提供するコマンド履歴を確認できます。デバイスでこのコマンドを実行すると、このタブで実行に関する情報を確認できます。
### コマンドリソースを取得する (CLI)
HTTP コントロールプレーン API [https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommand.html) オペレーションまたは [https://docs.aws.amazon.com/cli/latest/reference/get-command.html](https://docs.aws.amazon.com/cli/latest/reference/get-command.html) AWS CLI コマンドを使用して、コマンドリソースに関する情報を取得します。このコマンドは、`CreateCommand` API リクエスト、または `create-command` CLI を使用してあらかじめ作成しておく必要があります。
#### サンプルの IAM ポリシー
この API オペレーションを使用する前に、デバイスでこのアクションを実行することを IAM ポリシーが許可していることを確認してください。以下に、`GetCommand` アクションの実行をユーザーに許可する IAM ポリシーの例を示しています。
この例では、次のように置き換えます。
+ `region` を `us-east-1` などお客様ご自身の AWS リージョンに置き換えます。
+ `account-id` を `123456789023` などの AWS アカウント 番号に置き換えます。
+ `command-id` `LockDoor`または などの一意のコマンド識別子を使用します AWS IoT `Light_Power_Status`。複数のコマンドを取得する場合は、IAM ポリシーの「*Resource*」セクションでこれらのコマンドを指定できます。
****
```
{
"Version":"2012-10-17",
"Statement": {
"Action": "iot:GetCommand",
"Effect": "Allow",
"Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id"
}
}
```
#### コマンド取得の例 (AWS CLI)
次の例は、 を使用してコマンドに関する情報を取得する方法を示しています`get-command` AWS CLI。用途に応じて、*``* を情報を取得するコマンドの識別子に置き換えてください。この情報は、`create-command` CLI のレスポンスから取得できます。
```
aws iot get-command --command-id
```
このコマンドを実行すると、コマンド、ペイロード、作成時刻と最終更新時刻に関する情報を含むレスポンスが生成されます。また、コマンドが非推奨になっているか、削除されているかを示す情報も提供されます。
以下のコードは、レスポンスの例です。
```
{
"commandId": "LockDoor",
"commandArn": "arn:aws:iot:::command/LockDoor",
"namespace": "AWS-IoT",
"payload":{
"content": "eyAibWVzc2FnZSI6ICJIZWxsbyBJb1QiIH0=",
"contentType": "application/json"
},
"createdAt": "2024-03-23T00:50:10.095000-07:00",
"lastUpdatedAt": "2024-03-23T00:50:10.095000-07:00",
"deprecated": false,
"pendingDeletion": false
}
```
## でコマンドを一覧表示する AWS アカウント
コマンドを作成すると、アカウントで作成したコマンドを表示することができます。リストでは、以下の情報を確認できます。
+ コマンド ID、およびコマンドに指定した表示名。
+ コマンドの Amazon リソースネーム (ARN)。
+ ターゲットデバイス上でコマンドを実行できるかどうか、またはコマンドが非推奨なのかを示すコマンドの状態。
**注記**
アカウントから削除されているコマンドは、リストに表示されません。コマンドが保留中の削除の場合は、コマンド ID を使用することでこれらのコマンドの詳細を表示できます。
+ コマンドが作成され、最後に更新された時刻。
### アカウントのコマンドを一覧表示する (コンソール)
AWS IoT コンソールでは、[Command Hub ](https://console.aws.amazon.com/iot/home#/commandHub)に移動して、作成したコマンドのリストとその詳細を確認できます。
### アカウントのコマンドを一覧表示する (CLI)
作成したコマンドを一覧表示するには、[https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommands.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommands.html) API オペレーションまたは [https://docs.aws.amazon.com/cli/latest/reference/iot/list-commands.html](https://docs.aws.amazon.com/cli/latest/reference/iot/list-commands.html) CLI を使用します。
#### サンプルの IAM ポリシー
この API オペレーションを使用する前に、デバイスでこのアクションを実行することを IAM ポリシーが許可していることを確認してください。以下に、`ListCommands` アクションの実行をユーザーに許可する IAM ポリシーの例を示しています。
この例では、次のように置き換えます。
+ `region` を `us-east-1` などお客様ご自身の AWS リージョンに置き換えます。
+ `account-id` を `123456789012` などの AWS アカウント 番号に置き換えます。
****
```
{
"Version":"2012-10-17",
"Statement": {
"Action": "iot:ListCommands",
"Effect": "Allow",
"Resource": "arn:aws:iot:us-east-1:123456789012:command/*"
}
}
```
#### アカウントのコマンドを一覧表示する例
アカウントのコマンドを一覧表示するには、次のコマンドを使用できます。
```
aws iot list-commands --namespace "AWS-IoT"
```
このコマンドを実行すると、作成したコマンドのリスト、コマンドが作成された時刻、最後に更新された時刻を含むレスポンスが生成されます。また、コマンドが非推奨になっているのか、またはターゲットデバイス上で実行可能な状態なのかどうかを示す、コマンドの状態も示されます。それぞれのステータスとステータスの理由については、「[コマンド実行ステータス](iot-remote-command-concepts.md#iot-command-execution-status)」を参照してください。
## コマンドリソースを更新する
コマンドを作成した後に、コマンドの表示名と説明を更新することができます。
**注記**
コマンドのペイロードは更新できません。この情報を更新したり、変更されたペイロードを使用したりするには、新しいコマンドを作成する必要があります。
### コマンドリソースを更新する (コンソール)
コンソールからコマンドを更新するには、 AWS IoT コンソールの [コマンドハブ](https://console.aws.amazon.com/iot/home#/commandHub)に移動し、次の手順を実行します。
1. 既存のコマンドリソースを更新するには、更新するコマンドを選択し、**[アクション]** で **[編集]** を選択します。
1. 使用する表示名と説明、および名前と値のペアをコマンドのタグとして指定します。
1. **[編集]** を選択して、コマンドを新しい設定で保存します。
### コマンドリソースを更新する (CLI)
[https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateCommand.html) コントロールプレーン API オペレーションまたは [https://docs.aws.amazon.com/cli/latest/reference/iot/update-command.html](https://docs.aws.amazon.com/cli/latest/reference/iot/update-command.html) AWS CLI を使用して、コマンドリソースを更新します。この API を使用すると、次のことができます。
+ 作成したコマンドの表示名と説明を編集する。
+ コマンドリソースを非推奨にする、または、既に非推奨になっているコマンドを復元する。
#### サンプルの IAM ポリシー
この API オペレーションを使用する前に、デバイスでこのアクションを実行することを IAM ポリシーが許可していることを確認してください。以下に、`UpdateCommand` アクションの実行をユーザーに許可する IAM ポリシーの例を示しています。
この例では、次のように置き換えます。
+ `region` を `us-east-1` などお客様ご自身の AWS リージョンに置き換えます。
+ `account-id` を `123456789012` などの AWS アカウント 番号に置き換えます。
+ `command-id` を `LockDoor` などの AWS IoT の一意のコマンド識別子に置き換えます。複数のコマンドを取得する場合は、IAM ポリシーの「*Resource*」セクションでこれらのコマンドを指定できます。
****
```
{
"Version":"2012-10-17",
"Statement": {
"Action": "iot:UpdateCommand",
"Effect": "Allow",
"Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id"
}
}
```
#### コマンドに関する情報を更新する例 (AWS CLI)
次の例は、 コマンドを使用して`update-command` AWS CLI コマンドに関する情報を更新する方法を示しています。この API を使用してコマンドリソースを非推奨にする、または復元する方法については、「[コマンドリソースを更新する (CLI)](iot-remote-command-deprecate.md#iot-remote-command-deprecate-cli)」を参照してください。
この例では、コマンドの表示名と説明を更新する方法を示しています。用途に応じて、*``* を情報を取得するコマンドの識別子に置き換えてください。
```
aws iot update-command \
--command-id
--displayname \
--description
```
このコマンドを実行すると、コマンドに関する更新された情報と最後に更新された時刻を含むレスポンスが生成されます。次のコードは、AC をオフにするコマンドの表示名と説明を更新するためのリクエストとレスポンスの例を示しています。
```
aws iot update-command \
--command-id \
--displayname \
--description
```
このコマンドを実行すると、次のレスポンスが生成されます。
```
{
"commandId": "LockDoor",
"commandArn": "arn:aws:iot:us-east-1:123456789012:command/LockDoor",
"displayName": "Secondary lock door",
"description": "Locks doors to my home",
"lastUpdatedAt": "2024-05-09T23:15:53.899000-07:00"
}
```
## コマンドリソースを非推奨にする、または復元する
コマンドを作成した後、コマンドの使用を継続しない場合は、非推奨としてマークできます。コマンドを非推奨にすると、保留中のすべてのコマンド実行は、終了ステータスに達するまでターゲットデバイスで実行され続けます。コマンドを非推奨にした後で、新しいコマンド実行をターゲットデバイスに送信するなどにコマンドを使用する場合は、コマンドを復元する必要があります。
**注記**
非推奨にしたコマンドを編集したり、そのコマンドに新しい実行を実行したりすることはできません。デバイスで新しいコマンドを実行するには、コマンドを復元して、コマンドの状態を *[利用可能]* にする必要があります。
コマンドの非推奨化と復元、およびその考慮事項の詳細については、「[コマンドリソースを非推奨にする](iot-remote-command-deprecate.md)」を参照してください。
## コマンドリソースを削除する
コマンドが不要になった場合は、コマンドをアカウントから完全に削除することができます。削除アクションが成功した場合、以下が適用されます。
+ コマンドが最大タイムアウトの 12 時間より長い期間非推奨になっている場合、コマンドは即時に削除されます。
+ コマンドが非推奨になっていない場合、または非推奨状態にある期間が最大タイムアウト期間より短い場合、そのコマンドは [`pending deletion`] の状態になります。最大タイムアウトの 12 時間後に、アカウントから自動的に削除されます。
**注記**
コマンドは、保留中のコマンドの実行がある場合でも、削除される可能性があります。コマンドは保留中の削除状態になり、アカウントから自動的に削除されます。
### コマンドリソースを削除する (コンソール)
コンソールからコマンドを削除するには、 AWS IoT コンソールの [コマンドハブ](https://console.aws.amazon.com/iot/home#/commandHub)に移動し、次の手順を実行します。
1. 削除するコマンドを選択し、**[アクション]** で **[削除]** を選択します。
1. コマンドを削除することを確認し、**[削除]** を選択します。
コマンドは削除対象としてマークされ、12 時間後にアカウントから完全に削除されます。
### コマンドリソースを削除する (CLI)
HTTP コントロールプレーン API `DeleteCommand` オペレーションまたは `delete-command` AWS CLI コマンドを使用して、コマンドリソースを削除します。削除アクションが成功すると、HTTP `statusCode` が 204 または 202 になり、最大タイムアウト期間の 12 時間後にコマンドは自動的にアカウントから削除されます。ステータスが 204 の場合、これはコマンドが削除されたことを示しています。
#### サンプルの IAM ポリシー
この API オペレーションを使用する前に、デバイスでこのアクションを実行することを IAM ポリシーが許可していることを確認してください。以下に、`DeleteCommand` アクションの実行をユーザーに許可する IAM ポリシーの例を示しています。
この例では、次のように置き換えます。
+ `region` を `us-east-1` などお客様ご自身の AWS リージョンに置き換えます。
+ `account-id` を `123456789012` などの AWS アカウント 番号に置き換えます。
+ `command-id` を `LockDoor` などの AWS IoT の一意のコマンド識別子に置き換えます。複数のコマンドを取得する場合は、IAM ポリシーの「*Resource*」セクションでこれらのコマンドを指定できます。
****
```
{
"Version":"2012-10-17",
"Statement": {
"Action": "iot:DeleteCommand",
"Effect": "Allow",
"Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id"
}
}
```
#### コマンドを削除する例 (AWS CLI)
次の例は、 コマンドを使用して`delete-command` AWS CLI コマンドを削除する方法を示しています。用途に応じて、*``* を、削除するコマンドの識別子に置き換えてください。
```
aws iot delete-command --command-id
```
API リクエストが成功すると、コマンドは 202 または 204 のステータスコードを生成します。`GetCommand` API を使用して、コマンドがアカウントに存在していないことを確認できます。
# コマンド実行を開始およびモニタリングする
コマンドを作成したら、ターゲットデバイスで実行を開始します。デバイスは結果を更新し、MQTT 予約済みトピックにステータスを発行します。アカウントから実行ステータスを取得してモニタリングします。
AWS IoT コンソールまたは を使用して、 コマンドを起動およびモニタリングします AWS CLI。
**Topics**
+ [コマンド実行を開始する](#iot-remote-command-execution-start)
+ [コマンド実行の結果を更新する](#iot-remote-command-execution-update)
+ [コマンド実行を取得する](#iot-remote-command-execution-get)
+ [MQTT テストクライアントを使用したコマンドの更新の表示](#iot-remote-command-execution-update-mqtt)
+ [でコマンド実行を一覧表示する AWS アカウント](#iot-remote-command-execution-list)
+ [コマンド実行を削除する](#iot-remote-command-execution-delete)
## コマンド実行を開始する
**重要**
お客様は、安全かつ適用法に準拠した方法でコマンドをデプロイすることに全責任を負います。
実行を開始する前に、以下を確認してください。
+ ペイロード情報を使用して AWS IoT 名前空間に コマンドを作成しました。実行を開始すると、デバイスはペイロード命令を処理し、指定されたアクションを実行します。コマンドの作成[コマンドリソースを作成する](iot-remote-command-create-manage.md#iot-remote-command-create)については、「」を参照してください。
+ デバイスが コマンド用に MQTT 予約トピックにサブスクライブしました。Execution を開始すると、ペイロード情報は、この予約された MQTT リクエストトピックに発行されます。
** は Things または MQTT クライアントです。** はモノの名前またはクライアント ID です。サポートされている ** 値: JSON および CBOR。詳細については、「[コマンドトのピック](reserved-topics.md#reserved-topics-commands)」を参照してください。
```
$aws/commands///executions/+/request/
```
JSON/CBOR ** 以外の場合は、次のコマンドトピック形式を使用します。
```
$aws/commands///executions/+/request
```
### ターゲットデバイスに関する考慮事項
コマンドを受信して実行するターゲットデバイスを指定します。登録済みデバイスにはモノの名前、未登録デバイスにはクライアント ID を使用します。ペイロードを受信すると、デバイスは コマンドを実行し、指定されたアクションを実行します。
#### AWS IoT モノ
ターゲットデバイスは、 AWS IoT レジストリに登録されているモノにすることができます。モノはデバイスの検索と管理を簡素化します。
[Connect デバイスページまたは を使用して、デバイスを](https://console.aws.amazon.com/iot/home#/connect-overview)モノとして登録します[https://docs.aws.amazon.com/iot/latest/apireference/API_CreateThing.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateThing.html)。[Thing Hub ](https://console.aws.amazon.com/iot/home#/thinghub)または を使用して既存のモノを検索します[https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeThing.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeThing.html)。登録の詳細については[、「レジストリでのモノの管理](https://docs.aws.amazon.com/iot/latest/developerguide/thing-registry)」を参照してください。
#### クライアント ID
未登録のデバイスの場合は、クライアント ID を使用します。
クライアント ID は、デバイスに割り当てる一意の識別子です。MQTT プロトコルで定義され、英数字、アンダースコア、またはダッシュが含まれます。に接続する各デバイスには、一意のクライアント ID AWS IoT が必要です。
**注記**
登録済みのモノの場合、クライアント ID はモノの名前と一致することができます。
特定のクライアント ID をターゲットにする場合、デバイスはペイロードを受け取るためにそのクライアント ID AWS IoT を使用して に接続する必要があります。
クライアント ID は、デバイスが に接続するときに使用する MQTT クライアント ID です AWS IoT Core。 はこの ID AWS IoT を使用してデバイスを識別し、接続とサブスクリプションを管理します。
### コマンド実行のタイムアウトに関する考慮事項
タイムアウトは、実行結果を提供するデバイスの期間 (秒単位) を指定します。
実行を作成すると、タイマーが開始されます。デバイスがオフラインになるか、タイムアウト内に結果を報告できない場合、実行はステータス でタイムアウトします`TIMED_OUT`。
デフォルト: 10 秒。最大: 12 時間。
#### タイムアウト値と `TIMED_OUT` 実行ステータス
クラウドとデバイスの両方がタイムアウトをレポートできます。
コマンドを送信すると、タイマーが開始されます。タイムアウト内にデバイスレスポンスが到着しない場合、クラウドは理由コード `TIMED_OUT`を使用して実行ステータスを に設定します`$NO_RESPONSE_FROM_DEVICE`。
これは、次の場合に発生します。
+ 実行中にデバイスがオフラインになりました。
+ デバイスはタイムアウト内に実行を完了できませんでした。
+ タイムアウト内にデバイスがステータスをレポートできませんでした。
この場合、`TIMED_OUT` の実行ステータスがクラウドから報告されると、コマンドの実行は非終了の状態です。デバイスは、ステータスをターミナルステータス `SUCCEEDED`、、`FAILED`または のいずれかに上書きするレスポンスを発行できます`REJECTED`。その後、コマンド実行はターミナルになり、それ以降の更新は受け付けません。
デバイスは、コマンドの実行時にタイムアウトが発生したことを報告することで、クラウドによって開始された`TIMED_OUT`ステータスを更新することもできます。この場合、コマンドの実行ステータスは のままですが`TIMED_OUT`、`statusReason`オブジェクトはデバイスによって報告された情報に基づいて更新されます。その後、コマンドの実行はターミナルになり、それ以上の更新は受け入れられません。
#### MQTT 永続的セッションの使用
AWS IoT Device Management コマンド機能で使用するように MQTT 永続セッションを設定できます。この機能は、デバイスがオフラインになり、タイムアウト時間前にオンラインに戻ったときに、デバイスがコマンドを受信して指定された手順を実行できるようにする場合などに、特に便利です。
デフォルトでは、MQTT 永続セッションの有効期限は 60 分に設定されています。コマンド実行タイムアウトがこの期間を超える値に設定されている場合、60 分以上実行されるコマンド実行はメッセージブローカーによって拒否され、失敗する可能性があります。実行時間が 60 分を超えるコマンドを実行するには、永続セッションの有効期限の延長をリクエストできます。
**注記**
MQTT 永続セッション機能を正しく使用するには、クリーンスタートフラグをゼロに設定します。詳細については、「[MQTT 永続セッション](https://docs.aws.amazon.com/iot/latest/developerguide/mqtt.html#mqtt-persistent-sessions)」を参照してください。
### コマンド実行を開始する (コンソール)
コンソールからコマンドの実行を開始するには、 AWS IoT コンソールの [コマンドハブ](https://console.aws.amazon.com/iot/home#/commandHub)ページに移動し、次の手順を実行します。
1. 作成したコマンドを実行するには、**[コマンドの実行]** を選択します。
1. MQTT 予約トピックや該当する場合はパラメータなど、作成したコマンドに関する情報を確認します。
動的コマンドの場合は、パラメータ値を入力するか、デフォルトのままにします。デフォルト値を持たないパラメータの場合、この実行の一部として送信される値を指定する必要があります。
1. コマンドを受信して実行するターゲットデバイスを指定します。デバイスが に登録されている場合は AWS IoT モノとして指定でき AWS IoT、デバイスがまだ登録されていない場合はクライアント ID を使用できます。詳細については、[ターゲットデバイスに関する考慮事項](#iot-command-execution-target)を参照してください。
1. (オプション) コマンドのタイムアウト値を設定し、タイムアウトまでにコマンドを実行する期間を決定します。コマンドを 60 分よりも長く実行させる場合は、MQTT 永続セッションの有効期間を延長する必要がある可能性があります。詳細については、「[コマンド実行のタイムアウトに関する考慮事項](#iot-command-execution-timeout)」を参照してください。
1. [**Run command**] を選択してください。
### コマンド実行を開始する (AWS CLI)
[https://docs.aws.amazon.com/iot/latest/apireference/API_StartCommandExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_StartCommandExecution.html) HTTP データプレーン API オペレーションを使用して、コマンド実行を開始します。API リクエストとレスポンスは、コマンド実行 ID と相関しています。デバイスは、コマンドの実行を完了すると、コマンドレスポンストピックにメッセージを発行することで、ステータスと実行結果をクラウドに報告できます。カスタムレスポンスコードの場合、所有しているアプリケーションコードはレスポンスメッセージを処理して結果を投稿できます AWS IoT。
デバイスがコマンドリクエストトピックをサブスクライブしている場合は、`StartCommandExecution` API がペイロードメッセージをトピックに発行します。ペイロードには、任意の形式を使用できます。詳細については、「[コマンドのペイロード](iot-remote-command-create-manage.md#iot-commands-payload)」を参照してください。
```
$aws/commands///executions/+/request/
```
ペイロード形式が JSON または CBOR でない場合、コマンドリクエストトピックの形式を次に示します。
```
$aws/commands///executions/+/request
```
#### サンプルの IAM ポリシー
この API オペレーションを使用する前に、デバイスでこのアクションを実行することを IAM ポリシーが許可していることを確認してください。以下に、`StartCommandExecution` アクションの実行をユーザーに許可する IAM ポリシーの例を示しています。
この例では、次のように置き換えます。
+ `region` を `us-east-1` などお客様ご自身の AWS リージョンに置き換えます。
+ `account-id` を `123456789012` などの AWS アカウント 番号に置き換えます。
+ `command-id` など、 AWS IoT コマンドの一意の識別子を持つ `LockDoor`。複数のコマンドを送信する場合は、IAM ポリシーでこれらのコマンドを指定できます。
+ `devices` デバイスが AWS IoT モノとして登録されているか、MQTT クライアントとして指定されているか`client`に応じて、 `thing`または のいずれかを使用します。
+ `device-id` `thing-name`または AWS IoT を使用します`client-id`。
```
{
"Effect": "Allow",
"Action": [
"iot:StartCommandExecution"
],
"Resource": [
"arn:aws:iot:region:account-id:command/command-id",
"arn:aws:iot:region:account-id:devices/device-id"
]
}
```
でサポートされている条件キーのリストを確認するには`StartCommandExecution`、*IAM ユーザーガイド*の「 [の条件キー AWS IoT](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsiot.html#awsiot-policy-keys)」を参照してください。
#### アカウント固有のデータプレーンエンドポイントを取得する
API コマンドを実行する前に、エンドポイントのアカウント固有のエンドポイント URL を取得する必要があります。デュアルスタックエンドポイント (IPv4 と IPv6) を使用している場合は、`iot:Data-ATS` を使用します。`iot:Jobs` エンドポイントは IPv4 専用です。たとえば、次のコマンドを実行するとします。
```
aws iot describe-endpoint --endpoint-type iot:Data-ATS
```
以下のレスポンスの例に示すように、アカウント固有のエンドポイント URL を返します。
```
{
"endpointAddress":
"-ats.iot..api.com"
}
```
#### コマンド実行を開始する例 (AWS CLI)
次の例は、 コマンドを使用して`start-command-execution` AWS CLI コマンドの実行を開始する方法を示しています。
この例では、次のように置き換えます。
+ *``* を実行するコマンドの ARN に置き換えます。この情報は、`create-command` CLI コマンドのレスポンスから取得できます。たとえば、ステアリングホイールモードを変更するためのコマンドを実行する場合は、`arn:aws:iot:region:account-id:command/SetComfortSteeringMode` を使用します。
+ *``* をターゲットデバイスのモノの ARN に置き換えます。これは、コマンド実行のターゲットとなる IoT のモノ、または MQTT クライアントです。たとえば、ターゲットデバイス `myRegisteredThing` に対してコマンドを実行する場合は、`arn:aws:iot:region:account-id:thing/myRegisteredThing` を使用します。
+ *``* を、[アカウント固有のデータプレーンエンドポイントを取得する](#iot-remote-command-execution-start-endpoint) で取得したアカウント固有のエンドポイントに `https://` のプレフィックスを付けて置き換えます。例えば、`https://123456789012abcd.jobs.iot.us-east-1.amazonaws.com`。
+ (オプション) `StartCommandExecution` API オペレーションを実行するときに、追加のパラメータ `executionTimeoutSeconds` を指定することもできます。このオプションフィールドは、デバイスがコマンドの実行を完了する必要がある時間枠を秒単位で指定します。デフォルト値は 10 秒です。コマンドの実行ステータスが `CREATED` になると、タイマーが開始されます。タイマーの有効期限が切れる前にコマンド実行結果が受信されない場合は、ステータスは自動的に `TIMED_OUT` に変わります。
+
```
aws iot-jobs-data start-command-execution \
--command-arn \
--target-arn \
--endpoint \
--execution-timeout-seconds 900
```
+ (オプション) 動的コマンドの場合は、置換に使用するパラメータとその値を指定します。コマンドの作成時に defaultValue が設定されていないパラメータの値を指定する必要があります。パラメータに defaultValue がある場合、ここで指定するパラメータ値が優先されます。valueConditions が設定されているパラメータの場合、ここで指定するパラメータ値は 条件を満たす必要があります。
`Light_Power_Status` 動的コマンドの例に基づく:
+
```
aws iot-jobs-data start-command-execution \
--command-arn arn:aws:iot:us-east-1:123456789012:command/Light_Power_Status \
--target-arn arn:aws:iot:us-east-1:123456789012:thing/exampleThing \
--endpoint \
--execution-timeout-seconds 900 \
--parameters "powerStatus={S=ON}"
```
このコマンドを実行すると、コマンド実行 ID が返されます。この ID を使用して、コマンド実行ステータス、詳細、およびコマンド実行履歴をクエリすることができます。
**注記**
コマンドが非推奨になった場合、`StartCommandExecution` API リクエストは検証の例外で失敗します。このエラーを修正するには、まず `UpdateCommand` API を使用してコマンドを復元してから、`StartCommandExecution` リクエストを実行します。
```
{
"executionId": "07e4b780-7eca-4ffd-b772-b76358da5542"
}
```
## コマンド実行の結果を更新する
コマンド実行のステータスまたは結果を更新するには、`UpdateCommandExecution` MQTT データプレーン API オペレーションを使用します。
**注記**
この API を使用する前に:
デバイスで MQTT 接続が確立されており、コマンドのリクエストとレスポンスのトピックがサブスクライブされている必要があります。詳細については、「[高レベルのコマンドワークフロー](iot-remote-command-workflow.md)」を参照してください。
`StartCommandExecution` API オペレーションを使用して、このコマンドがあらかじめ実行されている必要があります。
### サンプルの IAM ポリシー
この API オペレーションを使用する前に、デバイスがこれらのアクションを実行することを IAM ポリシーで許可していることを確認してください。以下に、デバイスがアクションを実行することを許可するポリシーの例を示しています。`UpdateCommandExecution` MQTT アクションを実行するアクセス許可をユーザーに付与する追加のサンプル IAM ポリシーについては、「」を参照してください[接続および公開ポリシーの例](connect-and-pub.md)。
この例では、次のように置き換えます。
+ `Region` など AWS リージョン、 で を使用します`us-east-1`。
+ `AccountID` を *`123456789012`* などの AWS アカウント 番号に置き換えます。
+ `ThingName` は、 など、コマンド実行をターゲットとする AWS IoT モノの名前で指定します*`myRegisteredThing`*。
+ `commands-request-topic` および AWS IoT コマンドリクエストおよびレスポンストピック`commands-response-topic`の名前。詳細については、「[高レベルのコマンドワークフロー](iot-remote-command-workflow.md)」を参照してください。
#### MQTT クライアント ID の IAM ポリシーの例
次のコードは、MQTT クライアント ID を使用する場合のデバイスポリシーの例を示しています。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:Publish",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/json"
]
},
{
"Effect": "Allow",
"Action": "iot:Receive",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/request",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/accepted",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/rejected",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/request/json",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/accepted/json",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/rejected/json"
]
},
{
"Effect": "Allow",
"Action": "iot:Subscribe",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/request",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/accepted",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/rejected",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/request/json",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/accepted/json",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/rejected/json"
]
},
{
"Effect": "Allow",
"Action": "iot:Connect",
"Resource": "arn:aws:iot:us-east-1:123456789012:client/${iot:ClientId}"
}
]
}
```
#### IoT のモノの IAM ポリシーの例
次のコードは、 AWS IoT のモノを使用する場合のデバイスポリシーの例を示しています。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:Publish",
"Resource": "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response"
},
{
"Effect": "Allow",
"Action": "iot:Receive",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/request",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/accepted",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/rejected",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/request/json",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/accepted/json",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/rejected/json"
]
},
{
"Effect": "Allow",
"Action": "iot:Subscribe",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/request",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/accepted",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/rejected",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/request/json",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/accepted/json",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/rejected/json"
]
},
{
"Effect": "Allow",
"Action": "iot:Connect",
"Resource": "arn:aws:iot:us-east-1:123456789012:client/${iot:ClientId}"
}
]
}
```
### `UpdateCommandExecution` API の使用方法
コマンド実行がリクエストトピックで受信されると、デバイスはコマンドを処理します。デバイスはその後、`UpdateCommandExecution` API を使用して、コマンド実行のステータスと結果を次のレスポンストピックに更新します。
```
$aws/commands///executions//response/
```
この例では、*``* はターゲットデバイスの一意の識別子であり、*``* はターゲットデバイスでのコマンド実行の識別子です。** は JSON または CBOR です。
**注記**
デバイスを に登録していない場合は AWS IoT、モノの名前の代わりにクライアント ID を識別子として使用できます。
```
$aws/commands/clients//executions//response/
```
#### 実行ステータスに対する更新をデバイスで報告する
デバイスは、API を使用することで、コマンド実行に対する以下のステータス更新を報告できます。これらのステータスの詳細については、「[コマンド実行ステータス](iot-remote-command-concepts.md#iot-command-execution-status)」を参照してください。
+ `IN_PROGRESS`: デバイスでコマンドの実行が開始されると、デバイスはステータスを `IN_PROGRESS` に更新できます。
+ `SUCCEEDED`: コマンドが正常に処理されて実行が完了すると、デバイスは応答トピックに `SUCCEEDED` としてメッセージを発行できます。
+ `FAILED`: コマンドの実行に失敗した場合は、デバイスはレスポンストピックに `FAILED` としてメッセージを発行できます。
+ `REJECTED`: デバイスがコマンドを受け入れなかった場合、デバイスはレスポンストピックに `REJECTED` としてメッセージを発行できます。
+ `TIMED_OUT`: コマンドの実行ステータスは、次のいずれかの理由で `TIMED_OUT` に変わる場合があります。
+ コマンド実行の結果が受信されなかった。これは、実行が指定された期間内に完了しなかったか、デバイスがレスポンストピックにステータス情報を発行できなかったために発生する可能性があります。
+ デバイスは、コマンドの実行を試行したときにタイムアウトが発生したことを報告します。
`TIMED_OUT` ステータスの詳細については、「[タイムアウト値と `TIMED_OUT` 実行ステータス](#iot-command-execution-timeout-status)」を参照してください。
#### `UpdateCommandExecution` API を使用するときの考慮事項
`UpdateCommandExecution` API を使用する際の重要な考慮事項を以下に示しています。
+ デバイスは、オプションの `statusReason` オブジェクトを使用して、実行に関する追加情報を提供できます。デバイスがこのオブジェクトを提供する場合、 オブジェクトの `reasonCode` フィールドは必須ですが、 `reasonDescription`フィールドはオプションです。
+ デバイスが `statusReason` オブジェクトを使用する場合、 は パターンを使用し`[A-Z0-9_-]+`、64 文字を超えないように`reasonCode`する必要があります。を指定する場合は`reasonDescription`、1,024 文字を超えないようにしてください。改行などのコントロール文字を除く任意の文字を使用できます。
+ デバイスは、オプションの `result` オブジェクトを使用することで、リモート関数呼び出しの戻り値など、コマンド実行の結果に関する情報を提供できます。`result` を指定する場合は、少なくとも 1 つのエントリが必要です。
+ `result` フィールドでは、エントリをキーと値のペアとして指定します。エントリごとに、データ型情報を文字列、ブール値、またはバイナリとして指定する必要があります。文字列データ型はキー `s` を使用し、ブール値データ型はキー `b` を使用し、バイナリデータ型はキー `bin` を使用する必要があります。これらのキーが小文字であることを確認します。
+ `UpdateCommandExecution` API の実行中にエラーが発生した場合は、Amazon CloudWatch の `AWSIoTLogsV2` ロググループでエラーを表示できます。ログの有効化とログの表示については、「[AWS IoT ログ記録の設定](configure-logging.md)」を参照してください。
#### `UpdateCommandExecution` API の例
次のコードは、デバイスが `UpdateCommandExecution` API を使用して実行ステータスを報告する方法の例を示しています。`statusReason` フィールドには、ステータスに関する追加情報が提供され、result フィールドには、この例の場合は自動車のバッテリー残量のパーセントなど、実行の結果に関する情報が提供されます。
```
{
"status": "IN_PROGRESS",
"statusReason": {
"reasonCode": "200",
"reasonDescription": "Execution_in_progress"
},
"result": {
"car_battery": {
"s": "car battery at 50 percent"
}
}
}
```
## コマンド実行を取得する
コマンドを実行したら、 AWS IoT コンソールと を使用してコマンド実行に関する情報を取得できます AWS CLI。取得できる情報は次のとおりです。
**注記**
最新のコマンド実行ステータスを取得するには、以下で説明するように、デバイスが `UpdateCommandExecution` MQTT API を使用してレスポンストピックにステータス情報を発行する必要があります。デバイスがこのトピックに発行するまで、`GetCommandExecution` API はステータスを `CREATED` または `TIMED_OUT` として報告します。
作成する各コマンドの実行には以下が含まれます。
+ **実行 ID**。これはコマンド実行の一意の識別子です。
+ コマンド実行の**ステータス**。ターゲットデバイスでコマンドを実行すると、コマンド実行は `CREATED` ステータスになります。その後、以下で説明するように、他のコマンド実行ステータスに移行できます。
+ コマンド実行の**結果**。
+ 一意の**コマンド ID** と、実行が作成されたターゲットデバイス。
+ **開始日**。コマンド実行が作成された日時を示します。
### コマンド実行を取得する (コンソール)
次のいずれかの方法を使用して、コンソールからコマンド実行を取得できます。
+
**[コマンドハブ] ページから**
AWS IoT コンソールの [コマンドハブ](https://console.aws.amazon.com/iot/home#/commandHub)ページに移動し、以下の手順を実行します。
1. ターゲットデバイスで実行を作成したコマンドを選択します。
1. コマンドの詳細ページの **[コマンド履歴]** タブに、作成した実行が表示されます。情報を取得する実行を選択します。
1. デバイスが `UpdateCommandExecution` API を使用して結果情報を提供した場合は、このページの **[結果]** タブでこの情報を確認できます。
+
**[モノのハブ] ページから**
コマンドの実行時にターゲットデバイスとして AWS IoT モノを選択した場合は、モノのハブページから実行の詳細を表示できます。
1. AWS IoT コンソールの [Thing Hub ](https://console.aws.amazon.com/iot/home#/thinghub)ページに移動し、コマンド実行を作成したモノを選択します。
1. モノの詳細ページの **[コマンド履歴]** に、作成した実行が表示されます。情報を取得する実行を選択します。
1. デバイスが `UpdateCommandExecution` API を使用して結果情報を提供した場合は、このページの **[結果]** タブでこの情報を確認できます。
### コマンド実行を取得する (CLI)
[https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommandExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommandExecution.html) AWS IoT Core コントロールプレーンの HTTP API オペレーションを使用して、コマンド実行に関する情報を取得します。`StartCommandExecution` API オペレーションを使用して、このコマンドがあらかじめ実行されている必要があります。
#### サンプルの IAM ポリシー
この API オペレーションを使用する前に、デバイスでこのアクションを実行することを IAM ポリシーが許可していることを確認してください。以下に、`GetCommandExecution` アクションの実行をユーザーに許可する IAM ポリシーの例を示しています。
この例では、次のように置き換えます。
+ `region` を `us-east-1` などお客様ご自身の AWS リージョンに置き換えます。
+ `account-id` を `123456789012` などの AWS アカウント 番号に置き換えます。
+ `command-id` などの一意の AWS IoT コマンド識別子を使用します`LockDoor`。
+ `devices` デバイスが AWS IoT モノとして登録されているか、MQTT クライアントとして指定されているか`client`に応じて、 `thing`または のいずれかを使用します。
+ `device-id` `thing-name`または AWS IoT を使用します`client-id`。
```
{
"Effect": "Allow",
"Action": [
"iot:GetCommandExecution"
],
"Resource": [
"arn:aws:iot:region:account-id:command/command-id",
"arn:aws:iot:region:account-id:devices/device-id"
]
}
```
#### コマンド実行を取得する例
次の例は、 コマンドを使用して実行された`start-command-execution` AWS CLI コマンドに関する情報を取得する方法を示しています。次の例では、ステアリングホイールモードをオフにするために実行されたコマンドに関する情報を取得する方法が示されています。
この例では、次のように置き換えます。
+ *``* を情報を取得するコマンド実行の識別子に置き換えます。
+ *``* を実行のターゲットとするデバイスの Amazon リソース番号 (ARN) に置き換えます。この情報は、`start-command-execution` CLI コマンドのレスポンスから取得できます。
+ オプションで、デバイスが `UpdateCommandExection` API を使用して実行結果を提供した場合、`GetCommandExecution` API を使用して `GetCommandExecution` API のレスポンスにコマンド実行結果を含めるかどうかを指定できます。
```
aws iot get-command-execution
--execution-id \
--target-arn \
--include-result
```
このコマンドを実行すると、コマンド実行の ARN、実行ステータス、実行開始時刻、完了時刻に関する情報を含むレスポンスが生成されます。また、ステータスに関する追加情報を含む `statusReason` オブジェクトも提供されます。それぞれのステータスとステータスの理由については、「[コマンド実行ステータス](iot-remote-command-concepts.md#iot-command-execution-status)」を参照してください。
次のコードは、API リクエストからのレスポンスの例を示しています。
**注記**
実行レスポンスの `completedAt` フィールドは、デバイスが終了ステータスをクラウドに報告する時間に対応します。`TIMED_OUT` ステータスの場合、このフィールドはデバイスがタイムアウトを報告した場合にのみ設定されます。`TIMED_OUT` ステータスがクラウドによって設定された場合は、`TIMED_OUT` ステータスは更新されません。このタイムアウトの動作の詳細については、「[コマンド実行のタイムアウトに関する考慮事項](#iot-command-execution-timeout)」を参照してください。
```
{
"executionId": "07e4b780-7eca-4ffd-b772-b76358da5542",
"commandArn": "arn:aws:iot:us-east-1:123456789012:command/LockDoor",
"targetArn": "arn:aws:iot:us-east-1:123456789012:thing/myRegisteredThing",
"status": "SUCCEEDED",
"statusReason": {
"reasonCode": "DEVICE_SUCCESSFULLY_EXECUTED",
"reasonDescription": "SUCCESS"
},
"result": {
"sn": { "s": "ABC-001" },
"digital": { "b": true }
},
"createdAt": "2024-03-23T00:50:10.095000-07:00",
"completedAt": "2024-03-23T00:50:10.095000-07:00"
}
```
## MQTT テストクライアントを使用したコマンドの更新の表示
MQTT テストクライアントを使用すると、コマンド機能を使用の際に、MQTT 経由でのメッセージの送受信を表示できます。デバイスが との MQTT 接続を確立したら AWS IoT、コマンドを作成してペイロードを指定し、デバイスで実行できます。コマンドを実行すると、デバイスがコマンドの MQTT 予約済みリクエストトピックをサブスクライブしている場合、このトピックに発行されたペイロードメッセージが表示されます。
その後、デバイスはペイロードの指示を受け取り、 AWS IoT デバイスで指定されたオペレーションを実行します。次に、 `UpdateCommandExecution` API を使用してコマンド実行結果とステータス情報を command. AWS IoT Device Management listens の MQTT 予約レスポンストピックに発行し、レスポンストピックを更新して更新された情報を保存し、 AWS CloudTrail と Amazon CloudWatch にログを発行します。その後、コンソールから、または `GetCommandExecution` API を使用して、最新のコマンド実行情報を取得できます。
次の手順は、MQTT テストクライアントを使用してメッセージを観察する方法を示しています。
1. AWS IoT コンソールで [MQTT テストクライアント](https://console.aws.amazon.com/iot/home#/test)を開きます。
1. **Subscribe** タブで、次のトピックを入力し、**Subscribe** を選択します。** は、登録したデバイスのモノの名前です AWS IoT。
**注記**
デバイスのモノの名前は、 AWS IoT コンソールの [Thing Hub ](https://console.aws.amazon.com/iot/home#/thinghub)ページから確認できます。デバイスをモノとして登録していない場合は、Connect device ページ AWS IoT から に接続するときにデバイスを登録できます。 [https://console.aws.amazon.com/iot/home#/connect-overview](https://console.aws.amazon.com/iot/home#/connect-overview)
```
$aws/commands/things//executions/+/request
```
1. (オプション) **[サブスクライブ]** タブで、次のトピックを入力し、**[サブスクライブ]** を選択することもできます。
```
$aws/commands/things/+/executions/+/response/accepted/json
$aws/commands/things/+/executions/+/response/rejected/json
```
1. コマンド実行が開始されると、デバイスがサブスクライブしているリクエストトピック `$aws/commands/things//executions/+/request` を使用して、メッセージペイロードがデバイスに送信されます。MQTT テストクライアントには、デバイスがコマンドを処理する手順を含むコマンドペイロードが表示されます。
1. コマンドの実行を開始した後、デバイスは、次の MQTT 予約済みレスポンストピックにコマンドのステータス更新を発行することができます。
```
$aws/commands///executions//response/json
```
例えば、車の空調をオンにして温度を目的の値まで下げるために実行したコマンドを考えてみましょう。次の JSON は、車両がレスポンストピックに発行した、コマンドの実行に失敗したことを示すサンプルメッセージです。
```
{
"deviceId": "My_Car",
"executionId": "07e4b780-7eca-4ffd-b772-b76358da5542",
"status": "FAILED",
"statusReason": {
"reasonCode": "CAR_LOW_ON_BATTERY",
"reasonDescription": "Car battery is lower than 5 percent"
}
}
```
この場合、車のバッテリーを充電した後に、コマンドを再度実行できます。
## でコマンド実行を一覧表示する AWS アカウント
コマンドを実行したら、 AWS IoT コンソールと を使用してコマンド実行に関する情報を取得できます AWS CLI。取得できる情報は次のとおりです。
+ **実行 ID**。これはコマンド実行の一意の識別子です。
+ コマンド実行の**ステータス**。ターゲットデバイスでコマンドを実行すると、コマンド実行は `CREATED` ステータスになります。その後、以下で説明するように、他のコマンド実行ステータスに移行できます。
+ 一意の**コマンド ID** と、実行が作成されたターゲットデバイス。
+ **開始日**。コマンド実行が作成された日時を示します。
### アカウントのコマンド実行を一覧表示する (コンソール)
次のいずれかの方法を使用して、コンソールからすべてのコマンド実行を表示できます。
+
**[コマンドハブ] ページから**
AWS IoT コンソールの [コマンドハブ](https://console.aws.amazon.com/iot/home#/commandHub)ページに移動し、以下の手順を実行します。
1. ターゲットデバイスで実行を作成したコマンドを選択します。
1. コマンドの詳細ページで、**[コマンド履歴]** タブに移動すると、作成した実行が一覧表示されます。
+
**[モノのハブ] ページから**
コマンドの実行時にターゲットデバイスとして AWS IoT モノを選択し、1 つのデバイスに複数のコマンド実行を作成した場合は、モノのハブページからデバイスの実行を表示できます。
1. AWS IoT コンソールの [Thing Hub ](https://console.aws.amazon.com/iot/home#/thinghub)ページに移動し、実行を作成したモノを選択します。
1. モノの詳細ページの **[コマンド履歴]** に、デバイスに対して作成した実行のリストが表示されます。
### アカウントのコマンド実行を一覧表示する (CLI)
[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 オペレーションを使用して、アカウント内のすべてのコマンド実行を一覧表示します。
#### サンプルの IAM ポリシー
この API オペレーションを使用する前に、デバイスでこのアクションを実行することを IAM ポリシーが許可していることを確認してください。以下に、`ListCommandExecutions` アクションの実行をユーザーに許可する IAM ポリシーの例を示しています。
この例では、次のように置き換えます。
+ `region` を `us-east-1` などお客様ご自身の AWS リージョンに置き換えます。
+ `account-id` を `123456789012` などの AWS アカウント 番号に置き換えます。
+ `command-id` などの一意の AWS IoT コマンド識別子を使用します`LockDoor`。
```
{
"Effect": "Allow",
"Action": "iot:ListCommandExecutions",
"Resource": *
}
```
#### コマンド実行を一覧表示する例
次の例は、 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"
}
]
}
```
それぞれのステータスとステータスの理由については、「[コマンド実行ステータス](iot-remote-command-concepts.md#iot-command-execution-status)」を参照してください。
## コマンド実行を削除する
コマンド実行が不要になった場合は、アカウントから完全に削除することができます。
**注記**
コマンド実行は、`SUCCEEDED`、`FAILED`、`REJECTED` などの終了ステータスになった場合にのみ削除できます。
このオペレーションは、 AWS IoT Core API または を使用してのみ実行できます AWS CLI。これはコンソールからは利用できません。
### サンプルの IAM ポリシー
この API オペレーションを使用する前に、デバイスがこれらのアクションを実行することを IAM ポリシーで許可していることを確認してください。以下に、デバイスがアクションを実行することを許可するポリシーの例を示しています。
この例では、次のように置き換えます。
+ `Region` など AWS リージョン、 で を使用します`us-east-1`。
+ `AccountID` を *`123456789012`* などの AWS アカウント 番号に置き換えます。
+ `CommandID` を実行を削除するコマンドの識別子に置き換えます。
+ `devices` デバイスが AWS IoT モノとして登録されているか、MQTT クライアントとして指定されているか`client`に応じて、 `thing`または のいずれかを使用します。
+ `device-id` `thing-name`または AWS IoT を使用します`client-id`。
```
{
"Effect": "Allow",
"Action": [
"iot:DeleteCommandExecution"
],
"Resource": [
"arn:aws:iot:region:account-id:command/command-id",
"arn:aws:iot:region:account-id:devices/device-id"
]
}
```
### コマンド実行を削除する例
次の例は、 コマンドを使用して`delete-command` AWS CLI コマンドを削除する方法を示しています。用途に応じて、*``* を削除するコマンド実行の識別子に置き換え、*``* をターゲットデバイスの ARN に置き換えてください。
```
aws iot delete-command-execution \
--execution-id \
--target-arn
```
API リクエストが成功すると、コマンド実行は 200 のステータスコードを生成します。`GetCommandExecution` API を使用して、コマンド実行がアカウントに存在していないことを確認できます。
# コマンドリソースを非推奨にする
コマンドを非推奨にして、古いため使用しないでください。例えば、同じ ID でペイロードが異なる新しいコマンドを作成するときに、コマンドがアクティブに維持されなくなった場合や、非推奨になります。
## 主な考慮事項
コマンドを廃止する際の重要な考慮事項:
+ コマンドを非推奨にしても削除されません。コマンドは、その ID を使用して取得し、再利用のために復元できます。
+ 廃止されたコマンドで新しい実行を開始しようとすると、エラーが生成され、古いコマンドが使用できなくなります。
+ 廃止されたコマンドを実行するには、まず復元します。復元後、コマンドはターゲットデバイスで定期的に使用および実行できるようになります。
+ 実行中にコマンドを非推奨にすると、完了するまで実行が継続されます。実行ステータスは引き続き取得できます。
## コマンドリソースを非推奨にする (コンソール)
コンソールからコマンドを非推奨にするには、 AWS IoT コンソールの [コマンドハブ](https://console.aws.amazon.com/iot/home#/commandHub)に移動し、次の手順を実行します。
1. 非推奨にするコマンドを選択し、**アクション**で**非推奨**を選択します。
1. コマンドを非推奨にすることを確認し、**[非推奨]** を選択します。
## コマンドリソースを非推奨にする(CLI)
`update-command` CLI を使用して、コマンドを非推奨としてマークします。削除する前にコマンドを非推奨にする必要があります。廃止されたコマンドを使用するには、まず復元します。
```
aws iot update-command \
--command-id \
--deprecated
```
たとえば、上記の例で更新した `ACSwitch` コマンドを非推奨にした場合、次のコードはこのコマンドを実行した際のサンプル出力を示しています。
```
{
"commandId": "turnOffAc",
"deprecated": true,
"lastUpdatedAt": "2024-05-09T23:16:51.370000-07:00"
}
```
## 非推奨の時間とステータスを確認する
`GetCommand` API を使用して、コマンドが廃止されたかどうか、および最後に廃止された日時を決定します。
```
aws iot get-command --command-id
```
このコマンドは、最後に更新されたフィールドの作成と廃止のタイムスタンプなど、コマンド情報を含むレスポンスを生成します。これにより、コマンドの有効期間と、それを削除するか再利用するかが決まります。コマンドのレスポンスの例を次に示します`turnOffAc`。
```
{
"commandId": "turnOffAC",
"commandArn": "arn:aws:iot:us-east-1:123456789012:command/turnOffAC",
"namespace": "AWS-IoT",
"payload": {
"content": "testPayload.json",
"contentType": "application/json"
},
"createdAt": "2024-03-23T00:50:10.095000-07:00",
"lastUpdatedAt": "2024-05-09T23:16:51.370000-07:00",
"deprecated": false
}
```
## コマンドリソースを復元する
`ACSwitch` コマンドを使用またはデバイスに送信するには、最初に復元します。
コンソールからコマンドを復元するには、 AWS IoT コンソールの [コマンドハブ](https://console.aws.amazon.com/iot/home#/commandHub)に移動し、復元するコマンドを選択し、**アクション**で**復元**を選択します。
AWS IoT Core API または を使用してコマンドを復元するには AWS CLI、 `UpdateCommand` API オペレーションまたは CLI `update-command` を使用します。以下の例は、リクエストとレスポンスの例を示しています。
```
aws iot update-command \
--command-id
--no-deprecated
```
次の例は、出力の例を示しています。
```
{
"commandId": "ACSwitch",
"deprecated": false,
"lastUpdatedAt": "2024-05-09T23:17:21.954000-07:00"
}
```