设备影子数据流

一、设备影子描述

设备影子是设备在云端的镜像，每个设备有且只有一个设备影子，影子存储设备最近的状态和应用程序期望，通过改变影子状态可以实现云端对对于设备的状态管控。

二、通讯协议

2.1 通讯方式

2.2 Topic定义

设备影子数据通过以下Topic进行流转。

三、场景示例

示例以灯泡设备为例，属性为灯泡的颜色，定义属性名为 color ，值有 red、green等值。

下面将主要介绍以下几个场景，方便您快速了解设备影子的通讯机制：

1. 应用程序改变设备状态

2. 应用程序或设备获取设备影子最新状态

3. 应用程序或设备删除影子信息

4. 应用程序或设备设置影子错误信息

3.1 应用程序改变设备状态

1.【应用程序】设置影子属性期望值

应用程序更新期望状态，使用Topic /${productId}/${deviceId}/shadow/update 上报期望值。发送JSON消息格式如下：

{
    "method":"update",
    "messageId":"157889065984",
    "state":{
        "desired":{
            "power_setting": {
                "flag": true,
                "config": {
                  "icon": "/test.png"
                }
            }
        }
    },
    "timestamp":0
}

参数说明

当前云鲸设备影子未对设备影子Key做数据大小或业务Key值的校验，但建议设备影子内业务Key不要超过128个。

2. 【设备影子服务】保存设备影子

设备影子接口到应用上报的期望值数据后，更新云端的设备影子文档

{
    "state":{
        "desired":{
            "power_setting": {
                "flag": true,
                "config": {
                  "icon": "/test.png"
                }
            }
        }
    },
    "metadata":{
        "desired":{
            "power_setting": {
                "timestamp": 1469564576000
             }
         }
    },
    "timestamp":1469564576000
 }

设备影子文档说明

3. 【设备影子服务】下发期望值更新

设备影子收到更新请求后，进行验证更新，结果发送到Topic： /${productId}/${deviceId}/shadow/get

1）若成功更新，发送到该 Topic 中的消息为：

{
    "method":"control",
    "messageId":"157889065984",
    "payload":{
        "code":0,
        "state":{
           "desired":{
                "power_setting": {
                    "flag": true,
                    "config": {
                      "icon": "/test.png"
                    }
                }
            }
        },
        "metadata":{
            "desired":{
                "power_setting":{
                    "timestamp":1469564576000
                }
            }
        }
    },
    "timestamp":1469564576000
}

2）若更新失败，发送到该 Topic 的消息为：

表示响应失败,并返回具体错误码和错误消息。

{
    "method":"reply",
    "messageId":"157889065985",
    "payload":{
        "code": ${errorcode},
        "msg": "${errormessage}"
     }
}

表示影子版本冲突导致响应失败。设备影子服务会返回云端设备影子更新时间，设备端应保存该设备影子最新更新时间。然后设备端应当检查当前messageId对应的上报数值是否与本地属性值一致，如一致则使用设备影子最新更新时间再次进行上报更新，如不一致则丢弃该上报消息。

{
    "method":"reply",
    "messageId":"157889065985",
    "payload":{
        "code":900010,
        "msg":"影子版本冲突。"
    },
    "timestamp":1626317187000
}

4. 【设备】检测当前值和期望值，执行业务

设备订阅Topic： /${productId}/${deviceId}/shadow/get，接收到设备影子期望值更新消息后，进行检测后执行本地业务更新。

5. 【设备】上报设备影子当前状态

本地业务更新完成后上报当前状态到 Topic：/${productId}/${deviceId}/shadow/update。发送的JSON消息格式：

{
    "method":"update",
    "messageId":"157889065985",
    "state":{
        "reported":{
            "power_setting": {
                "flag": false,
                "config": {
                  "icon": "/test.png"
                }
            }
        }
    },
    "timestamp":1626317187000
}

参数说明

6. 【设备影子服务】保存设备影子

设备影子收到更新请求后，进行验证更新，更新通过后更新云端的设备影子文档如下：

{
    "state":{
        "desired":{
            "power_setting": {
                "flag": true,
                "config": {
                  "icon": "/test.png"
                }
            }
        },
        "reported":{
            "power_setting": {
                "flag": false,
                "config": {
                  "icon": "/test.png"
                }
            }
        }
    },
    "metadata":{
        "desired":{
            "power_setting":{
                "timestamp":1469565576000
            }
        },
        "reported":{
            "power_setting":{
                "timestamp":1469565576000
            }
        }
    },
    "timestamp":1469565576000
}

设备影子文档说明

7. 【设备影子服务】下发设备当前值更新

设备影子文档更新后，结果发送到Topic： /${productId}/${deviceId}/shadow/get

1）若成功更新，发送到该 Topic 中的消息为：

