Device Shadow の REST API

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

https://account-specific-prefix-ats.iot.region.amazonaws.com/things/thingName/shadow

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

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

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

• AWS IoT コンソールのモノの詳細ページを使用します。コンソールで:

  1. [Manage] (管理) を展開し、[Manage] (管理) で [Things] (モノ) をクリックします。

  2. モノのリストで、エンドポイント URI を取得するモノを選択します。

  3. [Device Shadows] (デバイスシャドウ) タブをクリックし、シャドウを選択します。エンドポイント URI は、[Device Shadow details] (デバイスシャドウの詳細) ページの [Device Shadow URL] (デバイスシャドウの URL) セクションで確認できます。

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

identifier.iot.region.amazonaws.com

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

注記

API を使用するには、iotdevicegateway を認証のサービス名として使用する必要があります。詳細については、「 IoTDataPlane 」を参照してください。

また、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

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

認証

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 のフィールドはすべてデバイスのシャドウから削除されます。

リクエスト

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

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

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

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

レスポンス

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

HTTP 200
Response body: response state document

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

認証

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 を削除します。

リクエスト

リクエストには標準の 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 にリセットされないことに注意してください。

認証

デバイスのシャドウを削除するには、呼び出し元に 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

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

リクエスト

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

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

nextToken

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

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

pageSize

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

thingName

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

レスポンス

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

注記

名前なし (クラシック) シャドウは、このリストに表示されません。クラシックシャドウしかない、または指定したthingName が存在しない場合、レスポンスは空のリストになります。

HTTP 200
Response body: Shadow name list document

認証

デバイスのシャドウをリスト化するには、呼び出し元に 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"
      ]
    }
  ]
}