本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
Device Shadow 服務文件
Device Shadow 服務尊重JSON規格的所有規則。值、物件與陣列均存放於裝置的影子文件中。
影子文件範例
Device Shadow 服務會在 UPDATE、 和 DELETE 操作中使用這些文件GET，並使用 RESTAPI或 MQTT Pub/Sub Messages 。
請求狀態文件
請求狀態文件具有以下格式：
{ "state": { "desired": { "attribute1":integer2, "attribute2": "string2", ... "attributeN":boolean2}, "reported": { "attribute1":integer1, "attribute2": "string1", ... "attributeN":boolean1} }, "clientToken": "token", "version":version}
-
state：更新僅會影響所指定的欄位。一般而言，您會使用desired或reported屬性，但不會在同一個要求中使用兩者。-
desired：請求在裝置中更新的狀態屬性和值。 -
reported：裝置回報的狀態屬性和值。
-
-
clientToken：如已使用，您可透過用戶端字符來比對請求和相應的回應。 -
version：若使用此項目，Device Shadow 服務只有在指定版本與其擁有的最新版本相符時，才會處理更新。
回應狀態文件
根據回應類型，回應狀態文件的格式如下。
/accepted response state document
{ "state": { "desired": { "attribute1":integer2, "attribute2": "string2", ... "attributeN":boolean2} }, "metadata": { "desired": { "attribute1": { "timestamp":timestamp}, "attribute2": { "timestamp":timestamp}, ... "attributeN": { "timestamp":timestamp} } }, "timestamp":timestamp, "clientToken": "token", "version":version}
/delta response state document
{ "state": { "attribute1":integer2, "attribute2": "string2", ... "attributeN":boolean2}, "metadata": { "attribute1": { "timestamp":timestamp}, "attribute2": { "timestamp":timestamp}, ... "attributeN": { "timestamp":timestamp} }, "timestamp":timestamp, "clientToken": "token", "version":version}
/documents response state document
{ "previous" : { "state": { "desired": { "attribute1":integer2, "attribute2": "string2", ... "attributeN":boolean2}, "reported": { "attribute1":integer1, "attribute2": "string1", ... "attributeN":boolean1} }, "metadata": { "desired": { "attribute1": { "timestamp":timestamp}, "attribute2": { "timestamp":timestamp}, ... "attributeN": { "timestamp":timestamp} }, "reported": { "attribute1": { "timestamp":timestamp}, "attribute2": { "timestamp":timestamp}, ... "attributeN": { "timestamp":timestamp} } }, "version":version-1 }, "current": { "state": { "desired": { "attribute1":integer2, "attribute2": "string2", ... "attributeN":boolean2}, "reported": { "attribute1":integer2, "attribute2": "string2", ... "attributeN":boolean2} }, "metadata": { "desired": { "attribute1": { "timestamp":timestamp}, "attribute2": { "timestamp":timestamp}, ... "attributeN": { "timestamp":timestamp} }, "reported": { "attribute1": { "timestamp":timestamp}, "attribute2": { "timestamp":timestamp}, ... "attributeN": { "timestamp":timestamp} } }, "version":version}, "timestamp":timestamp, "clientToken": "token" }
回應狀態文件屬性
-
previous：成功更新之後，會在更新前包含物件的state。 -
current：成功更新之後，會在更新後包含物件的state。 -
state-
reported：僅當物件於reported區段回報任何資料，且包含僅位於請求狀態文件中的欄位時才出現。 -
desired：僅當裝置於desired區段回報任何資料，且包含僅位於請求狀態文件中的欄位時才出現。 -
delta：僅當desired資料與影子目前reported資料不同時才會存在。
-
-
metadata：包含desired和reported部分中每個屬性的時間戳記，因此您可確定狀態的更新時間。 -
timestamp— 由 產生回應的 Epoch 日期和時間 AWS IoT。 -
clientToken— 只有在發佈JSON有效/update主題時使用了用戶端權杖時才會顯示。 -
version： AWS IoT中目前共用之裝置影子的文件版本。此版本會在先前的文件版本編號加一。
錯誤回應文件
錯誤回應文件的格式如下：
{ "code":error-code, "message": "error-message", "timestamp":timestamp, "clientToken": "token" }
-
code— 指出錯誤類型的HTTP回應代碼。 -
message：可提供額外資訊的文字訊息。 -
timestamp— 由 產生回應的日期和時間 AWS IoT。此屬性不會出現在所有錯誤回應文件中。 -
clientToken：僅於已發佈的訊息中使用用戶端字符時才會出現。
如需詳細資訊，請參閱Device Shadow 錯誤訊息。
影子名稱清單回應文件
影子名稱清單回應文件的格式如下：
{ "results": [ "shadowName-1", "shadowName-2", "shadowName-3", "shadowName-n" ], "nextToken": "nextToken", "timestamp":timestamp}
-
results：影子名稱的陣列。 -
nextToken：在分頁請求中使用的字符值，以取得序列中的下一頁。當沒有更多的影子名稱返回時，這個屬性不存在。 -
timestamp— 由 產生回應的日期和時間 AWS IoT。
文件屬性
裝置的影子文件具有下列屬性：
state-
desired-
裝置所需的狀態。應用程式可將此部分編寫入文件，在無需直接連線的狀況下更新裝置狀態。
reported-
裝置回報的狀態。裝置會在文件中編寫此部分以回報其新狀態。應用程式會讀取文件的這部分，以判斷裝置上次報告的狀態。
metadata-
存放於文件
state部分之資料的相關資訊。其中包括針對state部分中各屬性的時間戳記 (Epoch 時間)，可讓您確定資料是在何時更新的。注意
中繼資料不會影響服務限制或定價的文件大小。如需詳細資訊，請參閱 AWS IoT 服務限制。
timestamp-
指示 訊息由 傳送的時間 AWS IoT。藉由使用訊息中的時間戳記和
desired或reported區段中的個別屬性的時間戳記，裝置可以判斷屬性的保留天數，即使裝置沒有內部時鐘也是如此。 clientToken-
裝置的唯一字串，可讓您將回應與MQTT環境中的請求建立關聯。
version-
文件版本。每次文件更新時，版本編號便會自動增加。如此可確保更新的文件為最新版本。
如需詳細資訊，請參閱影子文件範例。
差量狀態
差量 (delta) 狀態是一種虛擬類型的狀態，包含了 desired 和 reported 之間的差異。在 desired 部分的欄位若未出現於 reported 部分，則會納入差量之中。在 reported 部分的欄位若未出現於 desired 部分，則不會納入差量之中。差量包含中繼資料，且其值與 desired 欄位裡的中繼資料相同。例如：
{ "state": { "desired": { "color": "RED", "state": "STOP" }, "reported": { "color": "GREEN", "engine": "ON" }, "delta": { "color": "RED", "state": "STOP" } }, "metadata": { "desired": { "color": { "timestamp": 12345 }, "state": { "timestamp": 12345 } }, "reported": { "color": { "timestamp": 12345 }, "engine": { "timestamp": 12345 } }, "delta": { "color": { "timestamp": 12345 }, "state": { "timestamp": 12345 } } }, "version": 17, "timestamp": 123456789 } }
當巢狀物件不同，差量則會包含根路徑。
{ "state": { "desired": { "lights": { "color": { "r": 255, "g": 255, "b": 255 } } }, "reported": { "lights": { "color": { "r": 255, "g": 0, "b": 255 } } }, "delta": { "lights": { "color": { "g": 255 } } } }, "version": 18, "timestamp": 123456789 }
Device Shadow 服務會重複查看 desired 狀態內的所有欄位，然後將其與 reported 狀態相比較，藉此計算出差量。
陣列的處理和值相同。如果 desired 部分的某個陣列與 reported 部分的陣列不符，則整組所需陣列都會複製到差量中。
版本控制影子文件
Device Shadow 服務支援每個更新訊息的版本控制，包括請求和回應。這表示每次更新影子時，JSON文件的版本都會遞增。如此可確保兩種情況：
-
如果用戶端嘗試以較舊的版本編號覆寫影子，就會收到錯誤訊息。通知用戶端必須先重新同步裝置的影子，才可進行更新。
-
如果此訊息的版本低於存放於用戶端的訊息版本，則用戶端可以決定不採取行動。
用戶端可以透過不在影子文件中包含版本來略過版本比對。
影子文件中的用戶端字符
您可以搭配 MQTT型訊息使用用戶端權杖，以確認請求和請求回應中包含相同的用戶端權杖。如此可確保回應與請求之間具有關聯。
注意
用戶端字符不能超過 64 位元組。超過 64 個位元組的用戶端權杖會導致 400 （錯誤請求） 回應和無效的clientToken錯誤訊息。
空白影子文件屬性
當影子文件中的 reported 和 desired 屬性不適用於目前影子狀態時，它們可以是空的，您也可以省略它們。例如，影子文件只有在具有所需狀態時才會包含 desired 屬性。以下是沒有 desired 屬性的狀態文件的有效範例：
{ "reported" : { "temp": 55 } }
該 reported 屬性也可以是空白，例如，如果影子尚未由裝置更新：
{ "desired" : { "color" : "RED" } }
如果更新導致 desired 或 reported 屬性變為 null，則會從文件中移除。下面顯示了如何透過將屬性設定為 null 來刪除 desired。例如，當裝置更新其狀態時，您可能會這麼做。
{ "state": { "reported": { "color": "red" }, "desired": null } }
影子文件也可以具有 desired 或 reported 屬性，使影子文件變成空白。這是一個空白但有效的影子文件範例。
{ }
影子文件中的陣列值
影子支援陣列，但會將其視為一般值，即更新某陣列會取代整組陣列。您無法只更新陣列中的某部分。
初始狀態：
{ "desired" : { "colors" : ["RED", "GREEN", "BLUE" ] } }
更新：
{ "desired" : { "colors" : ["RED"] } }
最終狀態：
{ "desired" : { "colors" : ["RED"] } }
陣列不能有 Null 值。例如，以下陣列無效並且會被拒絕。
{ "desired" : { "colors" : [ null, "RED", "GREEN" ] } }
