Device Shadow MQTT 主题 - Amazon IoT Core
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

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

Device Shadow MQTT 主题

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

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

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

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

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

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

/get

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

ShadowTopicPrefix/get

Amazon 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

Amazon 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

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

Amazon 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

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

ShadowTopicPrefix/update/delta

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

消息正文详细信息

  • 发布到 update/delta 的消息仅包括 desired 部分和 reported 部分之间有所不同的预期属性。无论这些属性包含在当前更新消息中还是已存储在 Amazon 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

Amazon 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

Amazon 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

Amazon 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/delete

消息内容将被忽略。

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

Amazon 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

Amazon 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

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