本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
Device Shadow MQTT 主题
Device Shadow 服务使用保留的 MQTT 主题,以使设备和应用程序能够获取、更新或删除设备的状态信息(影子)。
要订阅影子主题并向该主题发布消息,需要获得基于主题的授权。Amazon IoT 保留向现有主题结构添加新主题的权利。为此,建议您订阅影子主题时勿使用通配符。例如,请勿在订阅时使用诸如 $aws/things/thingName/shadow/#
的主题筛选条件,因为与该主题筛选条件匹配的主题数量可能会随着 Amazon IoT 引入新的影子主题而增加。要了解针对这些主题发布的消息示例,请查看 与影子交互。
影子可以是命名或未命名(经典)的。每个影子使用的主题仅在主题前缀上有所不同。下表显示每种影子类型使用的主题前缀。
ShadowTopicPrefix 值 |
影子类型 |
---|---|
$aws/things/ |
未命名的(经典)影子 |
$aws/things/ |
命名的影子 |
要创建完整的主题,请为要表示的影子类型选择
,将 ShadowTopicPrefix
和 thingName
(如果适用)替换为相应的值,然后在其后面附加主题存根,如以下几部分中所示。shadowName
以下是用于与影子交互的 MQTT 主题。
主题
/get
要获得设备的影子,请在此主题下发布一条空消息:
ShadowTopicPrefix
/get
Amazon IoT 通过向 /get/accepted 或 /get/rejected 发布消息来进行响应。
示例 policy
以下是所需策略的示例:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Publish" ], "Resource": [ "arn:aws:iot:
region
:account
:topic/$aws/things/thingName
/shadow/get" ] } ] }
/get/accepted
在返回设备的影子时,Amazon IoT 将响应影子文档发布到该主题:
ShadowTopicPrefix
/get/accepted
有关更多信息,请参阅响应状态文档。
示例 policy
以下是所需策略的示例:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:
region
:account
:topicfilter/$aws/things/thingName
/shadow/get/accepted" ] }, { "Effect": "Allow", "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:region
:account
:topic/$aws/things/thingName
/shadow/get/accepted" ] } ] }
/get/rejected
Amazon IoT 在无法返回设备的影子时向此主题发布错误响应文档:
ShadowTopicPrefix
/get/rejected
有关更多信息,请参阅错误响应文档。
示例 policy
以下是所需策略的示例:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:
region
:account
:topicfilter/$aws/things/thingName
/shadow/get/rejected" ] }, { "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:region
:account
:topic/$aws/things/thingName
/shadow/get/rejected" ] } ] }
/update
向此主题发布请求状态文档来更新设备的影子:
ShadowTopicPrefix
/update
消息正文包含部分请求状态文档。
尝试更新设备状态的客户端将发送具有 desired
属性的 JSON 请求状态文档,例如:
{ "state": { "desired": { "color": "red", "power": "on" } } }
更新其影子的设备将发送具有 reported
属性的 JSON 请求状态文档,例如:
{ "state": { "reported": { "color": "red", "power": "on" } } }
Amazon IoT 通过向 /update/accepted 或 /update/rejected 发布消息来进行响应。
示例 policy
以下是所需策略的示例:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Publish" ], "Resource": [ "arn:aws:iot:
region
:account
:topic/$aws/things/thingName
/shadow/update" ] } ] }
/update/delta
在接受设备的影子更改时,Amazon IoT 将响应状态文档发布到该主题,并且请求状态文档包含不同的 desired
和 reported
状态值:
ShadowTopicPrefix
/update/delta
消息缓冲区包含一个 /delta 响应状态文档。
消息正文详细信息
-
发布到
update/delta
的消息仅包括desired
部分和reported
部分之间有所不同的预期属性。无论这些属性包含在当前更新消息中还是已存储在 Amazon IoT 中,它将包含所有此类属性。desired
部分和reported
部分之间相同的属性则不包含在内。 -
如果某个属性位于
reported
部分,但在desired
部分没有等效值,则不会包含在内。 -
如果某个属性位于
desired
部分,但在reported
部分没有等效值,则将包含在内。 -
如果某个属性已从
reported
部分删除,但仍存在于desired
部分,则将包含在内。
示例 policy
以下是所需策略的示例:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:
region
:account
:topicfilter/$aws/things/thingName
/shadow/update/delta" ] }, { "Effect": "Allow", "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:region
:account
:topic/$aws/things/thingName
/shadow/update/delta" ] } ] }
/update/accepted
Amazon IoT 在接受设备影子的更改时向此主题发布响应状态文档:
ShadowTopicPrefix
/update/accepted
消息缓冲区包含一个 /accepted 响应状态文档。
示例 policy
以下是所需策略的示例:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:
region
:account
:topicfilter/$aws/things/thingName
/shadow/update/accepted" ] }, { "Effect": "Allow", "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:region
:account
:topic/$aws/things/thingName
/shadow/update/accepted" ] } ] }
/update/documents
每次影子更新成功执行时,Amazon IoT 都会向该主题发布状态文档:
ShadowTopicPrefix
/update/documents
消息正文包含一个 /documents 响应状态文档。
示例 policy
以下是所需策略的示例:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:
region
:account
:topicfilter/$aws/things/thingName
/shadow/update/documents" ] }, { "Effect": "Allow", "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:region
:account
:topic/$aws/things/thingName
/shadow/update/documents" ] } ] }
/update/rejected
Amazon IoT 在拒绝设备影子的更改时向此主题发布错误响应文档:
ShadowTopicPrefix
/update/rejected
消息正文包含一个错误响应文档。
示例 policy
以下是所需策略的示例:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:
region
:account
:topicfilter/$aws/things/thingName
/shadow/update/rejected" ] }, { "Effect": "Allow", "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:region
:account
:topic/$aws/things/thingName
/shadow/update/rejected" ] } ] }
/delete
要删除设备的影子,请将一条空消息发布到删除主题:
ShadowTopicPrefix
/delete
消息内容将被忽略。
请注意,删除影子不会将其版本号重置为 0。
Amazon IoT 通过向 /delete/accepted 或 /delete/rejected 发布消息来进行响应。
示例 policy
以下是所需策略的示例:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Publish" ], "Resource": [ "arn:aws:iot:
region
:account
:topic/$aws/things/thingName
/shadow/delete" ] } ] }
/delete/accepted
Amazon IoT 在删除设备的影子时向此主题发布消息:
ShadowTopicPrefix
/delete/accepted
示例 policy
以下是所需策略的示例:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:
region
:account
:topicfilter/$aws/things/thingName
/shadow/delete/accepted" ] }, { "Effect": "Allow", "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:region
:account
:topic/$aws/things/thingName
/shadow/delete/accepted" ] } ] }
/delete/rejected
Amazon IoT 在无法删除设备的影子时向此主题发布错误响应文档:
ShadowTopicPrefix
/delete/rejected
消息正文包含一个错误响应文档。
示例 policy
以下是所需策略的示例:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:
region
:account
:topicfilter/$aws/things/thingName
/shadow/delete/rejected" ] }, { "Effect": "Allow", "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:region
:account
:topic/$aws/things/thingName
/shadow/delete/rejected" ] } ] }