更新时间:2023-04-13 GMT+08:00
分享

修改设备影子

接口说明

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

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

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

注意事项

当前仅使用LWM2M协议的设备支持设备影子功能,且仅支持修改LWM2M协议定义的属性信息,用户自定义的属性暂不支持修改。

URI

请求方法

PUT

URI

/iocm/app/shadow/v1.5.0/devices/{deviceId}

传输协议

HTTPS

请求参数

参数

必选/可选

类型

位置

描述

app_key

必选

String

header

访问物联网平台的应用ID,在物联网平台创建应用时由平台分配获得。

Authorization

必选

String

header

访问物联网平台的认证信息,值为“Bearer {accessToken}”,其中{accessToken}为调用鉴权接口返回的accessToken。

deviceId

必选

String

path

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

appId

可选

String

query

设备所属的应用ID,当修改授权应用下设备的设备影子时才需要填写。

serviceDesireds

必选

List<ServiceDesiredDTO>

body

需要修改的设备配置或状态信息。

ServiceDesiredDTO:

参数

必选/可选

类型

位置

描述

serviceId

必选

String(1-256)

body

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

desired

必选

ObjectNode

body

设备的服务属性配置,jsonString格式,里面是一个个健值对(key: value),“key”是产品模型中的属性名称(propertyName),“value”是该属性的取值,根据产品模型中属性的取值范围自定义设置。

产品模型中仅“访问模式”“W”(可写)的属性支持在设备影子中设置。

响应参数

Status Code: 200 OK

请求示例

PUT https://{host}:{port}/iocm/app/shadow/v1.5.0/devices/devices/{deviceId}?appId={appId}
Content-Type: application/json
app_key: ******
Authorization: Bearer ******

{
  "serviceDesireds": [
    {
      "serviceId": "Temperature",
      "desired": {
        "targetTemperature": 35
      }
    }
  ]
}

正常响应示例

Status Code: 200 OK

错误码

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.

服务器运行内部错误。

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

分享:

    相关文档

    相关产品