AWS IoT
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 Amazon AWS 入门

影子 MQTT 主题

Device Shadow 服务使用预留的 MQTT 主题,使应用程序和设备获取、更新或删除设备 (影子) 的状态信息。这些主题的名称以 $aws/things/thingName/shadow 开头。要订阅影子主题并向该主题发布消息,需要获得基于主题的授权。AWS IoT 保留向现有主题结构添加新主题的权利。为此,建议您订阅影子主题时勿使用通配符。例如,请勿在订阅时使用诸如 $aws/things/thingName/shadow/# 的主题筛选条件,因为与该主题筛选条件匹配的主题数量可能会随着 AWS IoT 引入新的影子主题而增加。要了解针对这些主题发布的消息示例,请查看 Device Shadow 服务数据流

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

/更新

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

$aws/things/thingName/shadow/update

尝试更新事物状态的客户端会发送类似如下的 JSON 请求状态文档:

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

更新其影子的设备会发送类似于下面的 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/accepted

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

$aws/things/thingName/shadow/update/accepted

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

示例策略

以下是所需策略的示例:

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

/update/documents

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

$aws/things/thingName/shadow/update/documents

JSON 文档包含两个主要节点:previouscurrentprevious 节点包含执行更新之前完整影子文档的内容,而 current 节点则包含成功更新之后完整影子文档的内容。首次更新 (创建) 影子时,previous 节点将包含 null

示例策略

以下是所需策略的示例:

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

/update/rejected

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

$aws/things/thingName/shadow/update/rejected

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

示例策略

以下是所需策略的示例:

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

/update/delta

AWS IoT 在接受设备影子的更改时向此主题发布响应状态文档,且请求状态文档包含不同的 desired 状态值和 reported 状态值:

$aws/things/thingName/shadow/update/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", "iot:Receive" ], "Resource": ["arn:aws:iot:region:account:topicfilter/$aws/things/thingName/shadow/update/delta"] }] }

/get

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

$aws/things/thingName/shadow/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 在返回设备的影子时向此主题发布响应状态文档:

$aws/things/thingName/shadow/get/accepted

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

示例策略

以下是所需策略的示例:

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

/get/rejected

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

$aws/things/thingName/shadow/get/rejected

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

示例策略

以下是所需策略的示例:

{ "Version": "2012-10-17", "Statement": [{ "Action": [ "iot:Subscribe", "iot:Receive" ], "Resource": ["arn:aws:iot:region:account:topicfilter/$aws/things/thingName/shadow/get/rejected"] }] }

/delete

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

$aws/things/thingName/shadow/delete

消息内容将被忽略。

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

示例策略

以下是所需策略的示例:

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

/delete/accepted

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

$aws/things/thingName/shadow/delete/accepted

示例策略

以下是所需策略的示例:

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

/delete/rejected

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

$aws/things/thingName/shadow/delete/rejected

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

示例策略

以下是所需策略的示例:

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