设备服务调用

典型场景

设备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时，则为空。

参数

类型

描述

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	发生拥塞，当前的网络已经被流控。