更新时间:2022-02-24 GMT+08:00

修改设备影子

典型场景

物联网平台支持创建设备的“影子”。设备影子用于存储设备最新上报的服务属性数据,以及第三方应用对服务属性的配置(服务属性为设备Profile文件中定义的service属性)。若设备处于离线或异常状态时,第三方应用无法通过命令下发的方式向设备下发配置,此时可把要下发的配置设置到设备影子,当设备重新上线时,设备影子会把配置下发给设备。第三方应用可调用此接口在设备影子上配置要下发给设备的配置信息。

每个设备有且只有一个设备影子,设备影子上有desired和report区。

  • desired区用于存储对设备服务属性的配置。若设备当前在线,desired区的配置会即时下发给设备;若设备当前不在线,desired区的配置会在设备上线时再下发给设备。
  • report区用于存储设备最新上报的服务属性数据。当设备上报数据时,平台会把数据同步到设备影子的report区。

接口功能

支持第三方应用配置设备影子desired区的信息,用于设备上线时把配置下发给设备。

接口描述

1
void modifyDeviceShadow(ModifyDeviceShadowInDTO mdsInDTO, String deviceId, String appId, String accessToken) throws NorthApiException

接口所属类

DeviceManagement

参数说明

参数

必选/可选

类型

位置

描述

deviceId

必选

String(256)

path

设备ID,用于唯一标识一个设备,在注册设备时由物联网平台分配获得。

appId

必选

String

query

如果是本应用的设备,此参数值可以填写null,否则填写授权应用的appId。

accessToken

必选

String

header

如果调用了定时刷新token接口,此参数值可以填写null,否则要填写鉴权接口获取的accessToken。

mdsInDTO

必选

ModifyDeviceShadowInDTO

body

具体参见ModifyDeviceShadowInDTO结构体的描述。

ModifyDeviceShadowInDTO结构体:

参数

必选/可选

类型

位置

描述

serviceDesireds

必选

List<ServiceDesiredDTO>

body

需要修改的设备配置或状态信息。具体参见ServiceDesiredDTO结构体。

ServiceDesiredDTO结构体说明:

参数

必选/可选

类型

位置

描述

serviceId

可选

String(1-256)

body

服务ID,用于标识一个服务。

desired

可选

ObjectNode

body

设备的服务属性配置。

返回值

void

错误码

Http状态码

错误码

错误描述

说明

200

100425

The special deviceCapability is not exist.

设备模板不存在。

处理建议:请检查设备模板是否已在物联网平台上传。

200

100431

The serviceType is not exist.

服务类型不存在。

处理建议:

  • 请检查该设备的Profile文件是否已上传到物联网平台。
  • 请检查请求参数是否正确,或者serviceId在Profile文件中是否存在。

400

107002

The properties is empty in database.

设备属性不存在。

处理建议:请检查接口请求中的serviceId是否有误。

400

107003

The request properties is unknown.

设备状态为未知。

处理建议:请检查设备与平台的连接是否正常。

400

50400

The input is invalid.

输入参数无效。

处理建议:请检查接口调用请求中携带参数的合法性。

403

100203

The application is not existed.

应用不存在。

处理建议:

  • 请检查HTTP请求头域中携带的appId是否有误。
  • 请检查请求路径(url)中传入的appId是否有误。

403

100217

The application hasn't been authorized.

应用未被授权。

处理建议:若非应用授权场景,请确认请求参数中的appId为空。

403

100443

The property is forbidden to write.

设备属性不可写。

403

1010009

app throttle exceed.

应用调用接口过于频繁,超过流控值(默认值是100次/60s)。

处理建议:联系物联网平台维护人员调大流控阈值或者控制接口的调用频率。

403

1010005

pp_key or access_token is invalid.

错误的token信息。

处理建议:请检查接口请求中所携带的accessToken是否有误。

404

100403

The device is not existed.

设备不存在。

处理建议:物联网平台未找到deviceId对应的设备,请检查deviceId是否有误。

404

100418

The deviceData is not existed.

设备信息不存在。

处理建议:

  • 请求参数中携带的deviceId错误。请确认该deviceId是否属于该appId或者deviceId是否写错。
  • Header中携带的appId有误,请确认该appId下是否有该deviceId。
  • 如果URL中携带了可选参数appId,请检查该appId是否有误。

500

100023

The data in dataBase is abnomal.

数据库异常。

处理建议:物联网平台内部错误,请联系物联网平台维护人员处理。

500

100203

The application is not existed.

应用不存在。

处理建议:

  • 请检查HTTP请求头域中携带的appId是否有误。
  • 请检查请求路径(url)中传入的appId是否有误。

500

50252

Internal server error.

服务器运行内部错误。

处理建议:物联网平台内部错误,请联系物联网平台维护人员处理。