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)

响应

在成功后，响应将包括标准 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"
      ]
    }
  ]
}