裝置影子資料流 - IoT Platform

裝置影子Topic

物聯網平台已為每個裝置預定義了兩個Topic，用於實現裝置影子資料流轉。

/shadow/update/${YourProductKey}/${YourDeviceName}
裝置和應用程式發布訊息到此Topic。物聯網平台收到該Topic的訊息後，將訊息中的狀態更新到裝置影子中。
/shadow/get/${YourProductKey}/${YourDeviceName}
裝置影子更新狀態到該Topic，裝置訂閱此Topic擷取最新訊息。

使用樣本

本文以燈泡裝置為例，說明裝置、裝置影子以及應用程式之間的通訊，主要介紹裝置主動上報狀態、應用程式改變裝置狀態、裝置主動擷取影子內容，和裝置主動刪除影子屬性。

樣本中，產品的ProductKey是a1PbRCF****；裝置名稱DeviceName是lightbulb。裝置以QoS=1發布訊息和訂閱兩個裝置影子Topic。

裝置主動上報狀態

裝置線上時，主動上報裝置狀態到影子，應用程式主動擷取裝置影子狀態。

資料流轉過程如下圖所示。

當燈泡lightbulb上線時，使用Topic /shadow/update/a1PbRCF****/lightbulb上報最新狀態到影子。

發送的JSON訊息格式：

{
    "method": "update", 
    "state": {
        "reported": {
            "color": "red"
        }
    }, 
    "version": 1
}

表 1. 上報參數說明
參數	說明
method	表示裝置或者應用程式請求裝置影子時的操作類型。當執行更新操作時，method為必要欄位，設定為update。
state	表示裝置發送給裝置影子的狀態資訊。 reported為必要欄位，狀態資訊會同步更新到裝置影子的reported部分。
version	表示裝置影子檢查請求中的版本資訊。只有當新版本大於目前的版本時，裝置影子才會接收裝置端的請求，並更新裝置影子版本。如果version設定為`-1`時，表示清空裝置影子資料，裝置影子會接收裝置端的請求，並將裝置影子版本更新為`0`。

裝置影子接收到燈泡上報的狀態資料後，更新影子文檔。

{
    "state": {
        "reported": {
            "color": "red"
        }
    }, 
    "metadata": {
        "reported": {
            "color": {
                "timestamp": 1469564492
            }
        }
    }, 
    "timestamp": 1469564492, 
    "version": 1
}

影子檔案更新後，裝置影子會返回結果給裝置（燈泡），即發送訊息到裝置訂閱的Topic /shadow/get/a1PbRCF****/lightbulb中。

若更新成功，發送到該Topic中的訊息為：

{
    "method": "reply", 
    "payload": {
        "status": "success", 
        "version": 1
    }, 
    "timestamp": 1469564576
}

若更新失敗，發送到該Topic中的訊息為：

{
    "method": "reply", 
    "payload": {
        "status": "error", 
        "content": {
            "errorcode": "${errorcode}", 
            "errormessage": "${errormessage}"
        }
    }, 
    "timestamp": 1469564576
}

表 2. 錯誤碼說明
errorCode	errorMessage
400	不正確的JSON格式。
401	影子資料缺少method資訊。
402	影子資料缺少state欄位。
403	影子資料中version值不是數字。
404	影子資料缺少reported欄位。
405	影子資料中 reported屬性欄位為空白。
406	影子資料中 method是無效的方法。
407	影子內容為空白。
408	影子資料中reported屬性個數超過128個。
409	影子版本衝突。
500	服務端處理異常。

應用程式改變裝置狀態

應用程式通過調用雲端API UpdateDeviceShadow下發期望狀態給裝置影子，裝置影子再將檔案下發給裝置端。裝置根據影子更新狀態，並上報最新狀態至影子。

資料流轉流程如下圖所示。

應用程式調用雲端API UpdateDeviceShadow，下發訊息更改燈泡狀態，例如需將燈泡的color屬性值改為green。
調用API時，參數ShadowMessage的值為：
```
{
    "method": "update", 
    "state": {
        "desired": {
            "color": "green"
        }
    }, 
    "version": 2
}
```

