设备影子数据流

约 1483 字大约 5 分钟

2026-08-18

设备影子数据通过 Topic 进行流转，主要包括设备上报状态到设备影子、应用程序更改设备状态、设备离线再上线后主动获取设备影子信息，和设备端请求删除设备影子中的属性信息。

设备影子 Topic

物联网平台已为每个设备预定义了两个Topic，用于实现设备影子数据流转。

Topic	用途
`shadow/update/${productKey}/${deviceName}`	设备和应用程序发布消息到此Topic。物联网平台收到该Topic的消息后，将消息中的状态更新到设备影子中。
`shadow/get/${productKey}/${deviceName}`	设备影子更新状态到该Topic，设备订阅此Topic获取最新消息。

使用示例

本文以灯泡设备为例，说明设备、设备影子以及应用程序之间的通信，主要介绍设备主动上报状态、应用程序改变设备状态、设备主动获取影子内容，和设备主动删除影子属性。

示例中，产品的 ProductKey 是 a1PbRCF****；设备名称 DeviceName 是 lightbulb。设备以 QoS=1 发布消息和订阅两个设备影子 Topic。

设备端开发设备影子能力的方法，请参见设备影子。

设备主动上报状态

设备在线时，主动上报设备状态到影子，应用程序主动获取设备影子状态。

当灯泡lightbulb上线时，使用Topic /shadow/update/a1PbRCF****/lightbulb 上报最新状态到影子。

发送的 JSON 消息格式：

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

参数	说明
method	表示设备或者应用程序请求设备影子时的操作类型。当执行更新操作时，`method` 为必填字段，设置为 `update`。
state	表示设备发送给设备影子的状态信息。 `reported` 为必填字段，状态信息会同步更新到设备影子的 `reported` 部分。
version	表示设备影子检查请求中的版本信息。只有当新版本大于当前版本时，设备影子才会接收设备端的请求，并更新设备影子版本。如果 `version` 设置为 `-1` 时，表示清空设备影子数据，设备影子会接收设备端的请求，并将设备影子版本更新为 `0`。

表1. 上报参数说明

设备影子接收到灯泡上报的状态数据后，更新影子文档。

{
  "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
}

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

表2. 错误码说明

应用程序改变设备状态

应用程序通过调用云端API 下发期望状态给设备影子，设备影子再将文件下发给设备端。设备根据影子更新状态，并上报最新状态至影子。

应用程序调用云端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/get/a1PbRCF****/lightbulb 中。

最新状态上报成功后，设备端和设备影子进行以下操作。

设备端发消息到Topic /shadow/update/a1PbRCF****/lightbulb 中清空 desired 属性。消息如下：

{
  "method": "update",
  "state": {
    "desired": "null"
  },
  "version": 4
}

设备影子会同步更新影子文档，此时的影子文档如下：

{
  "state": {
    "reported": {
      "color": "green"
    }
  },
  "metadata": {
    "reported": {
      "color": {
        "timestamp": 1469564577
      }
    }
  },
  "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
}

设备安全认证

配置物模型

Link协议自主开发

设备影子