全部产品
云市场

设备影子

更新时间:2019-06-25 09:45:26

功能介绍

设备影子是一个 JSON 文档,用于存储设备上报的状态、应用程序期望状态信息。

  • 每个设备有且只有一个设备影子,设备可以通过MQTT获取和设置设备影子来同步设备与物联网平台上存储的数据,该同步可以是云端的影子同步给设备,也可以是设备同步给云端的影子。

  • 应用程序通过物联网平台的SDK获取和设置设备影子,获取设备最新状态或者下发期望状态给设备。

具体影子的详细介绍见物联网平台的设备影子章节

API说明

监听影子变更

API原型 iot.device#onShadow(callback)
功能说明 监听设备影子的变化,不论是设备端主动更新影子、设备端获取影子都会被调用
参数说明
- callback:回调函数

代码示例:

  1. device.onShadow((res) => {
  2. console.log('获取最新设备影子,%o', res);
  3. })

用户需要分析返回的内容判断是更新成功、失败、还是云端主动向设备推送设备影子等情况,下面将会分情况进行说明

设备端更新云端影子

API原型 iot.device#postShadow(params)
功能说明 上报设备影子
参数说明
- params:影子的内容,为一个JSON对象

代码示例:

  1. device.postShadow({
  2. "a": "avalue"
  3. });

设备调用postShadown()之后,device.onShadow()将会被调用,若影子更新成功传递给onShadow()的res内容如下所示:

  1. {
  2. "method": "reply",
  3. "payload": {
  4. "status": "success",
  5. "version": 1
  6. },
  7. "timestamp": 1469564576
  8. }

用户可以根据method的数值“reply”得知res的数值是云端对更新的响应,根据“status”为“success”得知影子更新成功;若影子更新失败,则传递给onShadow()的res内容如下所示:

  1. {
  2. "method": "reply",
  3. "payload": {
  4. "status": "error",
  5. "content": {
  6. "errorcode": "${errorcode}",
  7. "errormessage": "${errormessage}"
  8. }
  9. },
  10. "timestamp": 1469564576
  11. }

用户可以根据“status”的值“error”得知更新影子失败,errorcode的数值定义如下:

errorCode errorMessage
400 不正确的JSON格式
401 影子JSON缺少method信息
402 影子JSON缺少state字段
403 影子JSON version不是数字
404 影子JSON缺少reported字段
405 影子JSON reported属性字段为空
406 影子JSON method是无效的方法
407 影子内容为空
408 影子reported属性个数超过128个
409 影子版本冲突
500 服务端处理异常

查询云端影子数据

API原型 iot.device#getShadow()
功能说明 从物联网平台获取最新的影子数据
参数说明

代码示例:

  1. // 设备主动获取影子,回调函数会触发onShadow方法,返回设备影子信息
  2. device.getShadow();

该函数调用之后将会触发物联网平台将影子发送给设备,在onShadow()中收到的数据格式示例如下:

  1. {
  2. "method": "reply",
  3. "payload": {
  4. "status": "success",
  5. "state": {
  6. "reported": {
  7. "color": "red"
  8. },
  9. "desired": {
  10. "color": "green"
  11. }
  12. },
  13. "metadata": {
  14. "reported": {
  15. "color": {
  16. "timestamp": 1469564492
  17. }
  18. },
  19. "desired": {
  20. "color": {
  21. "timestamp": 1469564492
  22. }
  23. }
  24. }
  25. },
  26. "version": 2,
  27. "timestamp": 1469564576
  28. }

用户可以解析”payload”->”state”中的”reported”得知设备以前上报的影子,分析”desired”得知云端主动修改的影子的数值

云端修改影子数值

物联网平台上的应用程序可能修改影子的数值,在这种情况下云端会将影子数据发送给设备,onShadow()中的res数据格式示例如下:

  1. {
  2. "method": "control",
  3. "payload": {
  4. "status": "success",
  5. "state": {
  6. "reported": {
  7. "color": "red"
  8. },
  9. "desired": {
  10. "color": "green"
  11. }
  12. },
  13. "metadata": {
  14. "reported": {
  15. "color": {
  16. "timestamp": 1469564492
  17. }
  18. },
  19. "desired": {
  20. "color": {
  21. "timestamp": 1469564576
  22. }
  23. }
  24. }
  25. },
  26. "version": 2,
  27. "timestamp": 1469564576
  28. }

用户可以通过“method”的数值为“control”得知这时云端更新了影子。同时通过”state”->”desired”得知修改的内容

删除影子

API原型 iot.device#deleteShadow(keys)
功能说明 删除设备影子
参数说明
- keys:需要删除的设备影子的属性的数组

代码示例:

  1. // 删除影子的单个属性
  2. device.deleteShadow("a");
  3. // 删除影子的多个属性
  4. device.deleteShadow(["a","b"]);
  5. // 删除影子的所有属性
  6. device.deleteShadow()

示例代码

Github提供了代码示例供开发者参考。