裝置影子接收到更新要求，更新其影子文檔為：

{
    "state": {
        "reported": {
            "color": "red"
        }, 
        "desired": {
            "color": "green"
        }
    }, 
    "metadata": {
        "reported": {
            "color": {
                "timestamp": 1469564492
            }
        }, 
        "desired": {
            "color": {
                "timestamp": 1469564576
            }
        }
    }, 
    "timestamp": 1469564576, 
    "version": 2
}

裝置影子更新完成後，發送返回結果到Topic/shadow/get/a1PbRCF****/lightbulb中。返回結果資訊構成由裝置影子決定。

{
    "method": "control", 
    "payload": {
        "state": {
            "reported": {
                "color": "red"
            }, 
            "desired": {
                "color": "green"
            }
        }, 
        "metadata": {
            "reported": {
                "color": {
                    "timestamp": 1469564492
                }
            }, 
            "desired": {
                "color": {
                    "timestamp": 1469564576
                }
            }
        }
    }, 
    "version": 2, 
    "timestamp": 1469564576
}

如果裝置燈泡線上，並且訂閱了Topic/shadow/get/a1PbRCF****/lightbulb，則會立即收到訊息。
收到訊息後，根據請求文檔中desired的值，將燈泡顏色變成綠色。

燈泡更新完狀態後，上報最新狀態到物聯網平台。
```
{
    "method": "update", 
    "state": {
        "reported": {
            "color": "green"
        }
    }, 
    "version": 3
}
```
說明如果有時間戳記判斷指令到期，也可以選擇不更新。

最新狀態上報成功後，裝置端和裝置影子進行以下操作。

裝置端發訊息到Topic/shadow/update/a1PbRCF****/lightbulb中清空desired屬性。訊息如下：
```
{
    "method": "update", 
    "state": {
        "desired": "null"
    }, 
    "version": 4
}
```

裝置影子會同步更新影子文檔，此時的影子文檔如下：

{
    "state": {
        "reported": {
            "color": "green"
        }
    }, 
    "metadata": {
        "reported": {
            "color": {
                "timestamp": 1469564577
            }
        }, 
        "desired": {
            "timestamp": 1469564576
        }
    }, 
    "version": 4
}

裝置主動擷取影子內容

若應用程式發送指令時，裝置離線。裝置再次上線後，將主動擷取裝置影子內容。

資料流轉過程如下圖所示。

燈泡主動發送以下訊息到Topic/shadow/update/a1PbRCF****/lightbulb中，請求擷取裝置影子中儲存的最新狀態。
```
{
    "method": "get"
}
```

當裝置影子收到這條訊息後，發送最新狀態到Topic/shadow/get/a1PbRCF****/lightbulb。燈泡通過訂閱該Topic擷取最新狀態。訊息內容如下：

{
    "method": "reply", 
    "payload": {
        "status": "success", 
        "state": {
            "reported": {
                "color": "red"
            }, 
            "desired": {
                "color": "green"
            }
        }, 
        "metadata": {
            "reported": {
                "color": {
                    "timestamp": 1469564492
                }
            }, 
            "desired": {
                "color": {
                    "timestamp": 1469564492
                }
            }
        }
    }, 
    "version": 2, 
    "timestamp": 1469564576
}

裝置主動刪除影子屬性

若裝置端已經是最新狀態，裝置端可以主動發送指令，刪除裝置影子中儲存的某條屬性狀態。

資料流轉過程如下圖所示。

裝置發送以下內容到Topic/shadow/update/a1PbRCF****/lightbulb中。

其中，method為delete，屬性的值為null。

刪除影子中某一屬性。

{
    "method": "delete", 
    "state": {
        "reported": {
            "color": "null", 
            "temperature": "null"
        }
    }, 
    "version": 1
}

刪除影子全部屬性。

{
    "method": "delete", 
    "state": {
        "reported": "null"
    }, 
    "version": 1
}