翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # コマンドの概念とステータス 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 ログを使用して、問題をトラブルシューティングします。