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

设备服务调用

典型场景

设备Profile文件中定义了物联网平台可向设备下发的命令,第三方应用可调用此接口向设备下发命令,配置或修改设备的服务属性,以实现对设备的控制。

物联网平台不对设备命令进行缓存而是直接下发命令,设备不在线时命令下发失败。下发命令的具体格式需要第三方应用与设备自定义,物联网平台在接口中直接进行封装,透传。

说明:

目前该接口仅用于安装了IoT Agent/AgentLite的网关设备,通过向网关设备下发命令,可对网关下的非直连设备进行控制。

接口功能

支持第三方应用向设备立即下发命令(当前仅支持安装了IoT Agent/AgentLite的网关设备),实现对设备的控制,支持给本应用的设备下发命令。

接口描述

1
InvokeDeviceServiceOutDTO invokeDeviceService(String deviceId, String serviceId, CommandDTO2 commandDTO, String appId, String accessToken) throws NorthApiException

参数说明

参数

必选/可选

类型

位置

描述

deviceId

必选

String(1-64)

path

设备ID,用于唯一标识一个设备。

serviceId

必选

String(1-64)

path

服务ID,唯一标识一个服务。

commandDTO

必选

CommandDTO2

body

见下表CommandDTO2的描述。

appId

必选

String

query

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

accessToken

必选

String

header

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

CommandDTO2

参数

必选/可选

类型

位置

描述

header

必选

CommandNA2CloudHeader

body

具体参见CommandNA2CloudHeader结构体。

body

可选

Object

body

消息的消息体。JsonObject里面是一个个健值对。每个健都是profile中命令的参数名(paraName)。

CommandNA2CloudHeader结构体说明:

参数

必选/可选

类型

位置

描述

requestId

可选

String(0-128)

body

用于标识一个命令,不能重复。

mode

必选

Enum

body

是否要确认消息。

  • NOACK:不需要确认消息
  • ACK:需要确认消息
  • 其它值无效

from

可选

String(128)

body

表示消息发布者的地址。

  • App发起的请求:/users/{userId}
  • 第三方应用发起的请求:/{serviceName}
  • 物联网平台发起的请求:/cloud/{serviceName}

toType

可选

Enum

body

消息接受者的类型,CLOUD/GATEWAY。

to

可选

String(128)

body

消息接收者的地址。

method

必选

String(1-32)

body

命令名称,如:“DISCOVERY”为发现非直连设备,“REMOVE”为删除非直连设备。

callbackURL

可选

String(1024)

body

命令的回调路径。

响应参数

InvokeDeviceServiceOutDTO

参数

类型

描述

status

String(128)

命令状态。

  • sent:已发送
  • deliveried:已投递,toType为CLOUD的请求才有该返回值
  • failed:失败,toType为CLOUD的请求才有该返回值

timestamp

String(128)

发送命令的时间戳,时间格式:yyyyMMdd'T'HHmmss'Z', 如20151212T121212Z。

requestId

String(128)

设备命令ID。

  • toType为GATEWAY时,如果请求有requestId则同请求的requestId一致,如果请求无requestId则平台分配一个序列号。
  • toType为CLOUD时,则为空。

错误码

Http状态码

错误码

错误描述

说明

200

100203

The application is not existed.

应用不存在。

处理建议:

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

200

100217

The application hasn't been authorized.

应用未被授权。

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

200

100418

The deviceData is not existed.

设备信息不存在。

处理建议:

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

200

100428

The device is not online.

设备不在线。

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

200

100432

The device command is muted.

设备命令已被禁用。

处理建议:请检查接口请求参数method中的命令是否有误。

400

100022

The input is invalid.

输入参数无效。

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

400

102203

CommandName is invalid.

命令名称无效。

处理建议:请检查接口请求参数method中携带的命令是否有误。

403

100450

The gateway is not online.

网关不在线。

处理建议:请检查网关与物联网平台的连接是否正常。

403

1010009

app throttle exceed.

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

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

403

1010005

App_key or access_token is invalid.

错误的token信息。

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

404

100444

The serviceType is not exist.

服务类型不存在。

处理建议:请检查接口请求参数toType中的服务类型是否有误。

500

100001

Internal server error.

服务内部处理错误。

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

500

100023

The data in dataBase is abnomal.

数据库异常。

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

500

50252

Internal server error.

服务内部处理错误。

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

503

100501

Congestion occurs, and the current network has been flow-controlled

发生拥塞,当前的网络已经被流控。