Device Shadow REST API - AWS IoT Core
GetThingShadowUpdateThingShadowDeleteThingShadowListNamedShadowsForThing

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

Device Shadow REST API

阴影会显示以下内容URI以更新状态信息：

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

终端节点特定于您的 AWS 账户。要查找端点，您可以：

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

  • 使用 AWS IoT 控制台设置。在 Settings（设置），端点将列在 Custom endpoint（自定义端点）下。

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

    1. 打开 Manage（管理），并在 Manage（管理）中，选择 Things（事物）。

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

    3. 选择 Device Shadows 选项卡，然后选择影子。您可以URI在 Device Shadow 详情页面的 D evice Shadow URL 部分查看终端节点。

终端节点的格式如下：

identifier.iot.region.amazonaws.com

影子RESTAPI遵循与中所述相同的HTTPS协议/端口映射。设备通信协议

注意

要使用APIs，必须使用iotdevicegateway作为身份验证的服务名称。有关更多信息，请参阅 I Pl oTData ane。

您也可以使用创建命名的阴影，方法是提供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凭据的签名版本 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

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

授权

要删除设备的影子，需要一项允许调用方执行 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标头以及以下响应代码和 a影子名称列表响应文档.

注意

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

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"
      ]
    }
  ]
}