Device Shadow MQTT 主题 - AWS IoT Core

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

Device Shadow MQTT 主题

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

要订阅影子主题并向该主题发布消息,需要获得基于主题的授权。AWS IoT 保留向现有主题结构添加新主题的权利。为此,建议您订阅影子主题时勿使用通配符。例如,请勿在订阅时使用诸如 $aws/things/thingName/shadow/# 的主题筛选条件,因为与该主题筛选条件匹配的主题数量可能会随着 AWS IoT 引入新的影子主题而增加。要了解针对这些主题发布的消息示例,请查看 与影子交互

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

ShadowTopicPrefix 影子类型
$aws/things/thingName/shadow 未命名的(经典)影子
$aws/things/thingName/shadow/name/shadowName 命名的影子

要创建完整的主题,请为要表示的影子类型选择 ShadowTopicPrefix,将 thingNameshadowName(如果适用)替换为相应的值,然后在其后面附加主题存根,如以下几节中所示。

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

/get

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

ShadowTopicPrefix/get

AWS IoT 通过向 /get/accepted/get/rejected 发布消息来进行响应。

示例策略

以下是所需策略的示例:

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

/get/accepted

在返回设备的影子时,AWS IoT 将响应影子文档发布到该主题:

ShadowTopicPrefix/get/accepted

有关更多信息,请参阅响应状态文档

示例策略

以下是所需策略的示例:

{ "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

AWS IoT 在无法返回设备的影子时向此主题发布错误响应文档:

ShadowTopicPrefix/get/rejected

有关更多信息,请参阅错误响应文档

示例策略

以下是所需策略的示例:

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

AWS IoT 通过向 /update/accepted/update/rejected 发布消息来进行响应。

示例策略

以下是所需策略的示例:

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

/update/delta

在接受设备的影子更改时,AWS IoT 将响应状态文档发布到该主题,并且请求状态文档包含不同的 desiredreported 状态值:

ShadowTopicPrefix/update/delta

消息缓冲区包含一个 /delta 响应状态文档

消息正文详细信息

  • 发布到 update/delta 的消息仅包括 desired 部分和 reported 部分之间有所不同的预期属性。无论这些属性包含在当前更新消息中还是已存储在 AWS IoT 中,它将包含所有此类属性。desired 部分和 reported 部分之间相同的属性则不包含在内。

  • 如果某个属性位于 reported 部分,但在 desired 部分没有等效值,则不会包含在内。

  • 如果某个属性位于 desired 部分,但在 reported 部分没有等效值,则将包含在内。

  • 如果某个属性已从 reported 部分删除,但仍存在于 desired 部分,则将包含在内。

示例策略

以下是所需策略的示例:

{ "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

AWS IoT 在接受设备影子的更改时向此主题发布响应状态文档:

ShadowTopicPrefix/update/accepted

消息缓冲区包含一个 /accepted 响应状态文档

示例策略

以下是所需策略的示例:

{ "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

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

ShadowTopicPrefix/update/documents

消息正文包含一个 /documents 响应状态文档

示例策略

以下是所需策略的示例:

{ "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

AWS IoT 在拒绝设备影子的更改时向此主题发布错误响应文档:

ShadowTopicPrefix/update/rejected

消息正文包含一个错误响应文档

示例策略

以下是所需策略的示例:

{ "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/shadow/delete

消息内容将被忽略。

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

AWS IoT 通过向 /delete/accepted/delete/rejected 发布消息来进行响应。

示例策略

以下是所需策略的示例:

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

/delete/accepted

AWS IoT 在删除设备的影子时向此主题发布消息:

ShadowTopicPrefix/delete/accepted

示例策略

以下是所需策略的示例:

{ "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

AWS IoT 在无法删除设备的影子时向此主题发布错误响应文档:

ShadowTopicPrefix/delete/rejected

消息正文包含一个错误响应文档

示例策略

以下是所需策略的示例:

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