Device Shadow REST API - AWS IoT
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

Device Shadow REST API

影子将显示用于更新状态信息的以下 URI:

https://endpoint/things/thingName/shadow

您的 AWS 账户具有特定的终端节点。要检索您的终端节点,请使用 describe-endpoint 命令。终端节点的格式如下:

identifier.iot.region.amazonaws.com

shadow REST API 遵循协议中所述的相同 HTTPS 协议/端口映射。

GetThingShadow

获取指定事物的影子。

响应状态文档包括 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

有关更多信息,请参阅响应状态文档示例

授权

要检索影子,需要一项允许调用方执行 iot:GetThingShadow 操作的策略。Device Shadow 服务接受两种形式的身份验证:使用 IAM 凭证的签名版本 4 或使用客户端证书的 TLS 双向身份验证。

以下是允许调用方检索设备的影子的示例策略:

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

UpdateThingShadow

更新指定事物的影子。

更新仅影响请求状态文档中指定的字段。值为 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

有关更多信息,请参阅响应状态文档示例

授权

要更新影子,需要一项允许调用方执行 iot:UpdateThingShadow 操作的策略。Device Shadow 服务接受两种形式的身份验证:使用 IAM 凭证的签名版本 4 或使用客户端证书的 TLS 双向身份验证。

以下是允许调用方更新设备的影子的示例策略:

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

DeleteThingShadow

删除指定事物的影子。

请求

该请求包括标准的 HTTP 标头以及以下 URI:

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

未命名的(经典)影子不需要使用 name 查询参数。

响应

请求成功后,响应将包括标准的 HTTP 标头以及以下代码和正文:

HTTP 200 Response body: Empty response state document

授权

要删除设备的影子,需要一项允许调用方执行 iot:DeleteThingShadow 操作的策略。Device Shadow 服务接受两种形式的身份验证:使用 IAM 凭证的签名版本 4 或使用客户端证书的 TLS 双向身份验证。

以下是允许调用方删除设备的影子的示例策略:

{ "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 标头以及以下响应代码和影子名称列表响应文档

注意

未命名的(经典)影子不会显示在该列表中。

HTTP 200 Response body: Shadow name list document

授权

要删除设备的影子,需要一项允许调用方执行 iot:ListNamedShadowsForThing 操作的策略。Device Shadow 服务接受两种形式的身份验证:使用 IAM 凭证的签名版本 4 或使用客户端证书的 TLS 双向身份验证。

以下是一个示例策略,它允许调用方列出事物的命名影子:

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