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

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

Device Shadow REST API

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

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

终端节点特定于您的 Amazon Web Services 账户。要查找端点,您可以:

  • 从 Amazon CLI 使用 describe-endpoint 命令。

  • 使用 Amazon IoT 控制台设置。在 Settings(设置),端点将列在 Custom endpoint(自定义端点)下。

  • 使用 Amazon IoT 控制台事物详细信息页面。在控制台中,执行以下操作:

    1. 打开 Manage(管理),并在 Manage(管理)中,选择 Things(事物)。

    2. 在事物列表中,选择要获取端点 URI 的事物。

    3. 选择 Device Shadows 选项卡,然后选择影子。您可以在 Device Shadow details(Device Shadow 详细信息)页面的 Device Shadow URL 部分查看端点 URI。

终端节点的格式如下:

identifier.iot.region.amazonaws.com

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

注意

您必须将 iotdevicegateway 用作身份验证的服务名称,才能使用 API。有关更多信息,请参阅 IoT DataPlane

您还可以通过提供 name=shadowName 用 API 创建命名影子,作为 API 的查询参数的一部分。

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 凭证的 Signature Version 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 凭证的 Signature Version 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

请注意,删除影子不会将其版本号重置为 0。

授权

要删除设备的影子,需要一项允许调用方执行 iot:DeleteThingShadow 操作的策略。Device Shadow 服务接受两种形式的身份验证:使用 IAM 凭证的 Signature Version 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 标头以及以下响应代码和 影子名称列表响应文档

注意

未命名的(经典)影子不会显示在该列表中。如果只有经典影子或 thingName 您指定的影子不存在,响应为空列表。

HTTP 200 Response body: Shadow name list document
授权

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

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

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