高レベルのコマンドワークフロー - AWS IoT Core
コマンドの作成と管理ターゲットを選択してトピックをサブスクライブするコマンド実行を開始してモニタリングする(オプション) コマンドイベントの通知を有効にする

高レベルのコマンドワークフロー

以下の手順は、デバイスとコマンド間の AWS IoT Device Management のコマンドワークフローの概要を示しています。コマンド HTTP API オペレーションのいずれかを使用すると、リクエストは Sigv4 認証情報を使用して署名されます。

AWS IoT Device Management デバイスコマンドの高レベルワークフローの概要。

コマンドの作成と管理

デバイスのコマンドを作成および管理するには、次の手順を実行します。

  1. コマンドリソースを作成する

    デバイスにコマンドを送信する前に、AWS IoT コンソールのコマンドハブから、または CreateCommand コントロールプレーン API オペレーションを使用してコマンドリソースを作成します。

  2. ペイロードを指定する

    コマンドの作成時に、コマンドのペイロードを指定する必要があります。ペイロードのコンテンツには、任意の形式を使用できます。デバイスがペイロードを正しく解釈するように、ペイロードのコンテンツタイプも指定することをお勧めします。

  3. (オプション) 作成したコマンドを管理する

    コマンドを作成した後に、コマンドの表示名と説明を更新することができます。今後使用する予定がなくなった場合は、コマンドを非推奨としてマークするか、アカウントからコマンドを完全に削除することもできます。ペイロード情報を変更する場合は、新しいコマンドを作成して、新しいペイロードファイルをアップロードする必要があります。

コマンドのターゲットデバイスを選択して MQTT トピックをサブスクライブする

コマンドワークフローを準備するには、ターゲットデバイスを選択し、コマンドを受信してレスポンスメッセージを発行するための AWS IoT 予約済み MQTT トピックを指定します。

  1. コマンドのターゲットデバイスを選択する

    コマンドワークフローを準備するには、コマンドを受信して指定されたアクションを実行するための、ターゲットデバイスを選択します。ターゲットデバイスには、AWS IoT レジストリに登録した AWS IoT のモノを指定するか、デバイスが AWS IoT に登録されていない場合は MQTT クライアント ID を使用して指定することもできます。詳細については、「ターゲットデバイスに関する考慮事項」を参照してください。

  2. IoT デバイスポリシーを設定する

    デバイスがコマンド実行を受信して更新を発行する前に、これらのアクションを実行するためのアクセス許可を付与する IAM ポリシーを使用する必要があります。デバイスが AWS IoT のモノとして登録されているか、MQTT クライアント ID として指定されているかに応じた使用可能なサンプルポリシーの例については、「サンプルの IAM ポリシー」を参照してください。

  3. MQTT 接続を確立する

    コマンド機能を使用するようにデバイスを準備するために、デバイスはまずメッセージブローカーに接続し、リクエストとレスポンスのトピックをサブスクライブする必要があります。デバイスは、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
  4. コマンドトピックにサブスクライブする

    接続が確立されると、デバイスはコマンドリクエストトピックにサブスクライブできます。コマンドを作成してターゲットデバイスでコマンド実行を開始すると、ペイロードメッセージは、メッセージブローカーによってリクエストトピックに発行されます。その後、デバイスはペイロードメッセージを受信し、コマンドを処理することができます。

    (オプション) デバイスは、これらのコマンドレスポンストピック (accepted または rejected) をサブスクライブして、クラウドサービスがデバイスからのレスポンスを承諾したか拒否したかを示すメッセージを受信することもできます。

    この例では、次のように置き換えます。

    • <device> を、ターゲットとするデバイスが IoT のモノとして登録されているか、MQTT クライアントとして指定されているかに応じて、thing または client に置き換えます。

    • <DeviceID> をターゲットデバイスの一意の識別子に置き換えます。この ID には、一意の MQTT クライアント ID またはモノの名前を使用することができます。

    注記

    ペイロードタイプが JSON または CBOR でない場合は、コマンドリクエストトピックに <PayloadFormat> フィールドが存在しない可能性があります。ペイロード形式を取得するには、MQTT 5 を使用して MQTT メッセージヘッダーから形式情報を取得することをお勧めします。詳細については、「コマンドトのピック」を参照してください。

    $aws/commands/<devices>/<DeviceID>/executions/+/request/<PayloadFormat>
