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

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。有关更多信息，请参阅 IotDataPlane。

您还可以通过提供 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"
      ]
    }
  ]
}