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

# Device Shadow MQTT 主题
<a name="device-shadow-mqtt"></a>

Device Shadow 服务使用保留的 MQTT 主题，以使设备和应用程序能够获取、更新或删除设备的状态信息（影子）。

要订阅影子主题并向该主题发布消息，需要获得基于主题的授权。 AWS IoT 保留向现有主题结构添加新主题的权利。为此，建议您订阅影子主题时勿使用通配符。例如，避免订阅主题过滤器，`$aws/things/thingName/shadow/#`因为与该主题过滤器匹配的主题数量可能会随着新的影子主题的 AWS IoT 引入而增加。要了解针对这些主题发布的消息示例，请查看 [与影子交互](device-shadow-data-flow.md)。

影子可以是命名或未命名（经典）的。每个影子使用的主题仅在主题前缀上有所不同。下表显示每种影子类型使用的主题前缀。


| *ShadowTopicPrefix* 值 | 影子类型 | 
| --- | --- | 
| \$1aws/things/thingName/shadow | 未命名的（经典）影子 | 
| \$1aws/things/thingName/shadow/name/shadowName | 命名的影子 | 

要创建完整的主题，请为要表示的影子类型选择 `ShadowTopicPrefix`，将 `thingName` 和 `shadowName`（如果适用）替换为相应的值，然后在其后面附加主题存根，如以下几部分中所示。

以下是用于与影子交互的 MQTT 主题。

**Topics**
+ [/get](#get-pub-sub-topic)
+ [/get/accepted](#get-accepted-pub-sub-topic)
+ [/get/rejected](#get-rejected-pub-sub-topic)
+ [/update](#update-pub-sub-topic)
+ [/update/delta](#update-delta-pub-sub-topic)
+ [/update/accepted](#update-accepted-pub-sub-topic)
+ [/update/documents](#update-documents-pub-sub-topic)
+ [/update/rejected](#update-rejected-pub-sub-topic)
+ [/delete](#delete-pub-sub-topic)
+ [/delete/accepted](#delete-accepted-pub-sub-topic)
+ [/delete/rejected](#delete-rejected-pub-sub-topic)

## /get
<a name="get-pub-sub-topic"></a>

要获得设备的影子，请在此主题下发布一条空消息：

```
ShadowTopicPrefix/get
```

AWS IoT 通过发布[/get/accepted](#get-accepted-pub-sub-topic)或来响应[/get/rejected](#get-rejected-pub-sub-topic)。

### 策略示例
<a name="get-policy"></a>

以下是所需策略的示例：

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iot:Publish"
            ],
            "Resource": [
                "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/get"
            ]
        }
    ]
}
```

## /get/accepted
<a name="get-accepted-pub-sub-topic"></a>

AWS IoT 返回设备的影子时，会向此主题发布响应影子文档：

```
ShadowTopicPrefix/get/accepted
```

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

### 策略示例
<a name="get-accepted-policy"></a>

以下是所需策略的示例：

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iot:Subscribe"
            ],
            "Resource": [
                "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/get/accepted"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "iot:Receive"
            ],
            "Resource": [
                "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/get/accepted"
            ]
        }
    ]
}
```

## /get/rejected
<a name="get-rejected-pub-sub-topic"></a>

AWS IoT 当无法返回设备的影子时，会针对此主题发布错误响应文档：

```
ShadowTopicPrefix/get/rejected
```

有关更多信息，请参阅 [错误响应文档](device-shadow-document.md#device-shadow-example-error-json)。

### 策略示例
<a name="get-rejected-policy"></a>

以下是所需策略的示例：

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iot:Subscribe"
      ],
      "Resource": [
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/get/rejected"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "iot:Receive"
      ],
      "Resource": [
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/get/rejected"
      ]
    }
  ]
}
```

## /update
<a name="update-pub-sub-topic"></a>

向此主题发布请求状态文档来更新设备的影子：

```
ShadowTopicPrefix/update
```

消息正文包含[部分请求状态文档](device-shadow-document.md#device-shadow-example-request-json)。

尝试更新设备状态的客户端将发送具有 `desired` 属性的 JSON 请求状态文档，例如：

```
{
  "state": {
    "desired": {
      "color": "red",
      "power": "on"
    }
  }
}
```

更新其影子的设备将发送具有 `reported` 属性的 JSON 请求状态文档，例如：

```
{
  "state": {
    "reported": {
      "color": "red",
      "power": "on"
    }
  }
}
```

AWS IoT 通过发布[/update/accepted](#update-accepted-pub-sub-topic)或来响应[/update/rejected](#update-rejected-pub-sub-topic)。

### 策略示例
<a name="update-policy"></a>

以下是所需策略的示例：

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iot:Publish"
            ],
            "Resource": [
                "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/update"
            ]
        }
    ]
}
```

## /update/delta
<a name="update-delta-pub-sub-topic"></a>

AWS IoT 当该主题接受设备影子的更改时，会发布该主题的响应状态文档，并且响应状态文档包含不同的值`desired`和`reported`状态：

```
ShadowTopicPrefix/update/delta
```

消息缓冲区包含一个 [/delta 响应状态文档](device-shadow-document.md#device-shadow-example-response-json-delta)。

### 消息正文详细信息
<a name="update-delta-rules"></a>
+ 发布到 `update/delta` 的消息仅包括 `desired` 部分和 `reported` 部分之间有所不同的预期属性。无论这些属性包含在当前更新消息中还是已存储在 AWS IoT中，它将包含所有此类属性。`desired` 部分和 `reported` 部分之间相同的属性则不包含在内。
+ 如果某个属性位于 `reported` 部分，但在 `desired` 部分没有等效值，则不会包含在内。
+ 如果某个属性位于 `desired` 部分，但在 `reported` 部分没有等效值，则将包含在内。
+ 如果某个属性已从 `reported` 部分删除，但仍存在于 `desired` 部分，则将包含在内。

### 策略示例
<a name="update-delta-policy"></a>

以下是所需策略的示例：

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iot:Subscribe"
            ],
            "Resource": [
                "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/update/delta"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "iot:Receive"
            ],
            "Resource": [
                "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/update/delta"
            ]
        }
    ]
}
```

## /update/accepted
<a name="update-accepted-pub-sub-topic"></a>

AWS IoT 当它接受设备影子的更改时，会发布此主题的响应状态文档：

```
ShadowTopicPrefix/update/accepted
```

消息缓冲区包含一个 [/accepted 响应状态文档](device-shadow-document.md#device-shadow-example-response-json-accepted)。

### 策略示例
<a name="update-accepted-policy"></a>

以下是所需策略的示例：

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iot:Subscribe"
            ],
            "Resource": [
                "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/update/accepted"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "iot:Receive"
            ],
            "Resource": [
                "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/update/accepted"
            ]
        }
    ]
}
```

## /update/documents
<a name="update-documents-pub-sub-topic"></a>

AWS IoT 每当成功执行影子更新时，都会向该主题发布状态文档：

```
ShadowTopicPrefix/update/documents
```

消息正文包含一个 [/documents 响应状态文档](device-shadow-document.md#device-shadow-example-response-json-documents)。

### 策略示例
<a name="update-documents-policy"></a>

以下是所需策略的示例：

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iot:Subscribe"
            ],
            "Resource": [
                "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/update/documents"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "iot:Receive"
            ],
            "Resource": [
                "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/update/documents"
            ]
        }
    ]
}
```

## /update/rejected
<a name="update-rejected-pub-sub-topic"></a>

AWS IoT 当该主题拒绝对设备影子的更改时，会发布针对此主题的错误响应文档：

```
ShadowTopicPrefix/update/rejected
```

消息正文包含一个[错误响应文档](device-shadow-document.md#device-shadow-example-error-json)。

### 策略示例
<a name="update-rejected-policy"></a>

以下是所需策略的示例：

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iot:Subscribe"
            ],
            "Resource": [
                "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/update/rejected"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "iot:Receive"
            ],
            "Resource": [
                "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/update/rejected"
            ]
        }
    ]
}
```

