概念介绍

设备影子概述

设备影子（Device Shadow）是物联网平台为每个设备在云端维护的一份 JSON 文档，用于缓存设备的最新上报状态（reported）和应用期望状态（desired）。平台自动计算二者的差异值（delta），并在设备在线时推送 delta 供设备执行。

核心价值：

• 状态持久化：设备最新属性值持久化在云端，应用可直接查询，无需下发指令
• 离线指令暂存：设备离线时，应用仍可设置期望状态，设备上线后自动同步
• 状态收敛：设备上报的 reported 满足 desired 后，平台自动清理已满足的期望值
• 多入口一致性：REST / MQTT / 设备上线三种入口得到相同的领域结果
• 通信解耦：应用与设备无需同时在线，通过影子文档实现异步交互
• Delta 差量同步：仅同步 reported 与 desired 之间的差异属性，减少网络传输
• 版本控制：每次更新 version 自增，乐观锁机制防止并发冲突

一、架构概览

设备影子充当设备与应用之间的中介层，解耦了设备端与应用端的直接通信依赖。

角色	操作	说明
设备端	写入 reported	设备上报当前属性状态
应用端	写入 desired	应用设置期望设备达到的目标状态
平台	自动计算 delta	对比 reported 与 desired，计算差异
平台	推送 delta	设备在线时，将差异推送给设备执行

二、典型应用场景

场景一：设备离线时设置期望值

时间	事件	影子变化
T1	空调设备离线	设备状态变为 OFFLINE
T2	用户通过 APP 设置温度 26°C	desired.temperature = 26，Delta 暂存
T3	空调设备上线	平台推送 Delta { temperature: 26 }
T4	空调执行调温并上报	reported.temperature = 26
T5	同步完成	Delta 清空，desired.temperature 自动清除

场景二：应用查询设备最新状态

设备每 5 分钟上报一次温度，上报值自动更新到影子的 reported 中。用户打开 APP 时，直接读取影子中的 reported.temperature 即可获得最新值，无需向设备下发查询指令。

场景三：弱网环境下的状态同步

应用连续下发 3 条属性设置指令（A=1, B=2, C=3），全部合并到 desired 中。设备在弱网下只收到 1 次 delta 推送，但该推送包含完整的差异（A=1, B=2, C=3），设备一次性执行所有变更。

三、影子文档字段总览

字段	类型	写入方	说明
state.reported	Object	设备	设备最近一次上报的属性状态
state.desired	Object	应用	应用期望设备达到的目标状态
state.delta	Object	平台（自动）	reported 与 desired 的差异值
metadata.reported	Object	平台（自动）	每个 reported 属性的最后更新时间戳
metadata.desired	Object	平台（自动）	每个 desired 属性的最后更新时间戳
version	Integer	平台（自动）	影子版本号，每次更新自增 1
timestamp	Long	平台（自动）	影子文档最后更新时间（毫秒）