シャドウとの相互作用 - AWS IoT Core

英語の翻訳が提供されている場合で、内容が矛盾する場合には、英語版がオリジナルとして取り扱われます。翻訳は機械翻訳により提供されています。

シャドウとの相互作用

このトピックでは、シャドウを操作するために AWS IoT が提供する 3 つの方法のそれぞれに関連するメッセージについて説明します。これらの方法には、次のものがあります。

UPDATE

存在しない場合はシャドウを作成します。メッセージ本文に指定された状態情報で既存のシャドウの内容を更新します。AWS IoT は、更新ごとにタイムスタンプを記録して、状態が最後に更新された日時を示します。シャドウの状態が変化すると、AWS IoT はすべての MQTT サブスクライバに desired 状態と reported 状態の違いを示す /delta メッセージを送信します。/delta メッセージを受信するデバイスまたはアプリは、違いに基づいてアクションを実行できます。たとえば、デバイスは自らの状態を desired 状態に更新でき、アプリケーションはデバイスの状態の変更を表示するようにその UI を更新できます。

GET

メタデータを含むシャドウの完全な状態を含む現在のシャドウドキュメントを取得します。

DELETE

シャドウとそのすべてのコンテンツを削除します。削除したデバイスのシャドウを復元することはできませんが、同じ名前で新しいシャドウを作成することはできます。

プロトコルのサポート

AWS IoT は、MQTT および HTTPS プロトコル経由の REST API をサポートし、シャドウと対話します。AWS IoT は、MQTT 発行アクションとサブスクライブアクション用に予約されたリクエストとレスポンスのトピックを提供します。デバイスおよびアプリは、AWS IoT リクエストの処理方法に関する情報についてリクエストトピックを発行する前に、レスポンストピックをサブスクライブする必要があります。詳細については、「Device Shadow MQTT トピック」および「デバイスシャドウREST API」を参照してください。

状態の要求と報告

AWS IoT とシャドウを使用して IoT ソリューションを設計する場合、変更を要求するアプリやデバイスと、それらを実装するアプリやデバイスを決定する必要があります。通常、デバイスは変更をシャドウに実装して報告し、アプリとサービスはシャドウの変更に応答して要求します。ソリューションは異なる場合がありますが、このトピックの例では、クライアントアプリまたはサービスがシャドウの変更を要求し、デバイスがその変更を実行してシャドウに報告することを前提としています。

シャドウの更新

アプリまたはサービスは、UpdateThingShadow API を使用するか、update トピックに発行することで、シャドウの状態を更新できます。更新は、リクエストで指定したフィールドにのみ反映されます。

クライアントが状態の変更を要求したときのシャドウの更新

クライアントが MQTT プロトコルを使用してシャドウの状態の変更を要求した場合

  1. クライアントには、変更するプロパティを識別できるように、現在のシャドウドキュメントが必要です。現在のシャドウドキュメントを取得する方法については、/get アクションを参照してください。

  2. クライアントは、次の MQTT トピックにサブスクライブします。

    • $aws/things/thingName/shadow/name/shadowName/update/accepted

    • $aws/things/thingName/shadow/name/shadowName/update/rejected

    • $aws/things/thingName/shadow/name/shadowName/update/delta

    • $aws/things/thingName/shadow/name/shadowName/update/documents

  3. クライアントは、シャドウの desired 状態を含む状態ドキュメントを持つ $aws/things/thingName/shadow/name/shadowName/update リクエストトピックを発行します。変更するプロパティのみをドキュメントに含める必要があります。これは、desired 状態のドキュメントの例です。

    { "state": { "desired": { "color": { "r": 10 }, "engine": "ON" } } }
  4. 更新リクエストが有効な場合、AWS IoT はシャドウ内の desired 状態を更新し、次のトピックに関するメッセージを発行します。

    • $aws/things/thingName/shadow/name/shadowName/update/accepted

    • $aws/things/thingName/shadow/name/shadowName/update/delta

    /update/accepted メッセージには /accepted レスポンス状態ドキュメント シャドウドキュメントが含まれ、 /update/delta メッセージには /delta レスポンス状態ドキュメント シャドウドキュメントが含まれます。

  5. 更新リクエストが有効でない場合、AWS IoT は、エラーを説明する エラーレスポンスドキュメント シャドウドキュメントを含む $aws/things/thingName/shadow/name/shadowName/update/rejected トピックを持つメッセージを発行します。

クライアントが API を使用してシャドウの状態の変更を要求した場合

  1. クライアントは、メッセージ本文として リクエスト状態ドキュメント 状態ドキュメントを持つ UpdateThingShadow API を呼び出します。

  2. リクエストが有効な場合、AWS IoT はレスポンスメッセージ本文として HTTP 成功レスポンスコードと /accepted レスポンス状態ドキュメント シャドウドキュメントを返します。

    AWS IoT は、サブスクライブするデバイスまたはクライアント用の /delta レスポンス状態ドキュメント シャドウドキュメントを含む $aws/things/thingName/shadow/name/shadowName/update/delta トピックに MQTT メッセージを発行します。

  3. リクエストが有効でない場合、AWS IoT はレスポンスメッセージ本文として HTTP エラーレスポンスコードと エラーレスポンスドキュメント を返します。

