Device Shadow MQTT トピック - AWS(AWS) IoT コア

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

Device Shadow MQTT トピック

Device Shadow サービスでは、予約された MQTT トピックを使用することで、アプリケーションやデバイスがデバイスの状態情報 (シャドウ) を取得、更新、削除できるようにします。

Shadow トピックへのパブリッシュとサブスクライブにはトピックベースの権限付与が必要です。AWS IoT には、既存のトピック構造に新しいトピックを追加する権限があります。この理由から、Shadow トピックへのサブスクリプションにワイルドカードを使用しないことをお勧めします。たとえば、$aws/things/thingName/shadow/# のようなトピックフィルタへのサブスクライブは避けてください。AWS IoT が新しい Shadow トピックを追加すると、このトピックフィルタに一致するトピックの数が増える可能性があるためです。これらのトピックでパブリッシュされたメッセージの例については、「シャドウとの相互作用」を参照してください。

シャドウは、名前付き、または名前のないもの (クラシック) にすることができます。それぞれで使用されるトピックは、トピックのプレフィックスでのみ異なります。この表は、各シャドウタイプで使用されるトピックのプレフィックスを示しています。

ShadowTopicPrefix value シャドウタイプ
$aws/things/thingName/shadow 名前のない (クラシック) シャドウ
$aws/things/thingName/shadow/name/shadowName 名前付きシャドウ

完全なトピックを作成するには、次のセクションに示すように、参照するシャドウのタイプの ShadowTopicPrefix を選択し、thingName と、shadowName (該当する場合) を対応する値に置き換え、トピックスタブにそれを追加します。

以下に示しているのは、Shadow とのやり取りに使用される MQTT トピックです。

/get

デバイスのシャドウを取得するには、このトピックに空のメッセージをパブリッシュします。

ShadowTopicPrefix/get

AWS IoT は /get/accepted または /get/rejected のいずれかにパブリッシュすることで応答します。

ポリシーの例

以下に示しているのは、必要なポリシーの例です。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Publish" ], "Resource": [ "arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/get" ] } ] }

/get/accepted

AWS IoT は、デバイスのシャドウを返すとき、このトピックにレスポンスシャドウドキュメントを発行します。

ShadowTopicPrefix/get/accepted

詳細については、レスポンス状態ドキュメント を参照してください。

ポリシーの例

以下に示しているのは、必要なポリシーの例です。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:region:account:topicfilter/$aws/things/thingName/shadow/get/accepted" ] }, { "Effect": "Allow", "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/get/accepted" ] } ] }

/get/rejected

AWS IoT は、デバイスのシャドウを返せないとき、このトピックにエラーレスポンスドキュメントをパブリッシュします。

ShadowTopicPrefix/get/rejected

詳細については、エラーレスポンスドキュメント を参照してください。

ポリシーの例

以下に示しているのは、必要なポリシーの例です。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:region:account:topicfilter/$aws/things/thingName/shadow/get/rejected" ] }, { "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/get/rejected" ] } ] }

/update

このトピックにリクエスト状態ドキュメントをパブリッシュして、デバイスのシャドウを更新します。

ShadowTopicPrefix/update

メッセージ本文には、部分的なリクエスト状態ドキュメントが含まれています。

デバイスの状態を更新しようとするクライアントは、次のような desired プロパティを持つ JSON リクエスト状態ドキュメントを送信します。

{ "state": { "desired": { "color": "red", "power": "on" } } }

シャドウを更新するデバイスは、次のような reported プロパティを持つ JSON リクエスト状態ドキュメントを送信します。

{ "state": { "reported": { "color": "red", "power": "on" } } }

AWS IoT は /update/accepted または /update/rejected のいずれかにパブリッシュすることで応答します。

ポリシーの例

以下に示しているのは、必要なポリシーの例です。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Publish" ], "Resource": [ "arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/update" ] } ] }

/update/delta

AWS IoT は、デバイスのシャドウに対する変更を受け入れると、このトピックにレスポンス状態ドキュメントを発行します。リクエスト状態ドキュメントには、desired 状態と reported 状態とで異なる値が含まれます。

ShadowTopicPrefix/update/delta

メッセージバッファには /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:region:account:topicfilter/$aws/things/thingName/shadow/update/delta" ] }, { "Effect": "Allow", "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/update/delta" ] } ] }

/update/accepted

AWS IoT は、デバイスのシャドウに対する変更を受け入れると、このトピックにレスポンス状態ドキュメントをパブリッシュします。

ShadowTopicPrefix/update/accepted

メッセージバッファには /accepted レスポンス状態ドキュメント が含まれています。

ポリシーの例

以下に示しているのは、必要なポリシーの例です。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:region:account:topicfilter/$aws/things/thingName/shadow/update/accepted" ] }, { "Effect": "Allow", "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/update/accepted" ] } ] }

/update/documents

AWS IoT は、Shadow に対する更新が正常に実行されるたびに、このトピックに状態ドキュメントをパブリッシュします。

ShadowTopicPrefix/update/documents

メッセージ本文には、/documents レスポンス状態ドキュメント が含まれています。

ポリシーの例

以下に示しているのは、必要なポリシーの例です。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:region:account:topicfilter/$aws/things/thingName/shadow/update/documents" ] }, { "Effect": "Allow", "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/update/documents" ] } ] }

/update/rejected

AWS IoT は、デバイスのシャドウに対する変更を拒否すると、このトピックにエラーレスポンスドキュメントをパブリッシュします。

ShadowTopicPrefix/update/rejected

メッセージ本文には、エラーレスポンスドキュメント が含まれています。

ポリシーの例

以下に示しているのは、必要なポリシーの例です。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:region:account:topicfilter/$aws/things/thingName/shadow/update/rejected" ] }, { "Effect": "Allow", "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/update/rejected" ] } ] }

/delete

デバイスのシャドウを削除するには、削除トピックに空のメッセージをパブリッシュします。

ShadowTopicPrefix/shadow/delete

メッセージの内容は無視されます。

AWS IoT は /delete/accepted または /delete/rejected のいずれかにパブリッシュすることで応答します。

ポリシーの例

以下に示しているのは、必要なポリシーの例です。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Publish" ], "Resource": [ "arn:aws:iot:region:account: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:region:account:topicfilter/$aws/things/thingName/shadow/delete/accepted" ] }, { "Effect": "Allow", "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/delete/accepted" ] } ] }

/delete/rejected

AWS IoT は、デバイスのシャドウを削除できないとき、このトピックにエラーレスポンスドキュメントをパブリッシュします。

ShadowTopicPrefix/delete/rejected

メッセージ本文には、エラーレスポンスドキュメント が含まれています。

ポリシーの例

以下に示しているのは、必要なポリシーの例です。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:region:account:topicfilter/$aws/things/thingName/shadow/delete/rejected" ] }, { "Effect": "Allow", "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/delete/rejected" ] } ] }