翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# 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"
]
}
]
}
```