デバイスが /update/delta トピックに関する /desired 状態を受信すると、デバイス内で必要な変更を行います。次に、/update トピックにメッセージが送信され、現在の状態がシャドウに報告されます。

デバイスが現在の状態を報告したときにシャドウを更新する

デバイスが MQTT プロトコルを使用して現在の状態をシャドウに報告する場合

  1. デバイスは、シャドウを更新する前に、次の MQTT トピックにサブスクライブする必要があります。

    • $aws/things/thingName/shadow/name/shadowName/update/accepted

    • $aws/things/thingName/shadow/name/shadowName/update/rejected

    • $aws/things/thingName/shadow/name/shadowName/update/delta

    • $aws/things/thingName/shadow/name/shadowName/update/documents

  2. デバイスは、この例のように、現在の状態を報告する $aws/things/thingName/shadow/name/shadowName/update トピックにメッセージを発行することによって、現在の状態を報告します。

    { "state": { "reported" : { "color" : { "r" : 10 }, "engine" : "ON" } } }
  3. AWS IoT が更新を受け入れると、/accepted レスポンス状態ドキュメント シャドウドキュメントを含む $aws/things/thingName/shadow/name/shadowName/update/accepted トピックにメッセージが発行されます。

  4. 更新リクエストが有効でない場合、AWS IoT は、エラーを説明する エラーレスポンスドキュメント シャドウドキュメントを含む $aws/things/thingName/shadow/name/shadowName/update/rejected トピックを持つメッセージを発行します。

デバイスが API を使用して現在の状態をシャドウに報告する場合

  1. デバイスは、メッセージ本文として リクエスト状態ドキュメント 状態ドキュメントを持つ UpdateThingShadow API を呼び出します。

  2. リクエストが有効な場合、AWS IoT はシャドウを更新し、レスポンスメッセージ本文として /accepted レスポンス状態ドキュメント シャドウドキュメントを持つ HTTP 成功レスポンスコードを返します。

    AWS IoT は、サブスクライブするデバイスまたはクライアント用の /delta レスポンス状態ドキュメント シャドウドキュメントを含む $aws/things/thingName/shadow/name/shadowName/update/delta トピックに MQTT メッセージを発行します。

  3. リクエストが有効でない場合、AWS IoT はレスポンスメッセージ本文として HTTP エラーレスポンスコードと エラーレスポンスドキュメント を返します。

オプティミスティックロック

状態ドキュメントのバージョンを使用して、デバイスのシャドウドキュメントの最新バージョンを更新していることを確認できます。更新リクエストでバージョンを渡したとき、そのバージョンと状態ドキュメントの現在のバージョンとが一致しない場合、サービスは HTTP 409 conflict レスポンスコードでリクエストを拒否します。

たとえば、 と指定します。

初期ドキュメント:

{ "state": { "desired": { "colors": [ "RED", "GREEN", "BLUE" ] } }, "version": 10 }

更新: (バージョンが一致しないと、リクエストは拒否される)

{ "state": { "desired": { "colors": [ "BLUE" ] } }, "version": 9 }

結果

{ "code": 409, "message": "Version conflict", "clientToken": "426bfd96-e720-46d3-95cd-014e3ef12bb6" }

更新: (バージョンが一致すると、リクエストは受け入れられる)

{ "state": { "desired": { "colors": [ "BLUE" ] } }, "version": 10 }

最終状態:

{ "state": { "desired": { "colors": [ "BLUE" ] } }, "version": 11 }

シャドウキュメントの取得

シャドウドキュメントは、GetThingShadow API を使用するか、get トピックをサブスクライブして発行することによって取得できます。これにより、desired 状態と reported 状態の間の delta を含む、完全なシャドウドキュメントが取得されます。このタスクの手順は、デバイスまたはクライアントがリクエストを行っているかどうかにかかわらず同じです。

MQTT プロトコルを使用してシャドウドキュメントを取得するには

  1. デバイスまたはクライアントは、シャドウを更新する前に、次の MQTT トピックにサブスクライブする必要があります。

    • $aws/things/thingName/shadow/name/shadowName/get/accepted

    • $aws/things/thingName/shadow/name/shadowName/get/rejected

  2. デバイスまたはクライアントは、空のメッセージ本文を持つ $aws/things/thingName/shadow/name/shadowName/get トピックにメッセージを発行します。

  3. リクエストが成功すると、AWS IoT はメッセージ本文に /accepted レスポンス状態ドキュメント を含むメッセージを $aws/things/thingName/shadow/name/shadowName/get/accepted トピックに発行します。

  4. リクエストが有効でない場合、AWS IoT は、メッセージ本文に エラーレスポンスドキュメント を含むメッセージを $aws/things/thingName/shadow/name/shadowName/get/rejected トピックに発行します。