{
    "method":"update",
    "messageId":"157889065985",
    "payload":{
        "code":0,
        "state":{
            "reported":{
                "power_setting":{
                    "flag":false,
                    "config":{
                        "icon":"/test.png"
                    }
                }
            }
        },
        "metadata":{
            "reported":{
                "color":{
                    "timestamp":1469565576000
                }
            }
        }
    },
    "timestamp":1469565576000
}

2）若更新失败，发送到该 Topic 的消息为：

表示响应失败,并返回具体错误码和错误消息。

{
    "method":"reply",
    "messageId":"157889065985",
    "payload":{
        "code": ${errorcode},
        "msg": "${errormessage}"
     }
}

表示影子版本冲突导致响应失败。设备影子服务会返回云端设备影子更新时间，设备端应保存该设备影子最新更新时间。然后设备端应当检查当前messageId对应的上报数值是否与本地属性值一致，如一致则使用设备影子最新更新时间再次进行上报更新，如不一致则丢弃该上报消息。

{
    "method":"reply",
    "messageId":"157889065985",
    "payload":{
        "code":900010,
        "msg":"影子版本冲突。"
    },
    "timestamp":1469565576000
}

3.2 应用程序或设备获取设备影子最新状态

1. 【设备或应用程序】重新连接MQTT Broker

应用程序或设备重新联网后，与MQTT Broker 重新建立连接

2.【设备或应用程序】发起获取最新设备影子状态

应用程序或设备发送主动获取设备影子消息到Topic：/${productId}/${deviceId}/shadow/update ，发送的消息格式：

{
  "method":"get",
  "messageId":"157065985"
}

3. 【设备影子服务】查询设备影子最新状态

设备影子服务接收到请求后，查询最新的设备影子文档

4. 【下发设备影子最新状态】

设备影子服务发送设备影子最新状态到Topic: /${productId}/${deviceId}/shadow/get ，发送的消息格式：

{
    "method": "reply",
    "messageId": "157065985",
    "payload": {
        "code": 0,
         "state": {
            "desired": {
                "color": "green"
            },
            "reported": {
                "color": "red"
            }
        },
        "metadata": {
            "desired": {
                "color": {
                    "timestamp": 1469564576000
                }
            },
            "reported": {
                "color": {
                    "timestamp": 1469565576000
                }
            }
        }
    },
    "timestamp": 1469565576000
}

5. 【检查设备影子状态、执行业务】

应用程序或设备获取到设备影子最新状态后，执行业务

3.3 应用程序或设备删除影子信息

1.【应用程序或设备】触发清除设备影子信息逻辑

应用程序或者设备在处理逻辑时，检测到设备影子当前值或期望值已经无效时或需要重置设备影子进行触发清除操作。

2.【应用程序或设备】发送清除设备影子消息

发送清除设备影子消息到到Topic：/${productId}/${deviceId}/shadow/update

清空设备影子信息消息内容如下：

当进行清空或者删除全部上报值或期望值是，设备影子服务判断传递的timestamp是否等于设备影子最新时间戳，如不满足，则提示版本冲突，不进行删除

{
    "method": "clean",
    "messageId":"1241121"
}

清除上报全部属性值消息内容如下：

{
    "method": "delete",
    "messageId":"1241121",
    "state": {
        "reported": "null"
    },
    "timestamp": 1469565576000
}

清除期望全部属性值消息内容如下：

{
    "method": "delete",
    "messageId":"1241121",
    "state": {
        "desired": "null"
    },
    "timestamp": 1469565576000
}

当删除具体属性值时，设备影子服务先进行判断传递的timestamp是否等于设备影子最新时间戳，不等于则判断是否大于等于该字段的metadata中的最后更新时间戳，如不满足，则提示版本冲突，不进行删除

清除上报某一属性值消息内容如下：

{
    "method": "delete",
    "messageId":"1241121",
    "state": {
        "reported": {
            "color": "null"
        }
    },
    "timestamp": 1469565576000
}

清除期望某一属性值消息内容如下：

{
    "method": "delete",
    "messageId":"1241121",
    "state": {
        "desired": {
            "color": "null"
        }
    },
    "timestamp": 1469565576000
}

为满足部分业务在处理完成期望值后，需要将相同key的期望值删除并同时上报上报值的业务，提供一个原子方法同时进行处理。
当进行该业务处理时，设备影子服务先判断传递的timestamp是否等于设备影子最新时间戳，不等于则同时判断是否大于等于该字段上报值和期望值的metadata中的最后更新时间戳，如不满足，则提示版本冲突，不进行处理

删除期望值并更新上报值消息内容如下：

{
    "method": "updateAndDelete",
    "messageId":"1241121",
    "state": {
        "reported": {
            "color": "red"
        }
    },
    "timestamp": 1469565576000
}

删除上报值并更新期望值消息内容如下：

{
    "method": "updateAndDelete",
    "messageId":"1241121",
    "state": {
        "desired": {
            "color": "red"
        }
    },
    "timestamp": 1469565576000
}

