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

# Device Shadow REST API
<a name="device-shadow-rest-api"></a>

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

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

终端节点特定于您 AWS 账户。要查找端点，您可以：
+ 从 AWS CLI使用 [describe-endpoint](https://docs.aws.amazon.com/cli/latest/reference/iot/describe-endpoint.html) 命令。
+ 使用 AWS IoT 控制台设置。在 **Settings**（设置），端点将列在 **Custom endpoint**（自定义端点）下。
+ 使用 AWS IoT 控制台事物详细信息页面。在控制台中，执行以下操作：

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

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

  1. 选择 **Device Shadows** 选项卡，然后选择影子。您可以在 **Device Shadow details**（Device Shadow 详细信息）页面的 **Device Shadow URL** 部分查看端点 URI。

端点的格式如下：

```
identifier.iot.region.amazonaws.com
```

影子 REST API 遵循与中所[设备通信协议](protocols.md)述相同的 HTTPS protocols/port 映射。

**注意**  
要使用 APIs，必须使用`iotdevicegateway`作为身份验证的服务名称。有关更多信息，请参阅 [Io TData 飞机](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-iot-data-plane/classes/iotdataplane.html)。

**Topics**
+ [GetThingShadow](#API_GetThingShadow)
+ [UpdateThingShadow](#API_UpdateThingShadow)
+ [DeleteThingShadow](#API_DeleteThingShadow)
+ [ListNamedShadowsForThing](#API_ListNamedShadowsForThing)

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

## GetThingShadow
<a name="API_GetThingShadow"></a>

获取指定事物的影子。

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

有关更多信息，请参阅[响应状态文档示例](device-shadow-document.md#device-shadow-example-response-json)。

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

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

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "iot:GetThingShadow",
            "Resource": [
                "arn:aws:iot:us-east-1:123456789012:thing/thing"
            ]
        }
    ]
}
```

## UpdateThingShadow
<a name="API_UpdateThingShadow"></a>

更新指定事物的影子。

更新仅影响请求状态文档中指定的字段。值为 `null` 的所有字段都会从设备的影子中删除。

**请求**  
该请求包括标准的 HTTP 标头以及以下 URI 和正文：

```
HTTP POST https://endpoint/things/thingName/shadow?name=shadowName
Request body: request state document
```

未命名的（经典）影子不需要使用 `name` 查询参数。

有关更多信息，请参阅[请求状态文档示例](device-shadow-document.md#device-shadow-example-request-json)。

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

```
HTTP 200
Response body: response state document
```

有关更多信息，请参阅[响应状态文档示例](device-shadow-document.md#device-shadow-example-response-json)。

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

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

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "iot:UpdateThingShadow",
            "Resource": [
                "arn:aws:iot:us-east-1:123456789012:thing/thing"
            ]
        }
    ]
}
```

## DeleteThingShadow
<a name="API_DeleteThingShadow"></a>

删除指定事物的影子。

**请求**  
该请求包括标准的 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。

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

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

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "iot:DeleteThingShadow",
            "Resource": [
                "arn:aws:iot:us-east-1:123456789012:thing/thing"
            ]
        }
    ]
}
```

## ListNamedShadowsForThing
<a name="API_ListNamedShadowsForThing"></a>

列出指定事物的影子。

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

```
HTTP GET /api/things/shadow/ListNamedShadowsForThing/thingName?nextToken=nextToken&pageSize=pageSize
Request body: (none)
```

nextToken  
用于检索下一组结果的令牌。  
该值在分页结果中返回，并在返回下一页的调用中使用。

pageSize  
在每个调用中返回的影子名称的数量。另请参阅`nextToken`。

thingName  
要列出命名的影子的事物的名称。

**响应**  
在成功后，响应将包括标准 HTTP 标头以及以下响应代码和 [影子名称列表响应文档](device-shadow-document.md#device-shadow-list-json)。

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

```
HTTP 200
Response body: Shadow name list document
```

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

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

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "iot:ListNamedShadowsForThing",
            "Resource": [
                "arn:aws:iot:us-east-1:123456789012:thing/thing"
            ]
        }
    ]
}
```