$aws/commands/<devices>/<DeviceID>/executions/+/response/accepted/<PayloadFormat>
$aws/commands/<devices>/<DeviceID>/executions/+/response/rejected/<PayloadFormat>

ターゲットデバイスのコマンド実行を開始してモニタリングする

コマンドを作成し、コマンドのターゲットを指定したら、次の手順を実行してターゲットデバイスで実行を開始できます。

  1. ターゲットデバイスでコマンド実行を開始する

    AWS IoT コンソールのコマンドハブから、またはアカウント固有のエンドポイントで StartCommandExecution データプレーン API を使用して、ターゲットデバイスでコマンド実行を開始します。デュアルスタックエンドポイント (IPv4 と IPv6) を使用している場合は、iot:Data-ATS を使用します。iot:Jobs エンドポイントは IPv4 専用です。

    API は、デバイスがサブスクライブした上述のコマンドリクエストトピックにペイロードメッセージを発行します。

    注記

    コマンドがクラウドから送信されたときにデバイスがオフラインで、MQTT 永続セッションを使用している場合は、コマンドはメッセージブローカーで待機します。デバイスがタイムアウト期間前にオンラインに戻り、コマンドリクエストトピックをサブスクライブしている場合、デバイスはコマンドを処理して、その結果をコマンドレスポンストピックに発行できます。タイムアウト期間前にデバイスがオンラインに戻らない場合は、コマンドの実行はタイムアウトし、ペイロードメッセージは期限切れになって、メッセージブローカーによって破棄される可能性があります。

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

    これで、デバイスはペイロードメッセージを受信し、コマンドを処理して指定されたアクションを実行し、UpdateCommandExecution API を使用してコマンド実行の結果を次のコマンドレスポンストピックに発行できるようになりました。デバイスがレスポンストピックを受け入れたコマンドと拒否したコマンドにサブスクライブしている場合は、レスポンスがクラウドサービスによって受け入れられたか拒否されたかを示すメッセージがデバイスに送信されます。

    リクエストトピックで指定した内容に応じて、<devices> はモノまたはクライアントにすることができ、<DeviceID> は IoT のモノの名前、または MQTT クライアント ID にすることができます。

    注記

    <PayloadFormat> は、コマンドレスポンストピックで JSON または CBOR のみを使用できます。

    $aws/commands/<devices>/<DeviceID>/executions/<ExecutionId>/response/<PayloadFormat>
  3. (オプション) コマンド実行結果を取得する

    コマンド実行の結果を取得するには、AWS IoT コンソールからコマンド履歴を表示するか、GetCommandExecution コントロールプレーン API オペレーションを使用します。最新のステータス情報を取得するには、デバイスがコマンド実行結果をレスポンストピックに発行している必要があります。また、最後に更新された日時、実行結果、実行が完了した日時など、実行データに関する追加情報を取得することもできます。

(オプション) コマンドイベントの通知を有効にする

コマンドイベントにサブスクライブして、コマンド実行のステータスが変更されたときに通知を受け取ることができます。次の手順は、コマンドイベントにサブスクライブして処理する方法を示しています。

  1. トピックルールを作成する

    コマンドイベントトピックにサブスクライブして、コマンド実行のステータスが変更されたときに通知を受け取ることができます。トピックルールを作成して、デバイスによって処理されたデータを、AWS Lambda、Amazon SQS、AWS Step Functions などのルールでサポートされている他の AWS IoT サービスにルーティングすることもできます。トピックルールは、AWS IoT コンソール、または CreateTopicRule AWS IoT Core コントロールプレーン API オペレーションのいずれかを使用して作成できます。詳細については、「AWS IoT ルールの作成」を参照してください。

    この例では、<CommandID> を通知を受信するコマンドの識別子に置き換え、<CommandExecutionStatus> をコマンド実行のステータスに置き換えます。

    $aws/events/commandExecution/<CommandID>/<CommandExecutionStatus>
    注記

    すべてのコマンドとコマンド実行ステータスの通知を受け取るには、ワイルドカード文字を使用し、次のトピックにサブスクライブします。

    $aws/events/commandExecution/+/#
  2. コマンドイベントを受信して処理する

    前のステップでコマンドイベントにサブスクライブするトピックルールを作成した場合は、受信したコマンドプッシュ通知を管理し、これらのサービス上にアプリケーションを構築することができます。

次のコードは、受信するコマンドイベント通知のサンプルペイロードを示しています。

{
    "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
}