翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # AWS IoT Device Shadow サービス AWS IoT Device Shadow サービスは、 AWS IoT モノのオブジェクトにシャドウを追加します。シャドウは、デバイスが に接続されている AWS IoT かどうかにかかわらず、デバイスの状態をアプリケーションやその他のサービスで利用できるようにします。 AWS IoT モノのオブジェクトには複数の名前付きシャドウを含めることができるため、IoT ソリューションには、デバイスを他のアプリケーションやサービスに接続するためのより多くのオプションがあります。 AWS IoT Thing オブジェクトには、明示的に作成されるまでシャドウはありません。シャドウは、 AWS IoT コンソールを使用して作成、更新、削除できます。デバイス、その他のウェブクライアント、サービスは、MQTT および[予約された MQTT トピック](reserved-topics.md#reserved-topics-shadow)、[Device Shadow REST API](device-shadow-rest-api.md) を使用する HTTP、[AWS CLI for AWS IoT](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot-data/index.html) を使用して、シャドウを作成、更新、削除できます。シャドウは によってクラウド AWS に保存されるため、デバイスが接続されているかどうかにかかわらず、アプリケーションやその他のクラウドサービスからデバイス状態データを収集してレポートできます。 ## シャドウの使用 シャドウは、デバイス、アプリ、その他のクラウドサービスでデータを共有するための信頼性の高いデータストアを提供します。これにより、デバイス、アプリ、その他のクラウドサービスが、デバイスの状態を失うことなく接続および切断できます。 デバイス、アプリケーション、その他のクラウドサービスが に接続されている間は AWS IoT、シャドウを介してデバイスの現在の状態にアクセスして制御できます。たとえば、アプリはシャドウを更新することでデバイスの状態の変更をリクエストできます。 は、デバイスへの変更を示すメッセージ AWS IoT を発行します。デバイスはこのメッセージを受信し、一致するように状態を更新し、更新された状態のメッセージを発行します。Device Shadow サービスは、この更新された状態を対応するシャドウに反映します。アプリはシャドウの更新をサブスクライブすることも、シャドウに現在の状態を照会することもできます。 デバイスがオフラインになっても、アプリは引き続き AWS IoT およびデバイスのシャドウと通信できます。デバイスは再接続すると、シャドウの現在の状態を受信し、シャドウの状態と一致するように状態を更新し、更新された状態のメッセージを発行します。同様に、アプリがオフラインになり、デバイスがオフライン中に状態が変わると、デバイスはシャドウを更新したままにして、アプリが再接続したときに現在の状態のシャドウを照会できるようにします。 デバイスが頻繁にオフラインで、再接続後にデルタメッセージを受信するようにデバイスを設定する場合は、永続セッション機能を使用できます。永続セッションの有効期間の詳細については、「[永続的セッションの有効期間](https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits)」を参照してください。 ### 名前付きのシャドウまたは名前のないシャドウの使用の選択 Device Shadow サービスは、名前付きと名前のない、またはクラシックな、シャドウをサポートします。Thing オブジェクトは、複数の名前付きシャドウを持つことができます。また、名前のないシャドウを 1 つ以上持つことはできません。Thing オブジェクトは、予約済みの名前付きシャドウを持つこともできます。名前を更新できないという点を除けば、名前付きシャドウと同様に機能します。詳細については、「[予約済みの名前付きシャドウ](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-to-use-software-package-catalog.html#reserved-named-shadow)」を参照してください。 Thing オブジェクトは、名前付きのシャドウと名前のないシャドウを同時に持つことができますが、それぞれにアクセスするために使用する API は若干異なるため、ソリューションに最適なシャドウのタイプを決定し、そのタイプのみを使用する方が効率的です。シャドウにアクセスするための API の詳細については、「[シャドウトピック](reserved-topics.md#reserved-topics-shadow)」を参照してください。 名前付きシャドウを使用すると、Thing オブジェクトの状態をさまざまなビューで作成できます。たとえば、多数のプロパティを持つ Thing オブジェクトを、それぞれがシャドウ名で識別される論理的なプロパティのグループを持つシャドウに分割できます。また、プロパティを別のシャドウにグループ化し、ポリシーを使用してアクセスを制御することで、プロパティへのアクセスを制限することもできます。デバイスシャドウで使用するポリシーの詳細については、「[AWS IoTのアクション、リソース、および条件キー](https://docs.aws.amazon.com//service-authorization/latest/reference/list_awsiot.html)」と「[AWS IoT Core のポリシー](https://docs.aws.amazon.com//iot/latest/developerguide/iot-policies.html)」を参照してください。 クラシックな名前のないシャドウは単純ですが、名前付きシャドウよりも多少制限があります。各 AWS IoT モノのオブジェクトには、名前のないシャドウを 1 つだけ含めることができます。IoT ソリューションでシャドウデータの必要性が限られている場合は、そのようにシャドウの使用を開始することができます。ただし、将来、シャドウを追加すると思われる場合は、最初から名前付きのシャドウを使用することを検討してください。 フリートインデックスによるサポートは、名前のないシャドウと名前付きシャドウで異なります。詳細については、「[Manage fleet indexing](managing-fleet-index.md)」(フリートインデックスの管理) を参照してください。 ### シャドウにアクセスする すべてのシャドウには、予約された [MQTT トピック](reserved-topics.md#reserved-topics-shadow)と [HTTP URL](device-shadow-rest-api.md) があり、シャドウに対する `get`、`update`、`delete` のアクションをサポートします。 シャドウは [JSON シャドウドキュメント](device-shadow-document.md)を使用してデータを格納および取得します。シャドウのドキュメントには、デバイスの状態の次の側面を説明する state プロパティが含まれています。 + `desired` アプリは、`desired` オブジェクトを更新することによって、デバイスプロパティの desired 状態を指定します。 + `reported` デバイスは、`reported` オブジェクト内の現在の状態を報告します。 + `delta` AWS IoT は、`delta`オブジェクト内の目的の状態と報告された状態の違いを報告します。 シャドウに格納されるデータは、更新アクションのメッセージ本文の state プロパティによって決まります。それ以降の更新アクションでは、既存のデータオブジェクトの値を変更したり、シャドウの state オブジェクト内のキーやその他の要素を追加および削除したりできます。シャドウへのアクセス方法の詳細については、「[デバイスでのシャドウの使用](device-shadow-comms-device.md)」および「[アプリとサービスでのシャドウの使用](device-shadow-comms-app.md)」を参照してください。 **重要** 更新リクエストを行うアクセス許可は、信頼できるアプリとデバイスに制限する必要があります。これにより、シャドウの state プロパティが予期せず変更されるのを防ぐことができます。そうしないと、シャドウを使用するデバイスおよびアプリは、state プロパティのキーが変更されることを期待するように設計する必要があります。 ### デバイス、アプリ、その他のクラウドサービスでのシャドウの使用 デバイス、アプリ、その他のクラウドサービスでシャドウを使用するには、これらすべての一貫性と調整が必要です。 AWS IoT Device Shadow サービスはシャドウ状態を保存し、シャドウ状態が変更されたときにメッセージを送信し、状態を変更するメッセージに応答します。IoT ソリューション内のデバイス、アプリ、その他のクラウドサービスは、その状態を管理し、デバイスシャドウの状態と整合性を維持する必要があります。 シャドウ状態データは動的であり、シャドウへのアクセス許可を持つデバイス、アプリ、その他のクラウドサービスによって変更できます。このため、各デバイス、アプリ、その他のクラウドサービスがシャドウとどのようにやり取りするかを検討することが重要です。以下に例を示します。 + *デバイス*は、状態データをシャドウに伝達するときに、シャドウ状態の `reported` プロパティにのみ書き込む必要があります。 + *アプリおよびその他のクラウドサービス*は、状態変更リクエストをシャドウを介してデバイスに通信するときのみ、`desired` プロパティに書き込む必要があります。 **重要** シャドウデータオブジェクトに含まれるデータは、他のシャドウや Thing オブジェクトのプロパティ (Thing の属性や MQTT メッセージのコンテンツなど) から独立しています。ただし、デバイスは、必要に応じて、異なる MQTT トピックとシャドウで同じデータを報告できます。 複数のシャドウをサポートするデバイスは、異なるシャドウで報告するデータの整合性を維持する必要があります。 ### メッセージの順序 AWS IoT サービスからのメッセージが特定の順序でデバイスに到着する保証はありません。次のシナリオは、この場合に何が起こるかを示しています。 初期状態ドキュメント: ``` { "state": { "reported": { "color": "blue" } }, "version": 9, "timestamp": 123456776 } ``` 更新 1: ``` { "state": { "desired": { "color": "RED" } }, "version": 10, "timestamp": 123456777 } ``` 更新 2: ``` { "state": { "desired": { "color": "GREEN" } }, "version": 11, "timestamp": 123456778 } ``` 最終状態ドキュメント: ``` { "state": { "reported": { "color": "GREEN" } }, "version": 12, "timestamp": 123456779 } ``` これにより、2 つの差分メッセージが生成されます。 ``` { "state": { "color": "RED" }, "version": 11, "timestamp": 123456778 } ``` ``` { "state": { "color": "GREEN" }, "version": 12, "timestamp": 123456779 } ``` デバイスは順不同でこれらのメッセージを受信する場合があります。これらのメッセージ内の状態は累積的であるため、デバイスは追跡しているものより古いバージョン番号が含まれるメッセージをすべて安全に破棄できます。デバイスはバージョン 11 の前にバージョン 12 の差分を受信した場合、バージョン 11 のメッセージを安全に破棄できます。 ### シャドウメッセージのトリム デバイスに送信されるシャドウメッセージのサイズを小さくするには、デバイスに必要なフィールドのみを選択してから、デバイスのリッスン対象の MQTT トピックにメッセージを再パブリッシュするルールを定義します。 ルールは JSON で指定し、以下のようになります。 ``` { "sql": "SELECT state, version FROM '$aws/things/+/shadow/update/delta'", "ruleDisabled": false, "actions": [ { "republish": { "topic": "${topic(3)}/delta", "roleArn": "arn:aws:iam:123456789012:role/my-iot-role" } } ] } ``` SELECT ステートメントにより、指定したトピックにメッセージのどのフィールドが再パブリッシュされるかが決まります。すべての Shadow 名に一致させるには、"\$1" のワイルドカードを使用します。ルールでは、一致するすべてのメッセージが指定したトピックに再パブリッシュされるように定義しています。この場合、`"topic()"` 関数を使用して、再パブリッシュする先のトピックを指定しています。`topic(3)` は、元のトピック内のモノ名に評価されます。ルール作成の詳細については、「[のルール AWS IoT](iot-rules.md)」を参照してください。 # デバイスでのシャドウの使用 このセクションでは、デバイスが Device Shadow サービスと通信するための推奨方法である MQTT メッセージを使用したシャドウとの AWS IoT デバイス通信について説明します。 シャドウ通信は、MQTT のパブリッシュ/サブスクライブ通信モデルを使用して、リクエスト/レスポンスモデルをエミュレートします。すべてのシャドウアクションは、リクエストトピック、成功したレスポンストピック (`accepted`)、エラーレスポンストピック (`rejected`) で構成されます。 アプリとサービスで、デバイスが接続されているかどうかを判別できるようにする場合は、「[デバイスが接続されているかどうかの検出](device-shadow-comms-app.md#thing-connection)」を参照してください。 **重要** MQTT は発行/サブスクライブ通信モデルを使用するため、リクエストトピックを発行する*前に*レスポンストピックをサブスクライブする必要があります。そうでない場合、発行するリクエストに対するレスポンスを受信しない可能性があります。 [AWS IoT Device SDK](iot-sdks.md) を使用して Device Shadow サービス API を呼び出す場合、これは自動的に処理されます。 このセクションの例では、次の表で説明されているように、*ShadowTopicPrefix* が名前付きのシャドウまたは名前のないシャドウを参照できるトピックの省略形を使用します。 シャドウは、名前付き、または名前のないもの (クラシック) にすることができます。それぞれで使用されるトピックは、トピックのプレフィックスでのみ異なります。この表は、各シャドウタイプで使用されるトピックのプレフィックスを示しています。 | *ShadowTopicPrefix* 値 | シャドウタイプ | | --- | --- | | \$1aws/things/thingName/shadow | 名前のない (クラシック) シャドウ | | \$1aws/things/thingName/shadow/name/shadowName | 名前付きシャドウ | **重要** アプリまたはサービスによるシャドウの使用が一貫しており、デバイス内の対応する実装でサポートされていることを確認してください。たとえば、シャドウの作成、更新、削除方法を考えてみましょう。また、デバイスおよびシャドウを介してデバイスにアクセスするアプリまたはサービスでの更新の処理方法も考慮してください。デバイスの状態がどのように更新され、報告され、アプリやサービスがデバイスとそのシャドウとどのように相互作用するかを明確に設計する必要があります。 完全なトピックを作成するには、次の表に示すように、参照するシャドウのタイプの `ShadowTopicPrefix` を選択し、`thingName` と、`shadowName` (該当する場合) を対応する値に置き換え、トピックスタブに追加します。トピックでは大文字と小文字が区別されることに注意してください。 シャドウ用に予約されているトピックの詳細については、[シャドウトピック](reserved-topics.md#reserved-topics-shadow) を参照してください。 ## への最初の接続時にデバイスを初期化する AWS IoT デバイスが に登録されると AWS IoT、サポートされているシャドウの MQTT メッセージをサブスクライブする必要があります。 | Topic | 意味 | このトピックの受信時にデバイスが実行するアクション | | --- | --- | --- | | `ShadowTopicPrefix/delete/accepted` | `delete` リクエストが受け入れられ、シャドウ AWS IoT が削除されました。 | 更新の発行を停止するなど、削除されたシャドウに対応するために必要なアクション。 | | `ShadowTopicPrefix/delete/rejected` | `delete` リクエストは によって拒否 AWS IoT され、シャドウは削除されませんでした。メッセージ本文には、エラー情報が含まれています。 | メッセージ本文内のエラーメッセージに応答します。 | | `ShadowTopicPrefix/get/accepted` | `get` リクエストは によって受け入れられ AWS IoT、メッセージ本文には現在のシャドウドキュメントが含まれます。 | メッセージ本文内の状態ドキュメントを処理するために必要なアクション。 | | `ShadowTopicPrefix/get/rejected` | `get` リクエストが によって拒否され AWS IoT、メッセージ本文にエラー情報が含まれています。 | メッセージ本文内のエラーメッセージに応答します。 | | `ShadowTopicPrefix/update/accepted` | `update` リクエストは によって受け入れられ AWS IoT、メッセージ本文には現在のシャドウドキュメントが含まれます。 | メッセージ本文の更新されたデータがデバイスの状態と一致することを確認します。 | | `ShadowTopicPrefix/update/rejected` | `update` リクエストは によって拒否され AWS IoT、メッセージ本文にエラー情報が含まれています。 | メッセージ本文内のエラーメッセージに応答します。 | | `ShadowTopicPrefix/update/delta` | シャドウドキュメントは へのリクエストによって更新され AWS IoT、メッセージ本文にはリクエストされた変更が含まれています。 | メッセージ本文内の目的の状態と一致するようにデバイスの状態を更新します。 | | `ShadowTopicPrefix/update/documents` | シャドウの更新が最近完了し、メッセージ本文に現在のシャドウドキュメントが含まれています。 | メッセージ本文の更新された状態が、デバイスの状態と一致することを確認します。 | 各シャドウの前の表のメッセージにサブスクライブした後、デバイスがサポートするシャドウがすでに作成されているかどうかをテストして、各シャドウに `/get` トピックを発行します。`/get/accepted` メッセージを受信すると、メッセージ本文にはシャドウドキュメントが含まれます。シャドウドキュメントは、デバイスがその状態を初期化するために使用できます。`/get/rejected` メッセージを受信した場合は、現在のデバイス状態の `/update` メッセージを発行してシャドウを作成する必要があります。 例えば、モノ `My_IoT_Thing` があるとします。クラシックシャドウや名前の付いたシャドウはありません。今予約済みトピック `$aws/things/My_IoT_Thing/shadow/get` に `/get` リクエストを発行する場合、モノにシャドウがないため `$aws/things/My_IoT_Thing/shadow/get/rejected` トピックのエラーが返されます。このエラーを解決するには、まず次のペイロードなど、現在のデバイス状態の `$aws/things/My_IoT_Thing/shadow/update` トピックを使用して `/update` メッセージを発行します。 ``` { "state": { "reported": { "welcome": "aws-iot", "color": "yellow" } } } ``` これで モノのクラシックシャドウが作成され、`$aws/things/My_IoT_Thing/shadow/update/accepted` トピックへメッセージが発行されます。トピック `$aws/things/My_IoT_Thing/shadow/get` に発行する場合、デバイスの状態に関する `$aws/things/My_IoT_Thing/shadow/get/accepted` トピックを返します。 名前付きシャドウの場合、Get リクエストを使用する前に、最初に名前付きシャドウを作成するか、シャドウ名で更新を発行する必要があります。例えば、名前の付いたシャドウ `namedShadow1` を作成するには、まず、デバイスの状態情報をトピック `$aws/things/My_IoT_Thing/shadow/name/namedShadow1/update` に発行します。状態情報を取得するには、名前付きシャドウ `$aws/things/My_IoT_Thing/shadow/name/namedShadow1/get` の `/get` リクエストを使用します。 ## デバイスが に接続されている間のメッセージの処理 AWS IoT デバイスが に接続されている間は AWS IoT、**/update/delta** メッセージを受信でき、次の方法でデバイスの状態をシャドウの変更と一致させる必要があります。 1. 受信したすべての **/update/delta** メッセージを読み取り、一致するようにデバイスの状態を同期します。 1. デバイスの状態が変更されるたびに、デバイスの現在の状態を含む `reported` メッセージ本文を含む **/update** メッセージを発行します。 デバイスが接続されている間は、これらのメッセージが表示されたら発行する必要があります。 | 表示 | トピック | Payload | | --- | --- | --- | | デバイスの状態が変更されました。 | `ShadowTopicPrefix/update` | `reported` プロパティを持つシャドウドキュメント。 | | デバイスがシャドウと同期していない可能性があります。 | `ShadowTopicPrefix/get` | (空) | | デバイスに対するアクションは、デバイスの削除または交換時など、デバイスによってシャドウがサポートされなくなることを示します | `ShadowTopicPrefix/delete` | (空) | ## デバイスが に再接続したときのメッセージの処理 AWS IoT 1 つ以上のシャドウを持つデバイスが に接続する場合 AWS IoT、その状態を、以下によってサポートされるすべてのシャドウの状態と同期する必要があります。 1. 受信したすべての **/update/delta** メッセージを読み取り、一致するようにデバイスの状態を同期します。 1. デバイスの現在の状態を記載した `reported` メッセージ本文を含む **/update** メッセージを発行します。 # アプリとサービスでのシャドウの使用 このセクションでは、アプリケーションまたはサービスが AWS IoT Device Shadow サービスとやり取りする方法について説明します。この例では、アプリまたはサービスがシャドウと、シャドウを介してデバイスとのみ相互作用していることを前提としています。この例には、シャドウの作成や削除などの管理アクションは含まれていません。 この例では、 AWS IoT Device Shadow サービスの REST API を使用してシャドウを操作します。発行/サブスクライブ通信モデルを使用する [デバイスでのシャドウの使用](device-shadow-comms-device.md) で使用される例とは異なり、この例では REST API のリクエスト/レスポンス通信モデルを使用します。つまり、アプリケーションまたはサービスは、レスポンスを受信する前にリクエストを行う必要があります AWS IoT。ただし、このモデルの欠点は、通知をサポートしていないことです。アプリまたはサービスで、デバイスの状態の変更をタイムリーに通知する必要がある場合は、「[デバイスでのシャドウの使用](device-shadow-comms-device.md)」で説明されているように、パブリッシュ/サブスクライブ通信モデルをサポートする WSS プロトコル経由の MQTT または MQTT を検討してください。 **重要** アプリまたはサービスによるシャドウの使用が、デバイス内の対応する実装と一致し、サポートされていることを確認します。たとえば、シャドウの作成、更新、削除方法、デバイスとシャドウにアクセスするアプリまたはサービスで更新がどのように処理されるかを検討します。デザインでは、デバイスの状態の更新と報告方法、アプリやサービスがデバイスとそのシャドウとどのように相互作用するかを明確に指定する必要があります。 名前付きシャドウの REST API の URL は次のとおりです。 ``` https://endpoint/things/thingName/shadow?name=shadowName ``` 名前のないシャドウの場合： ``` https://endpoint/things/thingName/shadow ``` 各パラメータの意味は次のとおりです。 エンドポイント CLI コマンドによって返されるエンドポイント。 ``` aws iot describe-endpoint --endpoint-type IOT:Data-ATS ``` thingName シャドウが属する Thing オブジェクトの名前 shadowName 名前付きシャドウの名前。このパラメータは、名前のないシャドウでは使用されません。 ## への接続時にアプリまたはサービスを初期化する AWS IoT アプリが最初に接続するときは AWS IoT、使用しているシャドウの現在の状態を取得するために使用するシャドウの URLs に HTTP GET リクエストを送信する必要があります。これにより、アプリまたはサービスをシャドウと同期させることができます。 ## アプリケーションまたはサービスが に接続されている間の処理状態の変更 AWS IoT アプリケーションまたはサービスが接続されている間は AWS IoT、使用するシャドウの URLs に HTTP GET リクエストを送信することで、定期的に現在の状態をクエリできます。 エンドユーザーがアプリまたはサービスと対話してデバイスの状態を変更すると、アプリまたはサービスは、シャドウの `desired` 状態を更新するために使用するシャドウの URL に HTTP POST リクエストを送信できます。このリクエストは受け入れられた変更を返しますが、デバイスがシャドウを新しい状態で更新するまで HTTP GET リクエストを行い、シャドウをポーリングする必要がある場合があります。 ## デバイスが接続されているかどうかの検出 デバイスが現在接続されているかどうかを確認するには、シャドウドキュメントに `connected` プロパティを含めて、MQTT Last Wy and Testament (LWT) メッセージを使用して、デバイスがエラーにより切断された場合に、`connected` プロパティを `false` に設定します。 **注記** AWS IoT 予約済みトピック (\$1 で始まるトピック) に送信される MQTT LWT メッセージは、 AWS IoT Device Shadow サービスによって無視されます。ただし、これらはサブスクライブされたクライアントと AWS IoT ルールエンジンによって処理されるため、予約されていないトピックに送信される LWT メッセージと、シャドウの予約された更新トピック にシャドウ更新メッセージとして MQTT LWT メッセージを再発行するルールを作成する必要があります`ShadowTopicPrefix/update`。 **Device Shadow サービスに LWT メッセージを送信するには** 1. 予約されたトピックで MQTT LWT メッセージを再発行するルールを作成します。次の例は、 `my/things/myLightBulb/update` トピックに関するメッセージをリッスンし、`$aws/things/myLightBulb/shadow/update` に再発行するルールです。 ``` { "rule": { "ruleDisabled": false, "sql": "SELECT * FROM 'my/things/myLightBulb/update'", "description": "Turn my/things/ into $aws/things/", "actions": [ { "republish": { "topic": "$$aws/things/myLightBulb/shadow/update", "roleArn": "arn:aws:iam:123456789012:role/aws_iot_republish" } } ] } } ``` 1. デバイスが に接続すると AWS IoT、再発行ルールが認識する予約されていないトピックに LWT メッセージが登録されます。この例では、トピックが `my/things/myLightBulb/update` であり、connected プロパティを `false` に設定します。 ``` { "state": { "reported": { "connected":"false" } } } ``` 1. 接続後、デバイスはシャドウ更新トピック、`$aws/things/myLightBulb/shadow/update` に関するメッセージを発行し、`connected` プロパティを `true` に設定することを含む現在の状態を報告します。 ``` { "state": { "reported": { "connected":"true" } } } ``` 1. デバイスは正常に切断する前に、シャドウ更新トピック、`$aws/things/myLightBulb/shadow/update` に関するメッセージを発行し、`connected` プロパティを `false` に設定することを含む最新の状態を報告します。 ``` { "state": { "reported": { "connected":"false" } } } ``` 1. エラーによりデバイスが切断された場合、 AWS IoT メッセージブローカーはデバイスに代わってデバイスの LWT メッセージを発行します。再発行ルールはこのメッセージを検出し、シャドウ更新メッセージを発行してデバイスシャドウの `connected` プロパティを更新します。 **注記** 切断処理は非同期であるため、再接続時に LWT メッセージが順番にディスパッチされるとは限りません。接続状態の検出精度を向上させるために、[ライフサイクルイベント](life-cycle-events.md)を使用することをお勧めします。これらのイベントでは、順不同のイベントを管理するための属性が提供されています。 # デバイスシャドウサービス通信のシミュレーション このトピックでは、Device Shadow サービスが仲介として動作する方法を示し、デバイスおよびアプリはシャドウを使用してデバイスの状態を更新、保存、取得できます。 このトピックで説明されているやり取りをデモンストレーションし、さらに詳しく調べるには、 AWS アカウント と、 を実行できるシステムが必要です AWS CLI。これらがない場合は、コード例で相互作用を確認できます。 この例では、 AWS IoT コンソールは デバイスを表します。は、シャドウを介してデバイスにアクセスするアプリまたはサービス AWS CLI を表します。 AWS CLI インターフェイスは、アプリケーションが通信に使用する API と非常によく似ています AWS IoT。この例のデバイスはスマート電球で、アプリは電球の状態を表示し、電球の状態を変更できます。 ## シミュレーションの設定 これらの手順では、デバイスをシミュレートする [AWS IoT コンソール](https://console.aws.amazon.com/iot/home)と、アプリをシミュレートするコマンドラインウィンドウを開いてシミュレーションを初期化します。 **シミュレーション環境を設定するには** 1. このトピックの例を自分で実行する AWS アカウント には、 が必要です。がない場合は AWS アカウント、「」の説明に従って作成します[セットアップ AWS アカウント](setting-up.md)。 1. [AWS IoT コンソール](https://console.aws.amazon.com/iot/home)を開き、左側のメニューで [**テスト**] を選択して **MQTT クライアント**を開きます。 1. 別のウィンドウで、 AWS CLI がインストールされているシステムでターミナルウィンドウを開きます。 2 つのウィンドウが開いている必要があります。1 つは**テスト**ページの AWS IoT コンソール、もう 1 つはコマンドラインプロンプトです。 ## デバイスの初期化 このシミュレーションでは、*mySimulatedThing* という名前の Thing オブジェクトと、*SimShadow1* という名前のシャドウを使って作業します。 **モノのオブジェクトとその IoT ポリシーを作成する** **AWS IoT コンソール**でモノのオブジェクトを作成するには 1. [**Manage**] (管理) を選択し、[**Things**] (モノ) を選択します。 1. モノが一覧表示されている場合は**「作成**」ボタンをクリックするか、**「単一のモノを登録する**」をクリックして単一の AWS IoT モノを作成します。 1. 名前 `mySimulatedThing` を入力し、その他の設定はデフォルトのままにして、[**Next**] (次へ) をクリックします。 1. ワンクリックの証明書作成を使用して、 AWS IoTへのデバイスの接続を認証する証明書を生成します。[**Activate**] (有効化) をクリックして証明書を有効化します。 1. MQTT 予約トピックを発行およびサブスクライブするためのアクセス許可をデバイスに付与するポリシー `My_IoT_Policy` をアタッチできます。 AWS IoT モノの作成方法とこのポリシーの作成方法の詳細については、「」を参照してください[モノのオブジェクトを作成する](create-iot-resources.md#create-aws-thing)。 **モノのオブジェクトの名前の付いたシャドウを作成する** 以下に示すように、トピック `$aws/things/mySimulatedThing/shadow/name/simShadow1/update` に更新リクエストを発行することで、モノの名前付きシャドウを作成できます。 または、名前付きシャドウを作成するには: 1. **AWS IoT コンソール**で、表示されたモノのリストから自分のモノオブジェクトを選択し、**[Shadows]** (シャドウ) を選択します。 1. [**Add a shadow**] (シャドウの追加) を選択し、名前 `simShadow1` を入力してから、[**Create**] (作成) を選択して名前付きシャドウを追加します。 **予約済みの MQTT トピックをサブスクライブして発行する** コンソールで、予約された MQTT シャドウのトピックをサブスクライブします。これらのトピックは `get`、`update`、`delete` アクションに対するレスポンスです。これにより、デバイスがアクションを発行した後にレスポンスを受信できます。 ****MQTT クライアント**で MQTT トピックをサブスクライブするには** 1. **MQTT クライアント** で、**[Subscribe to topic]** (トピックのサブスクライブ) を選択します。 1. サブスクライブする `get`、`update`、および `delete` トピックを入力します。次のリストから一度に 1 つのトピックをコピーして **[Topic filter]** (トピックフィルター) フィールドに貼り付け、**[Subscribe]** (サブスクライブ) をクリックします。[**Subscriptions**] (サブスクリプション) の下にトピックが表示されます。 + `$aws/things/mySimulatedThing/shadow/name/simShadow1/delete/accepted` + `$aws/things/mySimulatedThing/shadow/name/simShadow1/delete/rejected` + `$aws/things/mySimulatedThing/shadow/name/simShadow1/get/accepted` + `$aws/things/mySimulatedThing/shadow/name/simShadow1/get/rejected` + `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/accepted` + `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/rejected` + `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/delta` + `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/documents` この時点で、シミュレートされたデバイスは、 AWS IoTによって発行されるトピックを受信する準備が整いました。 ****MQTT クライアント**で MQTT トピックを発行するには** デバイス自体を初期化してレスポンストピックにサブスクライブした後、サポートしているシャドウを照会する必要があります。このシミュレーションは、*simShadow1* という名前の *mySimulatedThing* というモノのオブジェクトをサポートする 1 つのシャドウのみをサポートします。 ****MQTT クライアント**から現在のシャドウ状態を取得するには** 1. **MQTT クライアント**で、[**トピックへの発行**] を選択します。 1. **[Publish]** (発行) で、次のトピックを入力し、取得するトピックを入力した下のメッセージ本文ウィンドウからコンテンツを削除します。その後、[**Publish to topic**] (トピックに発行) を選択してリクエストを発行できます。`$aws/things/mySimulatedThing/shadow/name/simShadow1/get`。 名前付きシャドウ 、`simShadow1` 、を作成していない場合は、`$aws/things/mySimulatedThing/shadow/name/simShadow1/get/rejected`トピックでメッセージを受信し、`code` が`404` の場合 (この例のように)、シャドウは作成されていないため、次に作成します。 ``` { "code": 404, "message": "No shadow exists with name: 'simShadow1'" } ``` **デバイスの現在のステータスを持つシャドウを作成するには** 1. **[MQTT client]** (MQTT クライアント) で、**[Publish to a topic]** (トピックへの発行) を選択し、このトピックを入力します。 ``` $aws/things/mySimulatedThing/shadow/name/simShadow1/update ``` 1. トピックを入力した下のメッセージ本文ウィンドウで、このシャドウドキュメントを入力して、デバイスが ID と現在の色を RGB 値で報告していることを示します。**[Publish]** (発行) を選択してリクエストを発行します。 ``` { "state": { "reported": { "ID": "SmartLamp21", "ColorRGB": [ 128, 128, 128 ] } }, "clientToken": "426bfd96-e720-46d3-95cd-014e3ef12bb6" } ``` トピックでメッセージを受信した場合は、次のようになります。 + `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/accepted`: これは、シャドウが作成され、メッセージ本文に現在のシャドウドキュメントが含まれていることを意味します。 + `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/rejected`: メッセージ本文内のエラーを確認します。 + `$aws/things/mySimulatedThing/shadow/name/simShadow1/get/accepted`: シャドウは既に存在し、この例のようにメッセージ本文には現在のシャドウ状態があります。これにより、デバイスを設定したり、シャドウ状態と一致していることを確認したりできます。 ``` { "state": { "reported": { "ID": "SmartLamp21", "ColorRGB": [ 128, 128, 128 ] } }, "metadata": { "reported": { "ID": { "timestamp": 1591140517 }, "ColorRGB": [ { "timestamp": 1591140517 }, { "timestamp": 1591140517 }, { "timestamp": 1591140517 } ] } }, "version": 3, "timestamp": 1591140517, "clientToken": "426bfd96-e720-46d3-95cd-014e3ef12bb6" } ``` ## アプリからアップデートを送信する このセクションでは、 を使用して AWS CLI 、アプリがシャドウとやり取りする方法を示します。 **を使用してシャドウの現在の状態を取得するには AWS CLI** コマンドラインで、次のコマンドを入力します。 ``` aws iot-data get-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 /dev/stdout ``` Windows プラットフォームでは、`/dev/stdout`の代わりに `con` を使用できます。 ``` aws iot-data get-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 con ``` シャドウが存在し、デバイスによって現在の状態を反映するように初期化されているため、次のシャドウドキュメントが返されます。 ``` { "state": { "reported": { "ID": "SmartLamp21", "ColorRGB": [ 128, 128, 128 ] } }, "metadata": { "reported": { "ID": { "timestamp": 1591140517 }, "ColorRGB": [ { "timestamp": 1591140517 }, { "timestamp": 1591140517 }, { "timestamp": 1591140517 } ] } }, "version": 3, "timestamp": 1591141111 } ``` アプリはこのレスポンスを使用して、デバイスの状態の表現を初期化できます。 エンドユーザーがスマート電球の色を黄色に変更した場合など、アプリが状態を更新した場合、アプリは **update-thing-shadow** コマンドを送信します。このコマンドは `UpdateThingShadow` REST API に対応します。 **アプリからシャドウを更新するには** コマンドラインで、次のコマンドを入力します。 ------ #### [ AWS CLI v2.x ] ``` aws iot-data update-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 \ --cli-binary-format raw-in-base64-out \ --payload '{"state":{"desired":{"ColorRGB":[255,255,0]}},"clientToken":"21b21b21-bfd2-4279-8c65-e2f697ff4fab"}' /dev/stdout ``` ------ #### [ AWS CLI v1.x ] ``` aws iot-data update-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 \ --payload '{"state":{"desired":{"ColorRGB":[255,255,0]}},"clientToken":"21b21b21-bfd2-4279-8c65-e2f697ff4fab"}' /dev/stdout ``` ------ 成功した場合、このコマンドは次のシャドウドキュメントを返します。 ``` { "state": { "desired": { "ColorRGB": [ 255, 255, 0 ] } }, "metadata": { "desired": { "ColorRGB": [ { "timestamp": 1591141596 }, { "timestamp": 1591141596 }, { "timestamp": 1591141596 } ] } }, "version": 4, "timestamp": 1591141596, "clientToken": "21b21b21-bfd2-4279-8c65-e2f697ff4fab" } ``` ## デバイスでの更新に応答 AWS コンソールで **MQTT クライアント**に戻ると、前のセクションで AWS IoT 発行された更新コマンドを反映するために が発行したメッセージが表示されます。 ****MQTT クライアント**で更新メッセージを表示するには** **[MQTT client]** (MQTT クライアント) の、**[Subscriptions]** (サブスクリプション) 列で **\$1aws/things/mySimulatedThing/shadow/name/simShadow1/update/delta** を選択します。トピック名が切り詰められている場合は、トピック名を一時停止してトピック全体を表示できます。このトピックのトピックログには、次のような `/delta` メッセージが表示されます。 ``` { "version": 4, "timestamp": 1591141596, "state": { "ColorRGB": [ 255, 255, 0 ] }, "metadata": { "ColorRGB": [ { "timestamp": 1591141596 }, { "timestamp": 1591141596 }, { "timestamp": 1591141596 } ] }, "clientToken": "21b21b21-bfd2-4279-8c65-e2f697ff4fab" } ``` デバイスはこのメッセージの内容を処理して、デバイスの状態がメッセージ内の `desired` 状態と一致するように設定します。 デバイスは、メッセージ内の状態と一致するように`desired`状態を更新した後、更新メッセージを公開 AWS IoT して、新しいレポートされた状態を に送信する必要があります。この手順では、**MQTT クライアント**でこれをシミュレートします。 **デバイスからシャドウを更新するには** 1. **MQTT クライアント**で、[**トピックへの発行**] を選択します。 1. メッセージ本文ウィンドウで、メッセージ本文ウィンドウの上にあるトピックフィールドに、シャドウのトピックを入力し、その後に `/update` アクションを入力します: `$aws/things/mySimulatedThing/shadow/name/simShadow1/update`とメッセージ本文に、デバイスの現在の状態を説明するこの更新されたシャドウドキュメントを入力します。[**Publish**] (発行) をクリックして、更新されたデバイス状態を発行します。 ``` { "state": { "reported": { "ColorRGB": [255,255,0] } }, "clientToken": "a4dc2227-9213-4c6a-a6a5-053304f60258" } ``` メッセージが によって正常に受信された場合 AWS IoT、この例のようなシャドウの現在の状態を持つ **MQTT クライアントの** **\$1aws/things/mySimulatedThing/shadow/name/simShadow1/update/accepted** メッセージログに新しいレスポンスが表示されます。 ``` { "state": { "reported": { "ColorRGB": [ 255, 255, 0 ] } }, "metadata": { "reported": { "ColorRGB": [ { "timestamp": 1591142747 }, { "timestamp": 1591142747 }, { "timestamp": 1591142747 } ] } }, "version": 5, "timestamp": 1591142747, "clientToken": "a4dc2227-9213-4c6a-a6a5-053304f60258" } ``` デバイスの報告された状態を正常に更新 AWS IoT すると、 は、前述の手順でデバイスによって実行されたシャドウ更新に起因するこのメッセージ本文など、メッセージのシャドウ状態の包括的な説明を `update/documents`トピックに送信します。 ``` { "previous": { "state": { "desired": { "ColorRGB": [ 255, 255, 0 ] }, "reported": { "ID": "SmartLamp21", "ColorRGB": [ 128, 128, 128 ] } }, "metadata": { "desired": { "ColorRGB": [ { "timestamp": 1591141596 }, { "timestamp": 1591141596 }, { "timestamp": 1591141596 } ] }, "reported": { "ID": { "timestamp": 1591140517 }, "ColorRGB": [ { "timestamp": 1591140517 }, { "timestamp": 1591140517 }, { "timestamp": 1591140517 } ] } }, "version": 4 }, "current": { "state": { "desired": { "ColorRGB": [ 255, 255, 0 ] }, "reported": { "ID": "SmartLamp21", "ColorRGB": [ 255, 255, 0 ] } }, "metadata": { "desired": { "ColorRGB": [ { "timestamp": 1591141596 }, { "timestamp": 1591141596 }, { "timestamp": 1591141596 } ] }, "reported": { "ID": { "timestamp": 1591140517 }, "ColorRGB": [ { "timestamp": 1591142747 }, { "timestamp": 1591142747 }, { "timestamp": 1591142747 } ] } }, "version": 5 }, "timestamp": 1591142747, "clientToken": "a4dc2227-9213-4c6a-a6a5-053304f60258" } ``` ## アプリで更新を確認する アプリは、デバイスによって報告された現在の状態をシャドウに照会できるようになりました。 **を使用してシャドウの現在の状態を取得するには AWS CLI** 1. コマンドラインで、次のコマンドを入力します。 ``` aws iot-data get-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 /dev/stdout ``` Windows プラットフォームでは、`/dev/stdout`の代わりに `con`を使用できます。 ``` aws iot-data get-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 con ``` 1. シャドウは現在の状態を反映するようにデバイスによって更新されたばかりなので、次のシャドウドキュメントを返します。 ``` { "state": { "desired": { "ColorRGB": [ 255, 255, 0 ] }, "reported": { "ID": "SmartLamp21", "ColorRGB": [ 255, 255, 0 ] } }, "metadata": { "desired": { "ColorRGB": [ { "timestamp": 1591141596 }, { "timestamp": 1591141596 }, { "timestamp": 1591141596 } ] }, "reported": { "ID": { "timestamp": 1591140517 }, "ColorRGB": [ { "timestamp": 1591142747 }, { "timestamp": 1591142747 }, { "timestamp": 1591142747 } ] } }, "version": 5, "timestamp": 1591143269 } ``` ## シミュレーションを超える AWS CLI (アプリを表す) とコンソール (デバイスを表す) の間の相互作用を試して、IoT ソリューションをモデル化します。 # シャドウとの相互作用 このトピックでは、シャドウを操作するために AWS IoT が提供する 3 つの方法のそれぞれに関連するメッセージについて説明します。これらの方法には、次のものがあります。 `UPDATE` 存在しない場合はシャドウを作成します。メッセージ本文に指定された状態情報で既存のシャドウの内容を更新します。 AWS IoT は、更新ごとにタイムスタンプを記録して、状態が最後に更新された日時を示します。シャドウの状態が変更されると、 AWS IoT はすべての MQTT サブスクライバーに 状態`desired`と `reported`状態の違いとともに`/delta`メッセージを送信します。`/delta` メッセージを受信するデバイスまたはアプリは、違いに基づいてアクションを実行できます。たとえば、デバイスは自らの状態を desired 状態に更新でき、アプリケーションはデバイスの状態の変更を表示するようにその UI を更新できます。 `GET` メタデータを含むシャドウの完全な状態を含む現在のシャドウドキュメントを取得します。 `DELETE` デバイスシャドウとそのコンテンツを削除します。 削除したデバイスシャドウドキュメントを復元することはできませんが、削除したデバイスシャドウドキュメントの名前で新しいデバイスシャドウを作成することはできます。過去 48 時間以内に削除されたものと同じ名前のデバイスシャドウドキュメントを作成した場合、新しいデバイスシャドウドキュメントのバージョン番号は、削除されたデバイスのシャドウドキュメントのバージョン番号の続きになります。デバイスシャドウドキュメントが 48 時間より前に削除されている場合、同じ名前の新しいデバイスシャドウドキュメントのバージョン番号は 0 になります。 ## プロトコルサポート AWS IoT は[、MQTT](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html) と HTTPS プロトコル経由の REST API をサポートして shadows とやり取りします。 は、MQTT 発行およびサブスクライブアクション用に予約された一連のリクエストおよびレスポンストピック AWS IoT を提供します。デバイスとアプリは、 がリクエスト AWS IoT を処理した方法についての情報をリクエストトピックに発行する前に、レスポンストピックをサブスクライブする必要があります。詳細については、「[Device Shadow MQTT トピック](device-shadow-mqtt.md)」および「[Device Shadow の REST API](device-shadow-rest-api.md)」を参照してください。 ## 状態の要求と報告 AWS IoT とシャドウを使用して IoT ソリューションを設計する場合は、変更をリクエストするアプリケーションまたはデバイスと、変更を実装するアプリケーションまたはデバイスを決定する必要があります。通常、デバイスは変更をシャドウに実装して報告し、アプリとサービスはシャドウの変更に応答して要求します。ソリューションは異なる場合がありますが、このトピックの例では、クライアントアプリまたはサービスがシャドウの変更を要求し、デバイスがその変更を実行してシャドウに報告することを前提としています。 ## シャドウの更新 アプリまたはサービスは、[UpdateThingShadow](device-shadow-rest-api.md#API_UpdateThingShadow) API を使用するか、[/update](device-shadow-mqtt.md#update-pub-sub-topic) トピックに発行することで、シャドウの状態を更新できます。更新は、リクエストで指定したフィールドにのみ反映されます。 ### クライアントが状態の変更を要求したときのシャドウの更新 **クライアントが MQTT プロトコルを使用してシャドウの状態の変更を要求した場合** 1. クライアントには、変更するプロパティを識別できるように、現在のシャドウドキュメントが必要です。現在のシャドウドキュメントを取得する方法については、/get アクションを参照してください。 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` 1. クライアントは、シャドウの desired 状態を含む状態ドキュメントを持つ `$aws/things/thingName/shadow/name/shadowName/update` リクエストトピックを発行します。変更するプロパティのみをドキュメントに含める必要があります。これは、desired 状態のドキュメントの例です。 ``` { "state": { "desired": { "color": { "r": 10 }, "engine": "ON" } } } ``` 1. 更新リクエストが有効な場合、 はシャドウ内の目的の状態 AWS IoT を更新し、これらのトピックに関するメッセージを発行します。 + `$aws/things/thingName/shadow/name/shadowName/update/accepted` + `$aws/things/thingName/shadow/name/shadowName/update/delta` `/update/accepted` メッセージには [/accepted レスポンス状態ドキュメント](device-shadow-document.md#device-shadow-example-response-json-accepted) シャドウドキュメントが含まれ、`/update/delta` メッセージには [/delta レスポンス状態ドキュメント](device-shadow-document.md#device-shadow-example-response-json-delta) シャドウドキュメントが含まれます。 1. 更新リクエストが有効でない場合、 はエラーを説明する[エラーレスポンスドキュメント](device-shadow-document.md#device-shadow-example-error-json)シャドウドキュメントを含む `$aws/things/thingName/shadow/name/shadowName/update/rejected`トピックを含むメッセージ AWS IoT を発行します。 **クライアントが API を使用してシャドウの状態の変更を要求した場合** 1. クライアントは、`UpdateThingShadow` API と [リクエスト状態ドキュメント](device-shadow-document.md#device-shadow-example-request-json) 状態ドキュメントをメッセージ本文として使用します。 1. リクエストが有効な場合、 は HTTP 成功レスポンスコードと[/accepted レスポンス状態ドキュメント](device-shadow-document.md#device-shadow-example-response-json-accepted)シャドウドキュメントをレスポンスメッセージ本文として AWS IoT 返します。 AWS IoT は、サブスクライブするデバイスまたはクライアントの[/delta レスポンス状態ドキュメント](device-shadow-document.md#device-shadow-example-response-json-delta)シャドウドキュメントを含む MQTT メッセージも`$aws/things/thingName/shadow/name/shadowName/update/delta`トピックに発行します。 1. リクエストが有効でない場合、 はレスポンスメッセージ本文[エラーレスポンスドキュメント](device-shadow-document.md#device-shadow-example-error-json)として HTTP エラーレスポンスコード AWS IoT を返します。 デバイスが `/desired` トピックに関する `/update/delta` 状態を受信すると、デバイス内で必要な変更を行います。次に、`/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` 1. デバイスは、この例のように、現在の状態を報告する `$aws/things/thingName/shadow/name/shadowName/update` トピックにメッセージを発行することによって、現在の状態を報告します。 ``` { "state": { "reported" : { "color" : { "r" : 10 }, "engine" : "ON" } } } ``` 1. が更新 AWS IoT を受け入れると、シャ[/accepted レスポンス状態ドキュメント](device-shadow-document.md#device-shadow-example-response-json-accepted)ドウドキュメントを使用して`$aws/things/thingName/shadow/name/shadowName/update/accepted`トピックにメッセージを発行します。 1. 更新リクエストが有効でない場合、 はエラーを説明する[エラーレスポンスドキュメント](device-shadow-document.md#device-shadow-example-error-json)シャドウドキュメントを含む `$aws/things/thingName/shadow/name/shadowName/update/rejected`トピックを含むメッセージ AWS IoT を発行します。 **デバイスが API を使用して現在の状態をシャドウに報告する場合** 1. デバイスは、[リクエスト状態ドキュメント](device-shadow-document.md#device-shadow-example-request-json) 状態ドキュメントをメッセージ本文として使用して `UpdateThingShadow` API を呼び出します。 1. リクエストが有効な場合、 はシャドウ AWS IoT を更新し、レスポンスメッセージ本文としてシャドウドキュメントを含む HTTP [/accepted レスポンス状態ドキュメント](device-shadow-document.md#device-shadow-example-response-json-accepted) 成功レスポンスコードを返します。 AWS IoT は、サブスクライブするデバイスまたはクライアントの[/delta レスポンス状態ドキュメント](device-shadow-document.md#device-shadow-example-response-json-delta)シャドウドキュメントを含む MQTT メッセージも`$aws/things/thingName/shadow/name/shadowName/update/delta`トピックに発行します。 1. リクエストが有効でない場合、 はレスポンスメッセージ本文[エラーレスポンスドキュメント](device-shadow-document.md#device-shadow-example-error-json)として HTTP エラーレスポンスコード AWS IoT を返します。 ### オプティミスティックロック 状態ドキュメントのバージョンを使用して、デバイスのシャドウドキュメントの最新バージョンを更新していることを確認できます。更新リクエストでバージョンを渡したとき、そのバージョンと状態ドキュメントの現在のバージョンとが一致しない場合、サービスは HTTP 409 conflict レスポンスコードでリクエストを拒否します。競合レスポンスコードは、`ThingShadow` を変更するすべての API (`DeleteThingShadow` を含む) でも発生する可能性があります。 例えば、次のようになります。 初期ドキュメント: ``` { "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](device-shadow-rest-api.md#API_GetThingShadow) API を使用するか、[/get](device-shadow-mqtt.md#get-pub-sub-topic) トピックをサブスクライブして発行することによって取得できます。これにより、`desired` 状態と `reported` 状態の間の delta を含む、完全なシャドウドキュメントが取得されます。このタスクの手順は、デバイスまたはクライアントがリクエストを行っているかどうかにかかわらず同じです。 **MQTT プロトコルを使用してシャドウドキュメントを取得するには** 1. デバイスまたはクライアントは、シャドウを更新する前に、次の MQTT トピックにサブスクライブする必要があります。 + `$aws/things/thingName/shadow/name/shadowName/get/accepted` + `$aws/things/thingName/shadow/name/shadowName/get/rejected` 1. デバイスまたはクライアントは、空のメッセージ本文を持つ `$aws/things/thingName/shadow/name/shadowName/get` トピックにメッセージを発行します。 1. リクエストが成功すると、 はメッセージ本文[/accepted レスポンス状態ドキュメント](device-shadow-document.md#device-shadow-example-response-json-accepted)に を含むメッセージを`$aws/things/thingName/shadow/name/shadowName/get/accepted`トピックに AWS IoT 発行します。 1. リクエストが有効でなかった場合、 はメッセージ本文に を含むメッセージを`$aws/things/thingName/shadow/name/shadowName/get/rejected`トピックに AWS IoT 発行[エラーレスポンスドキュメント](device-shadow-document.md#device-shadow-example-error-json)します。 **REST API を使用してシャドウドキュメントを取得するには** 1. デバイスまたはクライアントは、空のメッセージ本文で `GetThingShadow` API を呼び出します。 1. リクエストが有効な場合、 はレスポンスメッセージ本文としてシャドウドキュメントを含む HTTP [/accepted レスポンス状態ドキュメント](device-shadow-document.md#device-shadow-example-response-json-accepted) 成功レスポンスコード AWS IoT を返します。 1. リクエストが有効でない場合、 はレスポンスメッセージ本文[エラーレスポンスドキュメント](device-shadow-document.md#device-shadow-example-error-json)として HTTP エラーレスポンスコード AWS IoT を返します。 ## シャドウデータの削除 シャドウデータを削除するには、シャドウドキュメント内の特定のプロパティを削除する方法と、シャドウを完全に削除する方法の 2 つがあります。 + シャドウから特定のプロパティを削除するには、シャドウを更新します。ただし、削除するプロパティの値を `null` に設定します。値が `null` のフィールドは、シャドウドキュメントから削除されます。 + シャドウ全体を削除するには、[DeleteThingShadow](device-shadow-rest-api.md#API_DeleteThingShadow) API を使用するか、[/delete](device-shadow-mqtt.md#delete-pub-sub-topic) トピックに発行します。 **注記** シャドウを削除しても、すぐにバージョン番号がゼロにリセットされるわけではありません。48 時間後にゼロにリセットされます。 ### シャドウドキュメントからのプロパティの削除 **MQTT プロトコルを使用してシャドウからプロパティを削除するには** 1. デバイスまたはクライアントには、変更するプロパティを識別できるように、現在のシャドウドキュメントが必要です。現在のシャドウドキュメントを取得する方法については、「[シャドウキュメントの取得](#retrieving-device-shadow)」を参照してください。 1. デバイスまたはクライアントは、次の MQTT トピックにサブスクライブします。 + `$aws/things/thingName/shadow/name/shadowName/update/accepted` + `$aws/things/thingName/shadow/name/shadowName/update/rejected` 1. デバイスまたはクライアントは、削除するシャドウのプロパティに `$aws/things/thingName/shadow/name/shadowName/update` 値を割り当てる状態ドキュメントを含む `null` リクエストトピックを発行します。変更するプロパティのみをドキュメントに含める必要があります。これは、`engine` プロパティを削除するドキュメントの例です。 ``` { "state": { "desired": { "engine": null } } } ``` 1. 更新リクエストが有効な場合、 はシャドウ内の指定されたプロパティ AWS IoT を削除し、メッセージ本文にシャド[/accepted レスポンス状態ドキュメント](device-shadow-document.md#device-shadow-example-response-json-accepted)ウドキュメントを含む `$aws/things/thingName/shadow/name/shadowName/update/accepted`トピックを含むメッセージを発行します。 1. 更新リクエストが有効でない場合、 はエラーを説明する[エラーレスポンスドキュメント](device-shadow-document.md#device-shadow-example-error-json)シャドウドキュメントを含む `$aws/things/thingName/shadow/name/shadowName/update/rejected`トピックを含むメッセージ AWS IoT を発行します。 **REST API を使用してシャドウからプロパティを削除するには** 1. デバイスまたはクライアントは、削除するシャドウのプロパティに `null` 値を割り当てる [リクエスト状態ドキュメント](device-shadow-document.md#device-shadow-example-request-json) を使用して `UpdateThingShadow` API を呼び出します。削除するプロパティのみをドキュメントに含めます。これは、`engine` プロパティを削除するドキュメントの例です。 ``` { "state": { "desired": { "engine": null } } } ``` 1. リクエストが有効な場合、 は HTTP 成功レスポンスコードと[/accepted レスポンス状態ドキュメント](device-shadow-document.md#device-shadow-example-response-json-accepted)シャドウドキュメントをレスポンスメッセージ本文として AWS IoT 返します。 1. リクエストが有効でない場合、 はレスポンスメッセージ本文[エラーレスポンスドキュメント](device-shadow-document.md#device-shadow-example-error-json)として HTTP エラーレスポンスコード AWS IoT を返します。 ### シャドウの削除 デバイスのシャドウを削除に関する考慮事項を次に示します。 + デバイスのシャドウ状態を `null` に設定しても、シャドウは削除されません。シャドウのバージョンは、次の更新時に増分されます。 + デバイスのシャドウを削除しても、Thing オブジェクトは削除されません。Thing オブジェクトを削除しても、対応するデバイスのシャドウは削除されません。 + シャドウを削除しても、すぐにバージョン番号がゼロにリセットされるわけではありません。48 時間後にゼロにリセットされます。 **MQTT プロトコルを使用してシャドウを削除するには** 1. デバイスまたはクライアントは、次の MQTT トピックにサブスクライブします。 + `$aws/things/thingName/shadow/name/shadowName/delete/accepted` + `$aws/things/thingName/shadow/name/shadowName/delete/rejected` 1. デバイスまたはクライアントは、空のメッセージバッファを持つ `$aws/things/thingName/shadow/name/shadowName/delete` を発行します。 1. 削除リクエストが有効な場合、 はシャドウ AWS IoT を削除し、メッセージ本文に `$aws/things/thingName/shadow/name/shadowName/delete/accepted`トピックと省略されたシャド[/accepted レスポンス状態ドキュメント](device-shadow-document.md#device-shadow-example-response-json-accepted)ウドキュメントを含むメッセージを発行します。次に、受け入れられた削除メッセージの例を示します。 ``` { "version": 4, "timestamp": 1591057529 } ``` 1. 更新リクエストが有効でない場合、 はエラーを説明する[エラーレスポンスドキュメント](device-shadow-document.md#device-shadow-example-error-json)シャドウドキュメントを含む `$aws/things/thingName/shadow/name/shadowName/delete/rejected`トピックを含むメッセージ AWS IoT を発行します。 **REST API を使用してシャドウを削除するには** 1. デバイスまたはクライアントは、空のメッセージバッファを使用して `DeleteThingShadow` API を呼び出します。 1. リクエストが有効な場合、 はメッセージ本文に HTTP 成功レスポンスコードと [/accepted レスポンス状態ドキュメント](device-shadow-document.md#device-shadow-example-response-json-accepted) [/accepted レスポンス状態ドキュメント](device-shadow-document.md#device-shadow-example-response-json-accepted)と省略されたシャドウドキュメント AWS IoT を返します。次に、受け入れられた削除メッセージの例を示します。 ``` { "version": 4, "timestamp": 1591057529 } ``` 1. リクエストが有効でない場合、 はレスポンスメッセージ本文[エラーレスポンスドキュメント](device-shadow-document.md#device-shadow-example-error-json)として HTTP エラーレスポンスコード AWS IoT を返します。 # Device Shadow の REST API Shadow は状態情報の更新用に以下の URI を公開します。 ``` https://account-specific-prefix-ats.iot.region.amazonaws.com/things/thingName/shadow ``` エンドポイントは に固有です AWS アカウント。エンドポイントを見つけるには、以下を実行します。 + AWS CLIの [describe-endpoint](https://docs.aws.amazon.com/cli/latest/reference/iot/describe-endpoint.html) コマンドを使用します。 + AWS IoT コンソール設定を使用します。[**Settings**] (設定) で、エンドポイントは [**Custom endpoint**] (カスタムエンドポイント) の下に表示されます + AWS IoT コンソールのモノの詳細ページを使用します。コンソールで: 1. [**Manage**] (管理) を展開し、[**Manage**] (管理) で [**Things**] (モノ) をクリックします。 1. モノのリストで、エンドポイント URI を取得するモノを選択します。 1. [**Device Shadows**] (デバイスシャドウ) タブをクリックし、シャドウを選択します。エンドポイント URI は、[**Device Shadow details**] (デバイスシャドウの詳細) ページの [**Device Shadow URL**] (デバイスシャドウの URL) セクションで確認できます。 エンドポイントの形式は以下のとおりです。 ``` identifier.iot.region.amazonaws.com ``` シャドウの REST API は、「[デバイス通信プロトコル](protocols.md)」で説明されているものと同じ HTTPS プロトコル/ポートマッピングに従います。 **注記** API を使用するには、`iotdevicegateway` を認証のサービス名として使用する必要があります。詳細については、「[IOTDataPlane](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-iot-data-plane/classes/iotdataplane.html)」を参照してください。 **Topics** + [GetThingShadow](#API_GetThingShadow) + [UpdateThingShadow](#API_UpdateThingShadow) + [DeleteThingShadow](#API_DeleteThingShadow) + [ListNamedShadowsForThing](#API_ListNamedShadowsForThing) また、API のクエリパラメータの一部として `name=shadowName` を指定し、API を使用して名前付きシャドウを作成することもできます。 ## GetThingShadow 指定したモノの Shadow を取得します。 レスポンス状態ドキュメントには、`desired` 状態と `reported` 状態との差分が含まれます。 **リクエスト** リクエストには標準の HTTP ヘッダーに加えて、以下の URI が含まれます。 ``` HTTP GET https://endpoint/things/thingName/shadow?name=shadowName Request body: (none) ``` 名前なし (クラシック) シャドウでは、`name` クエリパラメータは必要ありません。 **応答** 成功した場合、レスポンスには標準の HTTP ヘッダーに加えて、以下のコードと本体が含まれます。 ``` HTTP 200 Response Body: response state document ``` 詳細については、「[Example Response State Document](device-shadow-document.md#device-shadow-example-response-json)」を参照してください。 **Authorization** Shadow を取得するには、呼び出し元に `iot:GetThingShadow` アクションの実行を許可するポリシーが必要です。Device Shadow サービスは、IAM 認証情報による署名バージョン 4、クライアント証明書による TLS 相互認証という、2 つの形式の認証を受け入れます。 以下に示しているのは、呼び出し元にデバイスのシャドウの取得を許可するポリシーの例です。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iot:GetThingShadow", "Resource": [ "arn:aws:iot:us-east-1:123456789012:thing/thing" ] } ] } ``` ## UpdateThingShadow 指定したモノの Shadow を更新します。 更新は、リクエスト状態ドキュメントで指定したフィールドにのみ反映されます。値が `null` のフィールドはすべてデバイスのシャドウから削除されます。 **リクエスト** リクエストには標準の HTTP ヘッダーに加えて、以下の URI と本体が含まれます。 ``` HTTP POST https://endpoint/things/thingName/shadow?name=shadowName Request body: request state document ``` 名前なし (クラシック) シャドウでは、`name` クエリパラメータは必要ありません。 詳細については、「[リクエスト状態ドキュメントの例](device-shadow-document.md#device-shadow-example-request-json)」を参照してください。 **応答** 成功した場合、レスポンスには標準の HTTP ヘッダーに加えて、以下のコードと本体が含まれます。 ``` HTTP 200 Response body: response state document ``` 詳細については、「[Example Response State Document](device-shadow-document.md#device-shadow-example-response-json)」を参照してください。 **Authorization** Shadow を更新するには、呼び出し元に `iot:UpdateThingShadow` アクションの実行を許可するポリシーが必要です。Device Shadow サービスは、IAM 認証情報による署名バージョン 4、クライアント証明書による TLS 相互認証という、2 つの形式の認証を受け入れます。 以下に示しているのは、呼び出し元にデバイスのシャドウの更新を許可するポリシーの例です。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iot:UpdateThingShadow", "Resource": [ "arn:aws:iot:us-east-1:123456789012:thing/thing" ] } ] } ``` ## DeleteThingShadow 指定したモノの Shadow を削除します。 **リクエスト** リクエストには標準の HTTP ヘッダーに加えて、以下の URI が含まれます。 ``` HTTP DELETE https://endpoint/things/thingName/shadow?name=shadowName Request body: (none) ``` 名前なし (クラシック) シャドウでは、`name` クエリパラメータは必要ありません。 **応答** 成功した場合、レスポンスには標準の HTTP ヘッダーに加えて、以下のコードと本体が含まれます。 ``` HTTP 200 Response body: Empty response state document ``` シャドウを削除しても、バージョン番号は 0 にリセットされないことに注意してください。 **Authorization** デバイスのシャドウを削除するには、呼び出し元に `iot:DeleteThingShadow` アクションの実行を許可するポリシーが必要です。Device Shadow サービスは、IAM 認証情報による署名バージョン 4、クライアント証明書による TLS 相互認証という、2 つの形式の認証を受け入れます。 以下に示しているのは、呼び出し元にデバイスのシャドウの削除を許可するポリシーの例です。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iot:DeleteThingShadow", "Resource": [ "arn:aws:iot:us-east-1:123456789012:thing/thing" ] } ] } ``` ## ListNamedShadowsForThing 指定されたモノのシャドウを一覧表示します。 **リクエスト** リクエストには標準の HTTP ヘッダーに加えて、以下の URI が含まれます。 ``` HTTP GET /api/things/shadow/ListNamedShadowsForThing/thingName?nextToken=nextToken&pageSize=pageSize Request body: (none) ``` nextToken 次の結果セットを取得するためのトークン。 この値は、ページングされた結果で返され、次のページを返す呼び出しで使用されます。 pageSize 各呼び出しで返すシャドウ名の数。「`nextToken`」も参照してください。 thingName 名前の付いたシャドウを一覧表示するモノの名前。 **応答** 成功した場合、レスポンスには標準の HTTP ヘッダーに加えて、以下のレスポンスコードと [シャドウ名リストレスポンスドキュメント](device-shadow-document.md#device-shadow-list-json) が含まれます。 **注記** 名前なし (クラシック) シャドウは、このリストに表示されません。クラシックシャドウしかない、または指定した`thingName` が存在しない場合、レスポンスは空のリストになります。 ``` HTTP 200 Response body: Shadow name list document ``` **Authorization** デバイスのシャドウをリスト化するには、呼び出し元に `iot:ListNamedShadowsForThing` アクションの実行を許可するポリシーが必要です。Device Shadow サービスは、IAM 認証情報による署名バージョン 4、クライアント証明書による TLS 相互認証という、2 つの形式の認証を受け入れます。 以下に示しているのは、呼び出し元にモノの名前付きシャドウの削除を許可するポリシーの例です。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iot:ListNamedShadowsForThing", "Resource": [ "arn:aws:iot:us-east-1:123456789012:thing/thing" ] } ] } ``` # Device Shadow MQTT トピック Device Shadow サービスでは、予約された MQTT トピックを使用することで、アプリケーションやデバイスがデバイスの状態情報 (シャドウ) を取得、更新、削除できるようにします。 Shadow トピックへのパブリッシュとサブスクライブにはトピックベースの権限付与が必要です。 AWS IoT には、既存のトピック構造に新しいトピックを追加する権限があります。この理由から、Shadow トピックへのサブスクリプションにワイルドカードを使用しないことをお勧めします。例えば、 が新しいシャドウトピック AWS IoT を導入`$aws/things/thingName/shadow/#`すると、このトピックフィルターに一致するトピックの数が増加する可能性があるため、 のようなトピックフィルターへのサブスクライブは避けてください。これらのトピックでパブリッシュされたメッセージの例については、「[シャドウとの相互作用](device-shadow-data-flow.md)」を参照してください。 シャドウは、名前付き、または名前のないもの (クラシック) にすることができます。それぞれで使用されるトピックは、トピックのプレフィックスでのみ異なります。この表は、各シャドウタイプで使用されるトピックのプレフィックスを示しています。 | *ShadowTopicPrefix* 値 | シャドウタイプ | | --- | --- | | \$1aws/things/thingName/shadow | 名前のない (クラシック) シャドウ | | \$1aws/things/thingName/shadow/name/shadowName | 名前付きシャドウ | 完全なトピックを作成するには、次のセクションに示すように、参照するシャドウのタイプの `ShadowTopicPrefix` を選択し、`thingName` と、`shadowName` (該当する場合) を対応する値に置き換え、トピックスタブにそれを追加します。 以下に示しているのは、Shadow とのやり取りに使用される MQTT トピックです。 **Topics** + [/get](#get-pub-sub-topic) + [/get/accepted](#get-accepted-pub-sub-topic) + [/get/rejected](#get-rejected-pub-sub-topic) + [/update](#update-pub-sub-topic) + [/update/delta](#update-delta-pub-sub-topic) + [/update/accepted](#update-accepted-pub-sub-topic) + [/update/documents](#update-documents-pub-sub-topic) + [/update/rejected](#update-rejected-pub-sub-topic) + [/delete](#delete-pub-sub-topic) + [/delete/accepted](#delete-accepted-pub-sub-topic) + [/delete/rejected](#delete-rejected-pub-sub-topic) ## /get デバイスのシャドウを取得するには、このトピックに空のメッセージをパブリッシュします。 ``` ShadowTopicPrefix/get ``` AWS IoT は、 [/get/accepted](#get-accepted-pub-sub-topic)または のいずれかに発行することで応答します[/get/rejected](#get-rejected-pub-sub-topic)。 ### ポリシーの例 以下に示しているのは、必要なポリシーの例です。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Publish" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/get" ] } ] } ``` ## /get/accepted AWS IoT は、デバイスのシャドウを返すときに、このトピックにレスポンスシャドウドキュメントを発行します。 ``` ShadowTopicPrefix/get/accepted ``` 詳細については、「[レスポンス状態ドキュメント](device-shadow-document.md#device-shadow-example-response-json)」を参照してください。 ### ポリシーの例 以下に示しているのは、必要なポリシーの例です。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/get/accepted" ] }, { "Effect": "Allow", "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/get/accepted" ] } ] } ``` ## /get/rejected AWS IoT は、デバイスのシャドウを返せない場合に、このトピックにエラーレスポンスドキュメントを発行します。 ``` ShadowTopicPrefix/get/rejected ``` 詳細については、「[エラーレスポンスドキュメント](device-shadow-document.md#device-shadow-example-error-json)」を参照してください。 ### ポリシーの例 以下に示しているのは、必要なポリシーの例です。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/get/rejected" ] }, { "Effect": "Allow", "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/get/rejected" ] } ] } ``` ## /update このトピックにリクエスト状態ドキュメントをパブリッシュして、デバイスのシャドウを更新します。 ``` ShadowTopicPrefix/update ``` メッセージ本文には、[部分的なリクエスト状態ドキュメント](device-shadow-document.md#device-shadow-example-request-json)が含まれています。 デバイスの状態を更新しようとするクライアントは、次のような `desired` プロパティを持つ JSON リクエスト状態ドキュメントを送信します。 ``` { "state": { "desired": { "color": "red", "power": "on" } } } ``` シャドウを更新するデバイスは、次のような `reported` プロパティを持つ JSON リクエスト状態ドキュメントを送信します。 ``` { "state": { "reported": { "color": "red", "power": "on" } } } ``` AWS IoT は、 [/update/accepted](#update-accepted-pub-sub-topic)または のいずれかに発行することで応答します[/update/rejected](#update-rejected-pub-sub-topic)。 ### ポリシーの例 以下に示しているのは、必要なポリシーの例です。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Publish" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/update" ] } ] } ``` ## /update/delta AWS IoT は、デバイスのシャドウの変更を受け入れると、このトピックにレスポンス状態ドキュメントを発行します。レスポンス状態ドキュメントには、 `desired` と `reported`の状態の異なる値が含まれています。 ``` ShadowTopicPrefix/update/delta ``` メッセージバッファには [/delta レスポンス状態ドキュメント](device-shadow-document.md#device-shadow-example-response-json-delta) が含まれています ### メッセージ本文の詳細 + `update/delta` にパブリッシュされたメッセージには、`desired` セクションと `reported` セクションとで異なる属性のみが含まれます。それら属性が、現在の更新メッセージに含まれていたか、 AWS IoTにすでに保存されていたかには関係ありません。`desired` セクションと `reported` セクションとで同じ属性は含まれません。 + 属性が `reported` セクションにあるが、`desired` セクションに同じ属性がない場合、その属性は含まれません。 + 属性が `desired` セクションにあるが、`reported` セクションに同じ属性がない場合、その属性は含まれません。 + 属性が `reported` セクションから削除されたが、`desired` セクションにまだある場合、その属性は含まれます。 ### ポリシーの例 以下に示しているのは、必要なポリシーの例です。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/update/delta" ] }, { "Effect": "Allow", "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/update/delta" ] } ] } ``` ## /update/accepted AWS IoT は、デバイスのシャドウの変更を受け入れると、このトピックに応答状態ドキュメントを発行します。 ``` ShadowTopicPrefix/update/accepted ``` メッセージバッファには [/accepted レスポンス状態ドキュメント](device-shadow-document.md#device-shadow-example-response-json-accepted) が含まれています ### ポリシーの例 以下に示しているのは、必要なポリシーの例です。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/update/accepted" ] }, { "Effect": "Allow", "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/update/accepted" ] } ] } ``` ## /update/documents AWS IoT シャドウの更新が正常に実行されるたびに、 はこのトピックに状態ドキュメントを発行します。 ``` ShadowTopicPrefix/update/documents ``` メッセージ本文には、 が含まれています[/documents レスポンス状態ドキュメント](device-shadow-document.md#device-shadow-example-response-json-documents) ### ポリシーの例 以下に示しているのは、必要なポリシーの例です。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/update/documents" ] }, { "Effect": "Allow", "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/update/documents" ] } ] } ``` ## /update/rejected AWS IoT は、デバイスのシャドウの変更を拒否すると、このトピックにエラーレスポンスドキュメントを発行します。 ``` ShadowTopicPrefix/update/rejected ``` メッセージ本文には、[エラーレスポンスドキュメント](device-shadow-document.md#device-shadow-example-error-json) が含まれています。 ### ポリシーの例 以下に示しているのは、必要なポリシーの例です。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/update/rejected" ] }, { "Effect": "Allow", "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/update/rejected" ] } ] } ``` ## /delete デバイスのシャドウを削除するには、削除トピックに空のメッセージをパブリッシュします。 ``` ShadowTopicPrefix/delete ``` メッセージの内容は無視されます。 シャドウを削除しても、バージョン番号は 0 にリセットされないことに注意してください。 AWS IoT は、 [/delete/accepted](#delete-accepted-pub-sub-topic)または のいずれかに発行することで応答します[/delete/rejected](#delete-rejected-pub-sub-topic)。 ### ポリシーの例 以下に示しているのは、必要なポリシーの例です。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Publish" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/delete" ] } ] } ``` ## /delete/accepted AWS IoT は、デバイスのシャドウが削除されると、このトピックにメッセージを発行します。 ``` ShadowTopicPrefix/delete/accepted ``` ### ポリシーの例 以下に示しているのは、必要なポリシーの例です。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/delete/accepted" ] }, { "Effect": "Allow", "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/delete/accepted" ] } ] } ``` ## /delete/rejected AWS IoT は、デバイスのシャドウを削除できない場合に、このトピックにエラーレスポンスドキュメントを発行します。 ``` ShadowTopicPrefix/delete/rejected ``` メッセージ本文には、[エラーレスポンスドキュメント](device-shadow-document.md#device-shadow-example-error-json) が含まれています。 ### ポリシーの例 以下に示しているのは、必要なポリシーの例です。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/delete/rejected" ] }, { "Effect": "Allow", "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/delete/rejected" ] } ] } ``` # Device Shadow サービスドキュメント Device Shadow サービスは JSON 仕様のすべてのルールに準拠します。値、オブジェクト、配列はデバイスのシャドウドキュメントに保存されます。 **Topics** + [シャドウドキュメントの例](#device-shadow-document-syntax) + [ドキュメントのプロパティ](#document-structure) + [delta 状態](#delta-state) + [シャドウドキュメントのバージョニング](#versioning) + [シャドウドキュメント内のクライアントトークン](#client-token) + [空のシャドウドキュメントのプロパティ](#device-shadow-empty-fields) + [シャドウドキュメント内の配列値](#device-shadow-arrays) ## シャドウドキュメントの例 Device Shadow サービスは、[REST API](device-shadow-rest-api.md) または [MQTT パブリッシュ/サブスクライブメッセージ](device-shadow-mqtt.md)を使用する UPDATE、GET、DELETE オペレーションで、以下のドキュメントを使用します。 **Topics** + [リクエスト状態ドキュメント](#device-shadow-example-request-json) + [レスポンス状態ドキュメント](#device-shadow-example-response-json) + [エラーレスポンスドキュメント](#device-shadow-example-error-json) + [シャドウ名リストレスポンスドキュメント](#device-shadow-list-json) ### リクエスト状態ドキュメント リクエスト状態ドキュメントの形式は次のとおりです。 ``` { "state": { "desired": { "attribute1": integer2, "attribute2": "string2", ... "attributeN": boolean2 }, "reported": { "attribute1": integer1, "attribute2": "string1", ... "attributeN": boolean1 } }, "clientToken": "token", "version": version } ``` + `state` — 更新は、指定したフィールドにのみ反映されます。通常、同じリクエストで `desired` または `reported` プロパティのいずれかを使用しますが、両方を使用することはありません。 + `desired` — デバイスで更新がリクエストされた state のプロパティと値。 + `reported` — デバイスによってレポートされた state のプロパティと値。 + `clientToken` — 使用する場合は、クライアントトークンによってリクエストとレスポンスを対応付けることができます。 + `version` — 使用した場合、指定したバージョンが最新バージョンと一致すると、Device Shadow サービスは更新を処理します。 ### レスポンス状態ドキュメント レスポンス状態ドキュメントはレスポンスタイプに応じて以下の形式になります。 #### /accepted レスポンス状態ドキュメント ``` { "state": { "desired": { "attribute1": integer2, "attribute2": "string2", ... "attributeN": boolean2 } }, "metadata": { "desired": { "attribute1": { "timestamp": timestamp }, "attribute2": { "timestamp": timestamp }, ... "attributeN": { "timestamp": timestamp } } }, "timestamp": timestamp, "clientToken": "token", "version": version } ``` #### /delta レスポンス状態ドキュメント ``` { "state": { "attribute1": integer2, "attribute2": "string2", ... "attributeN": boolean2 }, "metadata": { "attribute1": { "timestamp": timestamp }, "attribute2": { "timestamp": timestamp }, ... "attributeN": { "timestamp": timestamp } }, "timestamp": timestamp, "clientToken": "token", "version": version } ``` #### /documents レスポンス状態ドキュメント ``` { "previous" : { "state": { "desired": { "attribute1": integer2, "attribute2": "string2", ... "attributeN": boolean2 }, "reported": { "attribute1": integer1, "attribute2": "string1", ... "attributeN": boolean1 } }, "metadata": { "desired": { "attribute1": { "timestamp": timestamp }, "attribute2": { "timestamp": timestamp }, ... "attributeN": { "timestamp": timestamp } }, "reported": { "attribute1": { "timestamp": timestamp }, "attribute2": { "timestamp": timestamp }, ... "attributeN": { "timestamp": timestamp } } }, "version": version-1 }, "current": { "state": { "desired": { "attribute1": integer2, "attribute2": "string2", ... "attributeN": boolean2 }, "reported": { "attribute1": integer2, "attribute2": "string2", ... "attributeN": boolean2 } }, "metadata": { "desired": { "attribute1": { "timestamp": timestamp }, "attribute2": { "timestamp": timestamp }, ... "attributeN": { "timestamp": timestamp } }, "reported": { "attribute1": { "timestamp": timestamp }, "attribute2": { "timestamp": timestamp }, ... "attributeN": { "timestamp": timestamp } } }, "version": version }, "timestamp": timestamp, "clientToken": "token" } ``` #### レスポンス状態ドキュメントのプロパティ + `previous` — 更新が成功した後、更新前のオブジェクトの `state` が含まれます。 + `current` — 更新が成功した後、更新後のオブジェクトの `state` が含まれます。 + `state` + `reported` — モノが `reported` セクション内の任意のデータを報告し、リクエスト状態ドキュメントにあったフィールドだけを含む場合にのみ存在します。 + `desired` — デバイスが `desired` セクション内の任意のデータを報告し、リクエスト状態ドキュメントにあったフィールドだけを含む場合にのみ存在します。 + `metadata` — いつ状態が更新されたかを決定できるように、`desired` および `reported` セクションの属性ごとにタイムスタンプが含まれます。 + `timestamp` — レスポンスが生成されたエポック日時 AWS IoT。 + `clientToken` — `/update` トピックに有効な JSON を発行するときにクライアントトークンが使用された場合にのみ存在します。 + `version` — AWS IoTで共有されるデバイスのシャドウのドキュメントの現在のバージョン。ドキュメントの前バージョンから 1 ずつインクリメントされます。 ### エラーレスポンスドキュメント エラーレスポンスドキュメントの形式は次のとおりです。 ``` { "code": error-code, "message": "error-message", "timestamp": timestamp, "clientToken": "token" } ``` + `code` — エラーのタイプを示す HTTP レスポンスコード。 + `message` — 追加の情報を提供するテキストメッセージ。 + `timestamp` — レスポンスが生成された日時 AWS IoT。このプロパティはすべてのエラーレスポンスドキュメントに存在するわけではありません。 + `clientToken` — 発行されたメッセージでクライアントトークンが使用された場合にのみ表示されます。 詳細については、「[Device Shadow エラーメッセージ](device-shadow-error-messages.md)」を参照してください。 ### シャドウ名リストレスポンスドキュメント シャドウ名リストレスポンスドキュメントの形式は次のとおりです。 ``` { "results": [ "shadowName-1", "shadowName-2", "shadowName-3", "shadowName-n" ], "nextToken": "nextToken", "timestamp": timestamp } ``` + `results` — シャドウ名の配列。 + `nextToken` — シーケンス内の次のページを取得するためにページングされたリクエストで使用するトークン値。返すシャドウ名がなくなると、このプロパティは存在しません。 + `timestamp` — レスポンスが生成された日時 AWS IoT。 ## ドキュメントのプロパティ デバイスのシャドウドキュメントには、以下のプロパティがあります。 `state` `desired` デバイスの desired 状態。アプリケーションは、ドキュメントのこの部分に書き込んで、デバイスの状態を直接更新できます。そのために、デバイスに接続する必要はありません。 `reported` デバイスの reported 状態。デバイスはドキュメントのこの部分に書き込んで、デバイスの新しい状態を報告します。アプリは、ドキュメントのこの部分を読み取り、デバイスの last-reported 状態を判断します。 `metadata` ドキュメントの `state` セクションに保存されたデータに関する情報。この情報には `state` セクション内の属性ごとにタイムスタンプ (エポック時間) が含まれており、いつそれらの属性が更新されたかを決定できます。 メタデータは、サービスの制限または料金に関連するドキュメントサイズに影響を与えません。詳細については、「[AWS IoT サービス制限](https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html#limits_iot)」を参照してください。 `timestamp` メッセージがいつ送信されたかを示します AWS IoT。メッセージ内のタイムスタンプと、 `desired` または `reported` セクションの個々の属性のタイムスタンプを使用すると、デバイスに内部クロックがない場合でも、デバイスはプロパティの経過時間を判断できます。 `clientToken` デバイスに一意の文字列。MQTT 環境でレスポンスをリクエストに関連付けるために使用されます。 `version` ドキュメントのバージョン。ドキュメントが更新されるたびに、このバージョン番号がインクリメントされます。更新されるドキュメントのバージョンが最新になるように使用されます。 詳細については、「[シャドウドキュメントの例](#device-shadow-document-syntax)」を参照してください。 ## delta 状態 delta 状態は、`desired` 状態と `reported` 状態の違いを含む virtual 型の状態です。`desired` セクションに含まれるが、`reported` セクションに含まれないフィールドは、差分に含まれます。`reported` セクションに含まれるが、`desired` セクションに含まれないフィールドは、差分に含まれません。差分にはメタデータが含まれ、その値は `desired` フィールドのメタデータに一致します。以下に例を示します。 ``` { "state": { "desired": { "color": "RED", "state": "STOP" }, "reported": { "color": "GREEN", "engine": "ON" }, "delta": { "color": "RED", "state": "STOP" } }, "metadata": { "desired": { "color": { "timestamp": 12345 }, "state": { "timestamp": 12345 } }, "reported": { "color": { "timestamp": 12345 }, "engine": { "timestamp": 12345 } }, "delta": { "color": { "timestamp": 12345 }, "state": { "timestamp": 12345 } } }, "version": 17, "timestamp": 123456789 } } ``` ネストされたオブジェクトが異なると、差分にはルートへのパスが含まれます。 ``` { "state": { "desired": { "lights": { "color": { "r": 255, "g": 255, "b": 255 } } }, "reported": { "lights": { "color": { "r": 255, "g": 0, "b": 255 } } }, "delta": { "lights": { "color": { "g": 255 } } } }, "version": 18, "timestamp": 123456789 } ``` Device Shadow サービスは、`desired` 状態の各フィールドを反復処理し、`reported` 状態と比較することで、差分を計算します。 配列は値のように扱われます。`desired` セクションの配列が `reported` セクションの配列に一致しない場合は、desired 配列全体が差分にコピーされます。 ## シャドウドキュメントのバージョニング Device Shadow サービスは、リクエストとレスポンスの両方の更新メッセージごとにバージョニングをサポートします。つまり、シャドウが更新されるたびに、JSON ドキュメントのバージョンが増分されます。これにより、以下の 2 つのことが確実になります。 + クライアントは、古いバージョン番号を使用して Shadow を上書きしようとした場合、エラーを受け取ることができます。デバイスのシャドウを更新するには、再同期する必要があることがクライアントに通知されます。 + クライアントは、受信したメッセージ内のバージョンが自らで保存しているバージョンより古い場合、そのメッセージに基づいてアクションを実行しないことを決定できます。 クライアントは、シャドウドキュメントにバージョンを含めないことで、バージョン一致を回避できます。 ## シャドウドキュメント内のクライアントトークン クライアントトークンを MQTT ベースのメッセージングで使用して、リクエストとそのレスポンスに同じクライアントトークンが含まれていることを確認できます。これにより確実にレスポンスとリクエストが関連付けられます。 **注記** クライアントトークンは 64 バイトを超えない範囲にします。64 バイトを超えるクライアントトークンは、400 (不適切なリクエスト) レスポンスと*Invalid clientToken* エラーメッセージの原因となります。 ## 空のシャドウドキュメントのプロパティ シャドウドキュメントの `reported` プロパティと `desired` プロパティは、現在のシャドウ状態に適用されない場合は空にすることも、省略することもできます。たとえば、シャドウドキュメントには、desired 状態がある場合にのみ、`desired` プロパティが含まれます。次に、`desired` プロパティのない状態ドキュメントの有効な例を示します。 ``` { "reported" : { "temp": 55 } } ``` デバイスによってシャドウが更新されていない場合など、`reported` プロパティは空にすることもできます。 ``` { "desired" : { "color" : "RED" } } ``` 更新によって `desired` または `reported` プロパティが null になると、ドキュメントから削除されます。次に、`desired` プロパティを `null` に設定して削除する方法を示します。たとえば、デバイスの状態を更新するときにこれを行うことができます。 ``` { "state": { "reported": { "color": "red" }, "desired": null } } ``` シャドウドキュメントには、`desired` プロパティと `reported` プロパティのいずれも持たないため、シャドウドキュメントは空になります。これは、空で有効なシャドウドキュメントの例です。 ``` { } ``` ## シャドウドキュメント内の配列値 シャドウでは、配列がサポートされていますが、配列に対する更新により配列全体が置き換わる点では、通常の値として扱われます。配列の一部を更新することはできません。 初期状態: ``` { "desired" : { "colors" : ["RED", "GREEN", "BLUE" ] } } ``` 更新: ``` { "desired" : { "colors" : ["RED"] } } ``` 最終状態: ``` { "desired" : { "colors" : ["RED"] } } ``` 配列に null 値を含めることはできません。たとえば、以下の配列は有効ではなく、拒否されます。 ``` { "desired" : { "colors" : [ null, "RED", "GREEN" ] } } ``` # Device Shadow エラーメッセージ Device Shadow サービスは、状態ドキュメントの変更の試みが失敗したときに、MQTT を介して error トピックにメッセージをパブリッシュします。このメッセージは、いずれかの予約された `$aws` トピックへの発行リクエストに対するレスポンスとしてのみ発行されます。クライアントが REST API を使用してドキュメントを更新する場合は、そのレスポンスの一部として HTTP エラーコードを受け取り、MQTT エラーメッセージは発行されません。 **** | HTTP エラーコード | エラーメッセージ | | --- | --- | | 400 (Bad Request) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/iot/latest/developerguide/device-shadow-error-messages.html) | | 401 (Unauthorized) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/iot/latest/developerguide/device-shadow-error-messages.html) | | 403 (Forbidden) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/iot/latest/developerguide/device-shadow-error-messages.html) | | 404 (Not Found) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/iot/latest/developerguide/device-shadow-error-messages.html) | | 409 (Conflict) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/iot/latest/developerguide/device-shadow-error-messages.html) | | 413 (Payload Too Large) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/iot/latest/developerguide/device-shadow-error-messages.html) | | 415 (Unsupported Media Type) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/iot/latest/developerguide/device-shadow-error-messages.html) | | 429 (Too Many Requests) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/iot/latest/developerguide/device-shadow-error-messages.html) | | 500 (Internal Server Error) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/iot/latest/developerguide/device-shadow-error-messages.html) |