Shadow

AWS

Shadow

The Device Shadow supports named and classic (unnamed) shadows. A device can have multiple named shadows and one classic shadow.

Every shadow action consists of a request topic, a successful response topic (accepted), and an error response topic (rejected). Shadows can be named or unnamed (classic). The topics used by each differ only in the topic prefix. This table shows the topic prefix used by each shadow type.

Shadow type	ShadowTopicPrefix
Classic shadow	`$aws/things/{clientId}/shadow`
Named shadow	`$aws/things/{clientId}/shadow/name/{shadowName}`

To create a complete topic, select the ShadowTopicPrefix and then append that with the topic stub. Topics are case sensitive.

Update Shadow

Creates or updates the contents of an existing shadow with the state information provided in the message body. When the shadow’s state changes, the difference between the desired and the reported states is sent to /delta topic.

Operation	Topic	Payload
Request	`{ShadowTopicPrefix}/update`	Request State Document
Success Response	`{ShadowTopicPrefix}/update/accepted` `{ShadowTopicPrefix}/update/delta` `{ShadowTopicPrefix}/update/documents`	Response State Document /accepted Response State Document /delta Response State Document /documents
Failure Response	`{ShadowTopicPrefix}/update/rejected`	Shadow Error

Get Shadow

Retrieves a current shadow document that contains the complete state of the shadow, including metadata.

Operation	Topic	Payload
Request	`{ShadowTopicPrefix}/get`	Empty
Success Response	`{ShadowTopicPrefix}/get/accepted`	Response State Document /accepted
Failure Response	`{ShadowTopicPrefix}/get/rejected`	Shadow Error

Delete Shadow

Deletes the device shadow and its content.

Operation	Topic	Payload
Request	`{ShadowTopicPrefix}/delete`	Empty
Success Response	`{ShadowTopicPrefix}/delete/accepted`	Response State Document /accepted
Failure Response	`{ShadowTopicPrefix}/delete/rejected`	Shadow Error

Message Structure

Request State Document

{
    "state": {
            "reported": {
            "attribute1": integer1,
            "attribute2": "string1",
            ...
            "attributeN": boolean1
        }
    },
    "clientToken": "token",
    "version": version
}

reported - The state properties and values reported by the device.
clientToken - If used, you can match the request and corresponding response by the client token.
version - If used, the Device Shadow service processes the update only if the specified version matches the latest version it has.

Response State Document

/accepted

{
    "state": {
        "desired": {
            "attribute1": integer2,
            "attribute2": "string2",
            ...
            "attributeN": boolean2
        }
    },
    "metadata": {
        "desired": {
            "attribute1": {
                "timestamp": timestamp
            },
            "attribute2": {
                "timestamp": timestamp
            },
            ...
            "attributeN": {
                "timestamp": timestamp
            }
        }
    },
    "timestamp": timestamp,
    "clientToken": "token",
    "version": version
}

/delta

{
    "state": {
        "attribute1": integer2,
        "attribute2": "string2",
        ...
        "attributeN": boolean2
        },
    "metadata": {
        "attribute1": {
            "timestamp": timestamp
        },
        "attribute2": {
            "timestamp": timestamp
        },
        ...
        "attributeN": {
            "timestamp": timestamp
        }
    },
    "timestamp": timestamp,
    "clientToken": "token",
    "version": version
}

/documents

{
  "previous" : {
    "state": {
        "desired": {
            "attribute1": integer2,
            "attribute2": "string2",
            ...
            "attributeN": boolean2
        },
        "reported": {
            "attribute1": integer1,
            "attribute2": "string1",
            ...
            "attributeN": boolean1
        }
    },
    "metadata": {
        "desired": {
            "attribute1": {
                "timestamp": timestamp
            },
            "attribute2": {
                "timestamp": timestamp
            },
            ...
            "attributeN": {
                "timestamp": timestamp
            }
        },
        "reported": {
            "attribute1": {
                "timestamp": timestamp
            },
            "attribute2": {
                "timestamp": timestamp
            },
            ...
            "attributeN": {
                "timestamp": timestamp
            }
        }
    },
    "version": version-1
  },
  "current": {
    "state": {
        "desired": {
            "attribute1": integer2,
            "attribute2": "string2",
            ...
            "attributeN": boolean2
        },
        "reported": {
            "attribute1": integer2,
            "attribute2": "string2",
            ...
            "attributeN": boolean2
        }
    },
    "metadata": {
        "desired": {
            "attribute1": {
                "timestamp": timestamp
            },
            "attribute2": {
                "timestamp": timestamp
            },
            ...
            "attributeN": {
                "timestamp": timestamp
            }
        },
        "reported": {
            "attribute1": {
                "timestamp": timestamp
            },
            "attribute2": {
                "timestamp": timestamp
            },
            ...
            "attributeN": {
                "timestamp": timestamp
            }
        }
    },
    "version": version
  },
  "timestamp": timestamp,
  "clientToken": "token"
}

previous - After a successful update, contains the state of the object before the update.
current - After a successful update, contains the state of the object after the update.
reported - Present only if the reported section is updated, containing only fields that were in the requested state document.
desired - Present only if desired section is updated and contains only fields that were in the request state document
delta - Present only if the desired data differs from the shadow’s current reported data.
metadata - Contains the timestamps for each attribute in the desired and reported sections so that you can determine when the state was updated.
timestamp - The Epoch date and time the response was generated
clientToken - Present only if a client token was used when publishing valid JSON to the /update topic.
version - The current version of the document for the device’s shadow shared in IoT. It is increased by one over the previous version of the document.

Shadow Error

{
    "code": error-code,
    "message": "error-message",
    "timestamp": timestamp,
    "clientToken": "token"
}

code - An HTTP response code that indicates the type of error.
message - A message that provides additional information.
timestamp - The date and time the response was generated. This property is not present in all error response documents.
clientToken - Present only if a client token was used in the published message.

Error Codes

HTTP error code	Error messages
400 (Bad Request)	Invalid JSON Missing required node: state State node must be an object Desired node must be an object Reported node must be an object Invalid version Invalid clientToken JSON contains too many levels of nesting State contains an invalid node
401	Unauthorized
403	Forbidden
404	Thing not found No shadow exists with name: shadowName
409	Version conflict
413	The payload exceeds the maximum size allowed
415	Unsupported documented encoding
429	Too Many Requests
500	Internal Server Error

Limitations

The maximum number of levels in the desired or reported section of a JSON device state document is 5.
Maximum size of a device shadow name is 64 bytes of UTF-8 encoded characters.
Each individual shadow document must be 8 KB or less in size. Metadata doesn’t contribute to the document size.
Supported Encoding is UTF-8.