裝置影子MQTT主題 - AWS IoT Core

本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。

裝置影子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 (如適用) 的影子類型,然後將該類型附加至主題 stub,如下節所示。

以下是用於與陰影互動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 response state document

訊息內文詳細資料

  • 發佈於 update/delta 的訊息,僅包括 desiredreported 部分之間不同的所需屬性。這些屬性全都會包含在其中,無論這些屬性是否原本就包含於目前的更新訊息中或是已經存放於 AWS IoT。在 desiredreported 部分之間沒有差異的屬性則不會包含在內。

  • 如果某個屬性出現在 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 response state document

範例 政策

以下為所需政策的範例:

{ "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 response state document

範例 政策

以下為所需政策的範例:

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