文档首页/ 智能设施云平台/ API参考/ API列表/ 设备影子能力管理/ 查询设备影子数据
更新时间：2025-08-19 GMT+08:00
查看PDF
分享

查询设备影子数据

功能介绍

应用服务器可调用此接口查询指定设备的设备影子信息，包括对设备的期望属性信息（desired区）和设备最新上报的属性信息（reported区）。

设备影子介绍：

设备影子是一个用于存储和检索设备当前状态信息的JSON文档。

  • 每个设备有且只有一个设备影子，由设备ID唯一标识

  • 设备影子用于存储设备上报的(状态)属性和应用程序期望的设备(状态)属性

  • 无论该设备是否在线，都可以通过该影子获取和设置设备的属性

  • 设备上线或者设备上报属性时，如果desired区和reported区存在差异，则将差异部分下发给设备，配置的预期属性需在产品模型中定义且method具有可写属性“W”才可下发

限制：

设备影子JSON文档中的key不允许特殊字符：点(.)、dollar符号($)、空char(十六进制的ASCII码为00)。如果包含了以上特殊字符则无法正常刷新影子文档。

URI

GET /v1/iotfm/devices/{device_id}/shadow

表1 路径参数

参数

是否必选

参数类型

描述

device_id

是

String

参数说明：下发属性的设备ID，用于唯一标识一个设备，在注册设备时由设施云平台分配获得。

取值范围：长度不超过128，只允许字母、数字、下划线（_）、连接符（-）的组合。

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

是

String

参数说明：用户Token。通过调用 生成Token 接口获取，接口返回的响应消息头中“X-Subject-Token”就是需要获取的用户Token。

X-Instance-Id

是

String

参数说明：实例ID。通过访问智能设施云平台界面后获取，智能设施云平台资源均为实例级隔离，所有业务接口必须填写正确的实例ID才能被成功调用。

取值范围：长度8-36，只允许大小写字母、数字和-字符的组合。

X-Root-Zone-Id

否

String

参数说明：项目ID。

取值范围：长度不超过24，只允许字母、数字的组合。

响应参数

状态码：200

表3 响应Body参数

参数

参数类型

描述

device_id

String

参数说明：下发属性的设备ID，用于唯一标识一个设备，在注册设备时由设施云平台分配获得。

取值范围：长度不超过128，只允许字母、数字、下划线（_）、连接符（-）的组合。

shadow

Array of DeviceShadowData objects

参数说明：设备影子数据结构体。
表4 DeviceShadowData

参数

参数类型

描述

service_id

String

参数说明：设备命令所属的设备服务ID，在设备关联的产品模型中定义。

取值范围：长度不超过64的字符串。

desired

DeviceShadowProperties object

参数说明：用户最近一次对设备下发的预期数据，Json格式，里面是一个个键值对，每个键都是产品模型中属性的参数名(property_name)。

reported

DeviceShadowProperties object

参数说明：设备最近一次上报的属性数据，Json格式，里面是一个个键值对，每个键都是产品模型中属性的参数名(property_name)。

version

Long

参数说明：设备影子的版本，携带该参数时平台会校验值必须等于当前影子版本，初始从0开始。
表5 DeviceShadowProperties

参数

参数类型

描述

properties

Object

参数说明：设备影子的属性数据，Json格式，里面是一个个键值对，每个键都是产品模型中属性的参数名(property_name)，目前如样例所示只支持一层结构。

注意：JSON结构的key当前不支持特殊字符：点(.)、dollar符号($)、空char(十六进制的ASCII码为00)，key为以上特殊字符无法正常刷新设备影子。

event_time

String

参数说明：事件操作时间，格式为："yyyy-MM-dd'T'HH:mm:ss.SSS'Z'"。

状态码：400

表6 响应Body参数

参数

参数类型

描述

error_code

String

参数说明：错误码。

取值范围：长度8-36。

error_msg

String

参数说明：错误描述。

取值范围：长度2-512。

请求示例

查询指定设备的设备影子。

GET https://{endpoint}/v1/iotfm/devices/16087212bc75410c9ad77163b4cf6aba/shadow

响应示例

状态码：200

OK

{
  "device_id" : "16087212bc75410c9ad77163b4cf6aba",
  "shadow" : [ {
    "service_id" : "WaterMeter",
    "desired" : {
      "properties" : {
        "temperature" : "60"
      },
      "event_time" : "2022-12-26T01:52:49.999Z"
    },
    "reported" : {
      "properties" : {
        "temperature" : "59"
      },
      "event_time" : "2022-12-26T01:52:49.999Z"
    },
    "version" : 1
  } ]
}

状态码

状态码

描述

200

OK

400

Bad Request

403

Forbidden

404

Not Found

500

Internal Server Error

相关文档