Device Shadow REST API
A shadow exposes the following URI for updating state information:
https://
account-specific-prefix
-ats.iot.region
.amazonaws.com/things/thingName
/shadow
The endpoint is specific to your AWS account. To find your endpoint, you can:
-
Use the describe-endpoint command from the AWS CLI.
-
Use the AWS IoT console settings. In Settings, the endpoint is listed under Custom endpoint
-
Use the AWS IoT console thing details page. In the console:
-
Open Manage and under Manage, choose Things.
-
In the list of things, choose the thing for which you want to get the endpoint URI.
-
Choose the Device Shadows tab and choose your shadow. You can view the endpoint URI in the Device Shadow URL section of the Device Shadow details page.
-
The format of the endpoint is as follows:
identifier
.iot.region
.amazonaws.com
The shadow REST API follows the same HTTPS protocols/port mappings as described in Device communication protocols.
Note
To use the APIs, you must use iotdevicegateway
as the service name
for authentication. For more information, see IoTDataPlane.
You can also use the API to create a named shadow by providing
name=
as part of the query
parameter of the API.shadowName
GetThingShadow
Gets the shadow for the specified thing.
The response state document includes the delta between the desired
and reported
states.
Request
The request includes the standard HTTP headers plus the following URI:
HTTP GET https://
endpoint
/things/thingName
/shadow?name=shadowName
Request body: (none)
The name
query parameter is not required for unnamed (classic)
shadows.
Response
Upon success, the response includes the standard HTTP headers plus the following code and body:
HTTP 200 Response Body:
response state document
For more information, see Example Response State Document.
Authorization
Retrieving a shadow requires a policy that allows the caller to perform the
iot:GetThingShadow
action. The Device Shadow service accepts
two forms of authentication: Signature Version 4 with IAM credentials or TLS
mutual authentication with a client certificate.
The following is an example policy that allows a caller to retrieve a device's shadow:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iot:GetThingShadow", "Resource": [ "arn:aws:iot:
region
:account
:thing/thing
" ] } ] }
UpdateThingShadow
Updates the shadow for the specified thing.
Updates affect only the fields specified in the request state document. Any field
with a value of null
is removed from the device's shadow.
Request
The request includes the standard HTTP headers plus the following URI and body:
HTTP POST https://
endpoint
/things/thingName
/shadow?name=shadowName
Request body:request state document
The name
query parameter is not required for unnamed (classic)
shadows.
For more information, see Example Request State Document.
Response
Upon success, the response includes the standard HTTP headers plus the following code and body:
HTTP 200 Response body:
response state document
For more information, see Example Response State Document.
Authorization
Updating a shadow requires a policy that allows the caller to perform the
iot:UpdateThingShadow
action. The Device Shadow service accepts
two forms of authentication: Signature Version 4 with IAM credentials or TLS
mutual authentication with a client certificate.
The following is an example policy that allows a caller to update a device's shadow:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iot:UpdateThingShadow", "Resource": [ "arn:aws:iot:
region
:account
:thing/thing
" ] } ] }
DeleteThingShadow
Deletes the shadow for the specified thing.
Request
The request includes the standard HTTP headers plus the following URI:
HTTP DELETE https://
endpoint
/things/thingName
/shadow?name=shadowName
Request body: (none)
The name
query parameter is not required for unnamed (classic)
shadows.
Response
Upon success, the response includes the standard HTTP headers plus the following code and body:
HTTP 200 Response body:
Empty response state document
Note that deleting a shadow does not reset its version number to 0.
Authorization
Deleting a device's shadow requires a policy that allows the caller to perform
the iot:DeleteThingShadow
action. The Device Shadow service accepts
two forms of authentication: Signature Version 4 with IAM credentials or TLS
mutual authentication with a client certificate.
The following is an example policy that allows a caller to delete a device's shadow:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iot:DeleteThingShadow", "Resource": [ "arn:aws:iot:
region
:account
:thing/thing
" ] } ] }
ListNamedShadowsForThing
Lists the shadows for the specified thing.
Request
The request includes the standard HTTP headers plus the following URI:
HTTP GET /api/things/shadow/ListNamedShadowsForThing/
thingName
?nextToken=nextToken
&pageSize=pageSize
Request body: (none)
- nextToken
-
The token to retrieve the next set of results.
This value is returned on paged results and is used in the call that returns the next page.
- pageSize
-
The number of shadow names to return in each call. See also
nextToken
. - thingName
-
The name of the thing for which to list the named shadows.
Response
Upon success, the response includes the standard HTTP headers plus the following response code and a Shadow name list response document.
Note
The unnamed (classic) shadow does not appear in this list. The response is an
empty list if you only have a classic shadow or if the thingName
you specify doesn't exist.
HTTP 200 Response body:
Shadow name list document
Authorization
Listing a device's shadow requires a policy that allows the caller to perform
the iot:ListNamedShadowsForThing
action. The Device Shadow service
accepts two forms of authentication: Signature Version 4 with IAM credentials
or TLS mutual authentication with a client certificate.
The following is an example policy that allows a caller to list a thing's named shadows:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iot:ListNamedShadowsForThing", "Resource": [ "arn:aws:iot:
region
:account
:thing/thing
" ] } ] }