## /delete
<a name="delete-pub-sub-topic"></a>

要删除设备的影子，请将一条空消息发布到删除主题：

```
ShadowTopicPrefix/delete
```

消息内容将被忽略。

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

AWS IoT 通过发布[/delete/accepted](#delete-accepted-pub-sub-topic)或来响应[/delete/rejected](#delete-rejected-pub-sub-topic)。

### 策略示例
<a name="delete-policy"></a>

以下是所需策略的示例：

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iot:Publish"
            ],
            "Resource": [
                "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/delete"
            ]
        }
    ]
}
```

## /delete/accepted
<a name="delete-accepted-pub-sub-topic"></a>

AWS IoT 删除设备的影子后，向此主题发布一条消息：

```
ShadowTopicPrefix/delete/accepted
```

### 策略示例
<a name="delete-accepted-policy"></a>

以下是所需策略的示例：

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iot:Subscribe"
            ],
            "Resource": [
                "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/delete/accepted"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "iot:Receive"
            ],
            "Resource": [
                "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/delete/accepted"
            ]
        }
    ]
}
```

## /delete/rejected
<a name="delete-rejected-pub-sub-topic"></a>

AWS IoT 当无法删除设备的影子时，会针对此主题发布错误响应文档：

```
ShadowTopicPrefix/delete/rejected
```

消息正文包含一个[错误响应文档](device-shadow-document.md#device-shadow-example-error-json)。

### 策略示例
<a name="delete-rejected-policy"></a>

以下是所需策略的示例：

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iot:Subscribe"
            ],
            "Resource": [
                "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/delete/rejected"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "iot:Receive"
            ],
            "Resource": [
                "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/delete/rejected"
            ]
        }
    ]
}
```