3. 【设备影子服务】更新设备影子消息

设备影子服务在接收到更新设备影子消息时，进行更新设备影子文档信息。

{
    "state":{
        "desired":{
        },
        "reported": {
        }
    },
    "metadata":{
        "desired":{
            "color": {
                "timestamp": 1469566876000
             }
         },
        "reported": {
           "color": {
                "timestamp": 1469566876000
             }
        }
    }
    "timestamp":1469566876000
 }

4. 【设备影子服务】返回清除设备影子消息结果

设备影子服务在更新设备影子文档结束后，发送处理结果到Topic：/${productId}/${deviceId}/shadow/get

更新成功返回结果如下：

{
    "method":"reply",
    "messageId":"1241121",
    "payload":{
        "code":0
    }
}

更新失败返回结果如下：

{
    "method":"reply",
    "messageId":"1241121",
    "payload":{
        "code": ${errorcode},
        "msg": "${errormessage}"
     }
}

3.4 应用程序或设备设置影子错误信息

1. 【应用程序】执行业务，设置期望值

应用程序在执行相应业务后，对属性期望值进行更新。

2. 【应用程序】发送设置期望值信息

进行设置期望值动作，动作内容同本文档中3.1.1示例，

3. 【设备影子服务】更新设备影子信息

设备影子服务在收到应用程序设备期望值信息后，保存到设备影子中，动作内容同本文档中3.1.2示例

4. 【设备影子服务】广播期望值更新信息

设备影子服务保存期望到设备影子后，进行广播期望值更新信息，动作内容同本文档中3.1.3示例

5. 【设备】获取期望值信息后执行业务，发现期望值无法执行

设备在获取到期望值的更新后，根据设置的期望值进行执行业务，发现期望值数据因某种原因无法执行成功。

6. 【设备】上报期望值错误信息

设备更新错误信息到 Topic：/${productId}/${deviceId}/shadow/update。发送的JSON消息格式：

{
    "method":"setError",
    "messageId":"157889065987",
    "state":{
        "desired":{
            //对应执行错误的字段，错误信息由业务决定
            "power_setting": {
              "code": 1
            }
        }
    },
    "timestamp":1469566876000
}

参数说明

7. 【设备影子服务】更新设备影子信息

设备影子服务在接受到上报错误信息后，将其保存到设备影子中。

{
    "state":{
        "desired":{
            "power_setting": {
                "flag": true,
                "config": {
                  "icon": "/test.png"
                }
            }
        }
    },
    "metadata":{
        "desired":{
            "power_setting": {
                "timestamp": 1469564586000,
                //该字段的错误信息
                "error":{
                    "code": 1
                }
             }
         }
    }
    "timestamp":1469564576000,
 }

设备影子文档说明

8. 【设备影子服务】广播期望值错误信息更新

设备影子文档更新后，结果发送到Topic： /${productId}/${deviceId}/shadow/get

1）若成功更新，发送到该 Topic 中的消息为：

{
    "method":"setError",
    "messageId":"157889065987",
    "payload":{
        "code":0,
        "state":{
            "desired":{
                "power_setting":{
                    "flag":true,
                    "config":{
                        "icon":"/test.png"
                    }
                }
            }
        },
        "metadata":{
            "desired":{
                "color":{
                    "timestamp":1469565576000,
                    "error": {
                        "code": 1
                    }
                }
            }
        }
    },
    "timestamp":1469565596000
}

2）若更新失败，发送到该 Topic 的消息为：

表示响应失败,并返回具体错误码和错误消息。

{
    "method":"reply",
    "messageId":"157889065987",
    "payload":{
        "code": ${errorcode},
        "msg": "${errormessage}"
     }
}

表示影子版本冲突导致响应失败。设备影子服务会返回云端设备影子更新时间，设备端应保存该设备影子最新更新时间。然后设备端应当检查当前messageId对应的上报数值是否与本地属性值一致，如一致则使用设备影子最新更新时间再次进行上报更新，如不一致则丢弃该上报消息。

{
    "method":"reply",
    "messageId":"157889065987",
    "payload":{
        "code":900010,
        "msg":"影子版本冲突。"
    },
    "timestamp":1469565596000
}

9. 【应用程序】获取到设置错误广播消息，执行业务

应用程序在获取到设置错误的广播消息之后，根据错误信息进行对应业务的执行

10. 【应用程序】更新错误期望值信息

进行设置期望值动作，动作内容同本文档中3.1.1示例

11. 【设备影子服务】更新设备影子信息

设备影子服务在收到应用程序设备期望值信息后，保存到设备影子中，动作内容同本文档中3.1.2示例

四、错误码

五、method枚举

/${productId}/${deviceId}/shadow/update Topic 使用method:

/${productId}/${deviceId}/shadow/get Topic 使用method: