设备服务调用
典型场景
设备Profile文件中定义了物联网平台可向设备下发的命令，应用服务器可调用此接口向设备下发命令，配置或修改设备的服务属性，以实现对设备的控制。
物联网平台不对设备命令进行缓存而是直接下发命令，设备不在线时命令下发失败。下发命令的具体格式需要应用服务器与设备自定义，物联网平台在接口中直接进行封装，透传。
此接口适用于使用MQTT协议接入的设备，例如集成了AgentLite SDK的设备。
接口功能
支持应用服务器向设备立即下发命令，实现对设备的控制。
接口原型
请求方法 |
POST |
|---|---|
请求地址 |
https://server:port/iocm/app/signaltrans/v1.1.0/devices/{deviceId}/services/{serviceId}/sendCommand?appId={appId} |
传输协议 |
HTTPS |
请求参数
参数 |
必选/可选 |
类型 |
位置 |
描述 |
|---|---|---|---|---|
app_key |
必选 |
String |
header |
访问物联网平台的应用ID，在物联网平台创建应用时由平台分配获得。 |
Authorization |
必选 |
String |
header |
访问物联网平台的认证信息，值为“Bearer {accessToken}”，其中{accessToken}为调用鉴权接口返回的accessToken。 |
deviceId |
必选 |
String(1-64) |
path |
设备ID，用于唯一标识一个设备，在注册设备时由物联网平台分配获得。 |
serviceId |
必选 |
String(1-64) |
path |
命令对应的服务ID，用于标识一个服务。要与profile中定义的serviceId保持一致。 |
appId |
可选 |
String |
query |
访问物联网平台的应用ID，在物联网平台创建应用时由平台分配获得。此处填写授权应用的appId。 |
header |
必选 |
body |
消息的消息头。 |
|
body |
可选 |
ObjectNode |
body |
消息的消息体。JsonObject里面是一个个健值对。每个健都是profile中命令的参数名（paraName）。 |
参数 |
必选/可选 |
类型 |
位置 |
描述 |
|---|---|---|---|---|
requestId |
可选 |
String(0-128) |
body |
用于标识一个命令，不能重复。 |
mode |
必选 |
Enum |
body |
是否要确认消息，默认为ACK模式。
|
from |
可选 |
String(128) |
body |
表示消息发布者的地址。
|
toType |
可选 |
Enum |
body |
消息接收者的类型，默认为GATEWAY。 |
to |
可选 |
String(128) |
body |
消息接收者的地址。 |
method |
必选 |
String(1-32) |
body |
命令名称，要与profile中定义的命令名保持一致。 |
callbackURL |
可选 |
String(1024) |
body |
命令状态变化通知地址，当命令状态变化时（执行失败，执行成功，超时，发送，已送达）会通知应用服务器。 |
响应参数
Status Code: 202 Accepted
参数 |
类型 |
描述 |
|---|---|---|
status |
String(128) |
命令状态。
|
timestamp |
String(128) |
发送命令的时间戳，时间格式：yyyyMMdd'T'HHmmss'Z'， 如20151212T121212Z。 |
requestId |
String(128) |
设备命令ID。如果请求有requestId则同请求的requestId一致，如果请求无requestId则平台分配一个序列号。 |
请求示例
Method: POST
request:
https://server:port/iocm/app/signaltrans/v1.1.0/devices/{deviceId}/services/{serviceId}/sendCommand
Header:
app_key: ******
Authorization: Bearer ******
Content-Type: application/json
Body:
{
"header": {
"mode": "ACK",
"from": "/users/23212121",
"method": "INVITE-INIT",
"callbackURL": "http://10.10.10.10:8043/na/iocm/message/confirm"
},
"body": {
"from": "************",
"sessionID": "**********",
"sdp": "**********"
}
}
响应示例
response:
Status Code: 202 Accepted
Content-Type: application/json
Body:
{
"requestId": "************",
"status": "sent",
"timestamp": "**********"
}
错误码
Http状态码 |
错误码 |
错误描述 |
说明 |
|---|---|---|---|
200 |
100203 |
The application is not existed. |
应用不存在。 处理建议：
|
200 |
100217 |
The application hasn't been authorized. |
应用未被授权。 处理建议：若非应用授权场景，请确认请求参数中的appId为空。 |
200 |
100418 |
The deviceData is not existed. |
设备信息不存在。 处理建议：
|
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 |
发生拥塞，当前的网络已经被流控。 |
