Device Shadow の REST API - AWS IoT Core

Device Shadow の REST API

Shadow は状態情報の更新用に以下の URI を公開します。

https://endpoint:8443/things/thingName/shadow

エンドポイントは AWS アカウント に固有のものです。エンドポイントを見つけるには、以下を実行します。

  • AWS CLI の describe-endpoint コマンドを使用します。

  • AWS IoT コンソールの設定を使用します。[Settings] (設定) で、エンドポイントは [Custom endpoint] (カスタムエンドポイント) の下に表示されます

  • AWS IoT コンソールのモノの詳細を使用します。[Manage] (管理) を開きます。[Manage] (管理) で [Things] (モノ) を選択し、モノのリストでモノを選択して開きます。[Thing detail] (モノの詳細) のページの左側のナビゲーションで [Interact] (操作) を選択し、ページの [HTTPS] セクションにエンドポイント URI を表示します。

エンドポイントの形式は以下のとおりです。

identifier.iot.region.amazonaws.com

シャドウの REST API は、「」で説明されているものと同じ HTTPS プロトコル/ポートマッピングに従いますデバイス通信プロトコル

GetThingShadow

指定したモノの Shadow を取得します。

レスポンス状態ドキュメントには、desired 状態と reported 状態との差分が含まれます。

Request

リクエストには標準の HTTP ヘッダーに加えて、以下の URI が含まれます。

HTTP GET https://endpoint:8443/things/thingName/shadow?name=shadowName Request body: (none)

名前なし (クラシック) シャドウでは、name クエリパラメータは必要ありません。

Response

成功した場合、レスポンスには標準の HTTP ヘッダーに加えて、以下のコードと本体が含まれます。

HTTP 200 Response Body: response state document

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

Authorization

Shadow を取得するには、呼び出し元に iot:GetThingShadow アクションの実行を許可するポリシーが必要です。Device Shadow サービスは、IAM 認証情報による署名バージョン 4、クライアント証明書による TLS 相互認証という、2 つの形式の認証を受け入れます。

以下に示しているのは、呼び出し元にデバイスのシャドウの取得を許可するポリシーの例です。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iot:GetThingShadow", "Resource": [ "arn:aws:iot:region:account:thing/thing" ] } ] }

UpdateThingShadow

指定したモノの Shadow を更新します。

更新は、リクエスト状態ドキュメントで指定したフィールドにのみ反映されます。値が null のフィールドはすべてデバイスのシャドウから削除されます。

Request

リクエストには標準の HTTP ヘッダーに加えて、以下の URI と本体が含まれます。

HTTP POST https://endpoint:8443/things/thingName/shadow?name=shadowName Request body: request state document

名前なし (クラシック) シャドウでは、name クエリパラメータは必要ありません。

詳細については、「リクエスト状態ドキュメントの例」を参照してください。

Response

成功した場合、レスポンスには標準の HTTP ヘッダーに加えて、以下のコードと本体が含まれます。

HTTP 200 Response body: response state document

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

Authorization

Shadow を更新するには、呼び出し元に iot:UpdateThingShadow アクションの実行を許可するポリシーが必要です。Device Shadow サービスは、IAM 認証情報による署名バージョン 4、クライアント証明書による TLS 相互認証という、2 つの形式の認証を受け入れます。

以下に示しているのは、呼び出し元にデバイスのシャドウの更新を許可するポリシーの例です。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iot:UpdateThingShadow", "Resource": [ "arn:aws:iot:region:account:thing/thing" ] } ] }

DeleteThingShadow

指定したモノの Shadow を削除します。

Request

リクエストには標準の HTTP ヘッダーに加えて、以下の URI が含まれます。

HTTP DELETE https://endpoint:8443/things/thingName/shadow?name=shadowName Request body: (none)

名前なし (クラシック) シャドウでは、name クエリパラメータは必要ありません。

Response

成功した場合、レスポンスには標準の 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:region:account:thing/thing" ] } ] }

ListNamedShadowsForThing

指定されたモノのシャドウを一覧表示します。

Request

リクエストには標準の HTTP ヘッダーに加えて、以下の URI が含まれます。

HTTP GET /api/things/shadow/ListNamedShadowsForThing/thingName?nextToken=nextToken&pageSize=pageSize Request body: (none)
nextToken

次の結果セットを取得するためのトークン。

この値は、ページングされた結果で返され、次のページを返す呼び出しで使用されます。

pageSize

各呼び出しで返すシャドウ名の数。「nextToken」も参照してください。

thingName

名前の付いたシャドウを一覧表示するモノの名前。

Response

成功した場合、レスポンスには標準の HTTP ヘッダーに加えて、以下のレスポンスコードと が含まれますシャドウ名リストレスポンスドキュメント

注記

名前なし (クラシック) シャドウは、このリストに表示されません。

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:region:account:thing/thing" ] } ] }