REST API を使用してシャドウドキュメントを取得するには

  1. デバイスまたはクライアントは、空のメッセージ本文で GetThingShadow API を呼び出します。

  2. リクエストが有効な場合、AWS IoT は、レスポンスメッセージ本文として /accepted レスポンス状態ドキュメント シャドウドキュメントを持つ HTTP 成功レスポンスコードを返します。

  3. リクエストが有効でない場合、AWS IoT はレスポンスメッセージ本文として HTTP エラーレスポンスコード エラーレスポンスドキュメント を返します。

シャドウデータの削除

シャドウデータを削除するには、シャドウドキュメント内の特定のプロパティを削除する方法と、シャドウを完全に削除する方法の 2 つがあります。

  • 特定のプロパティをシャドウから削除するには、シャドウを更新します。ただし、削除するプロパティの値を null。 値 を持つフィールド null シャドードキュメントから削除されます。

  • シャドウ全体を削除するには、DeleteThingShadow API を使用するか、delete トピックに発行します。

シャドウドキュメントからのプロパティの削除

MQTT プロトコルを使用してシャドウからプロパティを削除するには

  1. デバイスまたはクライアントには、変更するプロパティを識別できるように、現在のシャドウドキュメントが必要です。現在のシャドウドキュメントを取得する方法については、「シャドウキュメントの取得」を参照してください。

  2. デバイスまたはクライアントは、次の MQTT トピックにサブスクライブします。

    • $aws/things/thingName/shadow/name/shadowName/update/accepted

    • $aws/things/thingName/shadow/name/shadowName/update/rejected

  3. デバイスまたはクライアントは、削除するシャドウのプロパティに null 値を割り当てる状態ドキュメントを含む $aws/things/thingName/shadow/name/shadowName/update リクエストトピックを発行します。変更するプロパティのみをドキュメントに含める必要があります。これは、engine プロパティを削除するドキュメントの例です。

    { "state": { "desired": { "engine": null } } }
  4. 更新リクエストが有効な場合、AWS IoT はシャドウ内の指定されたプロパティを削除し、メッセージ本文に /accepted レスポンス状態ドキュメント シャドウドキュメントを含む $aws/things/thingName/shadow/name/shadowName/update/accepted トピックを持つメッセージを発行します。

  5. 更新リクエストが有効でない場合、AWS IoT は、エラーを説明する エラーレスポンスドキュメント シャドウドキュメントを含む $aws/things/thingName/shadow/name/shadowName/update/rejected トピックを持つメッセージを発行します。

REST API を使用してシャドウからプロパティを削除するには

  1. デバイスまたはクライアントは、削除するシャドウのプロパティに null 値を割り当てる リクエスト状態ドキュメント を使用して UpdateThingShadow API を呼び出します。削除するプロパティのみをドキュメントに含めます。これは、engine プロパティを削除するドキュメントの例です。

    { "state": { "desired": { "engine": null } } }
  2. リクエストが有効な場合、AWS IoT はレスポンスメッセージ本文として HTTP 成功レスポンスコードと /accepted レスポンス状態ドキュメント シャドウドキュメントを返します。

  3. リクエストが有効でない場合、AWS IoT はレスポンスメッセージ本文として HTTP エラーレスポンスコードと エラーレスポンスドキュメント を返します。

シャドウの削除

注記

デバイスのシャドウ状態を null に設定しても、シャドウは削除されません。シャドウのバージョンは、次の更新時に増分されます。

デバイスのシャドウを削除しても、Thing オブジェクトは削除されません。Thing オブジェクトを削除しても、対応するデバイスのシャドウは削除されません。

MQTT プロトコルを使用してシャドウを削除するには

  1. デバイスまたはクライアントは、次の MQTT トピックにサブスクライブします。

    • $aws/things/thingName/shadow/name/shadowName/delete/accepted

    • $aws/things/thingName/shadow/name/shadowName/delete/rejected

  2. デバイスまたはクライアントは、空のメッセージバッファを持つ $aws/things/thingName/shadow/name/shadowName/delete を発行します。

  3. 削除リクエストが有効な場合、AWS IoT はシャドウを削除し、メッセージ本文に $aws/things/thingName/shadow/name/shadowName/delete/accepted トピックと省略形の /accepted レスポンス状態ドキュメント シャドウドキュメントを含むメッセージを発行します。次に、受け入れられた削除メッセージの例を示します。

    { "version": 4, "timestamp": 1591057529 }
  4. 更新リクエストが有効でない場合、AWS IoT は、エラーを説明する エラーレスポンスドキュメント シャドウドキュメントを含む $aws/things/thingName/shadow/name/shadowName/delete/rejected トピックを持つメッセージを発行します。

REST API を使用してシャドウを削除するには

  1. デバイスまたはクライアントは、空のメッセージバッファを使用して DeleteThingShadow API を呼び出します。

  2. リクエストが有効な場合、AWS IoT は HTTP 成功レスポンスコードと、メッセージ本文に /accepted レスポンス状態ドキュメント と省略形の /accepted レスポンス状態ドキュメント シャドウドキュメントを返します。次に、受け入れられた削除メッセージの例を示します。

    { "version": 4, "timestamp": 1591057529 }
  3. リクエストが有効でない場合、AWS IoT はレスポンスメッセージ本文として HTTP エラーレスポンスコードと エラーレスポンスドキュメント を返します。