在裝置中使用影子

本節說明使用 MQTT 訊息進行陰影的裝置通訊，MQTT 訊息是裝置與 Dev AWS IoT ice Shadow 服務通訊的偏好方法。

影子通訊功能會模擬使用 MQTT 的發佈/訂閱通訊模型的請求/回應模型。每個影子動作包括一個請求主題，一個成功的回應主題 (accepted) 和一個錯誤響應主題 (rejected)。

如果您希望應用程式和服務能夠判斷裝置是否已連線，請參閱 偵測裝置已連線。

重要

因 MQTT 會使用發佈/訂閱通訊模型，因此您應先訂閱回應主題，再發佈請求主題。若您並未這麼做，則將不會收到發佈請求的回應。

若您使用 AWS IoT Device SDK 呼叫 Device Shadow 服務 API，則會為您處理。

本節中的範例使用主題的縮寫形式，其中ShadowTopicPrefix可參考具名或未命名的陰影，如本表所述。

影子可以為已命名或未命名 (典型)。各影子所使用的主題只有在主題字首中有所不同。此表格會顯示每種影子類型所使用的主題字首。

ShadowTopicPrefix 值	影子類型
$aws/things/thingName/shadow	未命名 (經典) 影子
$aws/things/thingName/shadow/name/shadowName	已命名影子

重要

確保您的應用程式或服務對影子的使用符合一致性，並且受您裝置中對應的實作支援。例如，請考慮如何建立、更新和刪除影子。也請考慮如何在裝置中處理更新，以及透過影子存取裝置的應用程式或服務。您的設計應該清楚了解裝置狀態如何更新和報告，以及您的應用程式和服務如何與裝置及其影子互動。

若要建立完整的主題，請在 ShadowTopicPrefix 選取您要參照的影子類型、用對應值取代 thingName 及 shadowName (如適用) 的影子類型，然後將該類型附加至主題 stub，如下表所示。請記住，主題會區分大小寫。

如需有關影子保留主題的詳細資訊，請參閱 影子主題。

在第一次連接時初始化設備 AWS IoT

在設備註冊後 AWS IoT，它應該訂閱這些 MQTT 消息以獲取其支持的陰影。

主題	意義	收到此主題時裝置應採取的動作
ShadowTopicPrefix/delete/accepted	請delete求被接受並 AWS IoT 刪除了陰影。	適應已刪除影子所需的動作，例如停止發佈更新。
ShadowTopicPrefix/delete/rejected	請delete求已被拒絕，而 AWS IoT 且陰影未刪除。訊息內文包含錯誤資訊。	在訊息內文中回應錯誤訊息。
ShadowTopicPrefix/get/accepted	要get求已被接受 AWS IoT，且郵件內文包含目前的陰影文件。	處理訊息內文中的狀態文件所需的動作。
ShadowTopicPrefix/get/rejected	要get求已被拒絕 AWS IoT，且郵件內文包含錯誤資訊。	在訊息內文中回應錯誤訊息。
ShadowTopicPrefix/update/accepted	要update求已被接受 AWS IoT，且郵件內文包含目前的陰影文件。	確認訊息內文中的更新資料符合裝置狀態。
ShadowTopicPrefix/update/rejected	要update求已被拒絕 AWS IoT，且郵件內文包含錯誤資訊。	在訊息內文中回應錯誤訊息。
ShadowTopicPrefix/update/delta	陰影文件已由要求更新 AWS IoT，且郵件內文包含要求的變更。	更新裝置的狀態，以符合訊息內文中所需的狀態。
ShadowTopicPrefix/update/documents	最近已完成影子的更新，而訊息內文包含目前的影子文件。	確認訊息內文中的更新狀態符合裝置的狀態。

訂閱上表中每個影子的訊息之後，裝置應該測試，看看它支援的影子是否已經透過將 /get 主題發佈到每個影子來建立。如果收到 /get/accepted 訊息，訊息內文會包含影子文件，裝置可用來初始化其狀態。如果收到 /get/rejected 訊息，應該透過發佈具有目前裝置狀態的 /update 訊息來建立影子。

例如，假設您有一個沒有任何經典或已命名影子的物件 My_IoT_Thing。如果您現在於保留主題 $aws/things/My_IoT_Thing/shadow/get 上發佈 /get 請求，則會在 $aws/things/My_IoT_Thing/shadow/get/rejected 主題上傳回錯誤，因為物件沒有任何影子。若要解決此錯誤，請先使用 $aws/things/My_IoT_Thing/shadow/update 主題發佈 /update 訊息與目前裝置狀態 (如以下承載)。

{
	"state": {
		"reported": {
			"welcome": "aws-iot",
			"color": "yellow"
		}
	}
}

現在會為物件建立一個經典影子，並將訊息發佈至 $aws/things/My_IoT_Thing/shadow/update/accepted 主題。如果發佈至主題 $aws/things/My_IoT_Thing/shadow/get，則會將回應與裝置狀態傳回給 $aws/things/My_IoT_Thing/shadow/get/accepted 主題。

對於已命名的影子，在使用 get 請求之前，必須先建立已命名的影子或發佈含有影子名稱的更新。例如，若要建立已命名的影子 namedShadow1，請先將裝置狀態資訊發佈至主題 $aws/things/My_IoT_Thing/shadow/name/namedShadow1/update。若要擷取狀態資訊，請對已命名的影子 $aws/things/My_IoT_Thing/shadow/name/namedShadow1/get 使用 /get 請求。

在設備連接到時處理消息 AWS IoT

當設備連接到時 AWS IoT，它可以接收 /update /delta 消息，並應通過以下方式使設備狀態與其陰影中的更改保持匹配：

1. 讀取接收到的所有 /update/delta 訊息，並同步處理裝置狀態以進行比對。

2. 只要裝置狀態發生變化時，便使用具有裝置目前狀態的 reported 訊息內文發佈 /update 訊息。

當裝置連線時，它應該在指示時發佈這些訊息。

指示	主題	承載
裝置的狀態已變更。	ShadowTopicPrefix/update	具有 reported 屬性的影子文件。
裝置可能不會與影子同步。	ShadowTopicPrefix/get	(空白)
裝置上的動作表示裝置將不再支援影子，例如移除或取代裝置時。	ShadowTopicPrefix/delete	(空白)

裝置重新連線時處理訊息 AWS IoT

當具有一個或多個陰影的設備連接到時 AWS IoT，它應該通過以下方式將其狀態與其支持的所有陰影的狀態同步：

1. 讀取接收到的所有 /update/delta 訊息，並同步處理裝置狀態以進行比對。

2. 使用具有裝置目前狀態的 reported 訊息內文發佈 /update 訊息。