設備鏡像

設備鏡像是OneNET為每一個設備分配的用於存放裝置最新狀態/配置信息的json文檔

應用場景

設備鏡像可以應用於以下場景：

• 存放裝置靜態屬性，例如：設備的安裝位置
• 存放裝置當前狀態信息，例如：設備當前網路連接模式、運行狀態
• 同步設備與應用之間的長時間任務的執行狀態，例如：設備上報固件升級過程中的各個狀態與升級結果通知
• 應用層查詢設備的配置/狀態信息
• 在弱網/低功耗狀態下，應用層期望設備達到的某個長期的配置/狀態，設備鏡像可以託管該通信過程，在設備上線後完成該配置/狀態的期望值通信

設備鏡像json文檔包含如下信息：

• 系統屬性 系統為設備定義的屬性，例如，設備ID、創建時間、在線狀態等，對設備不可見，對應用層為只讀

• 標記（tags） 用於標記設備類別，例如，部署區域、應用項目，對設備不可見，對應用層為可讀寫

• 期望屬性（desired） 用於應用層表達設備所期望達到的某個狀態/配置，對應用層與設備均為可讀寫

• 報告屬性（reported） 用於設備上報當前的狀態/配置信息，與期望屬性結合使用，當設備報告屬性與期望屬性存在差異，平台可以發送該差異給設備，可實現同步設備配置/狀態，對應用層與設備均為可讀寫

• 屬性差異（delta） 用於表達報告屬性與期望屬性之間的差異值，每次鏡像json更新後，均會觸發差異計算，若存在差異值，平台可以發送該差異消息給設備，該差異對於應用層與設備均為只讀

常見使用方式

在實際應用場景中可以參考如下使用方式：

• 設備訂閱delta消息並上報屬性至reported
• 應用層在需求設備進行狀態/配置信息變更時，更新desired屬性
• 設備在線且設備訂閱了delta消息時，平台下發delta消息至設備
• 設備接收delta消息並作出狀態/配置調整，上報新的屬性至reported，當reported與desired一致時，delta屬性消失
• 設備與應用可定期查詢全量屬性
• 應用可通過標籤標記設備類別

設備鏡像json

設備鏡像json示例如下：

{
    "deviceId": "638612",
    "createTime": 1469564492,
    "status": "enabled",
    "statusReason": "created",
    "statusUpdateTime": 1469564492,
    "connectionState": "online",
    "lastActivityTime": 1469564492,

    "tags": {
        "building": "43",
        "floor": "1"
    },

    "properties": {
        "state": {
            "desired": {
                "lights": {
                    "color": "RED"
                },
                "engine": "ON"
            },
            "reported": {
                "lights": {
                    "color": "GREEN"
                },
                "engine": "ON"
            },
            "delta": {
                "lights": {
                    "color": "RED"
                }
            }
        },
        "metadata": {
            "desired": {
                "lights": {
                    "color": {
                        "timestamp": 1469564492
                    }
                },
                "engine": {
                    "timestamp": 1469564492
                }
            },
            "reported": {
                "lights": {
                    "color": {
                        "timestamp": 1469564492
                    }
                },
                "engine": {
                    "timestamp": 1469564492
                }
            }
        },
        "version": 10,
        "timestamp": 1469564492
    }
}

json中，系統屬性欄位說明如下：

使用限制

設備鏡像json物件具有以下使用限制：

• json整體大小不得超過4k
• properties中key的使用限制：長度1－30，由英文字母、數位、底線組成
• properties中當value為字串時，字串最大長度限制為512位元組
• properties中當value為整數時，數值範圍為－4503599627370496~4503599627370495
• properties中reported 與desired屬性json物件的最大嵌套深度為4層，例如以下物件是有效的：

{
    "state": {
        "reported": {
            "one": {
                "two": {
                    "three": {
                        "four": {
                            "key": "value"
                        }
                    }
                }
            }
        }
    }
}

更多幫助

• 了解設備鏡像控制台使用
• 了解設備開發指南，見設備鏡像topic簇的使用手冊