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

设备命令下发

接口说明

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

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

此接口适用于使用MQTT协议接入的设备,例如集成了AgentLite SDK的设备。

URI

请求方法

POST

URI

/iocm/app/signaltrans/v1.1.0/devices/{deviceId}/services/{serviceId}/sendCommand

传输协议

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,当创建授权应用下的命令时才需要填写。

header

必选

CommandNA2CloudHeader

body

消息的消息头。

body

可选

ObjectNode

body

消息的消息体,jsonString格式,里面是一个个健值对(key: value),“key”是产品模型中命令参数的参数名(paraName),“value”是该命令参数要设置的值,根据产品模型中命令参数的取值范围自定义设置。

CommandNA2CloudHeader:

参数

必选/可选

类型

位置

描述

requestId

可选

String(0-128)

body

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

mode

必选

Enum

body

是否要确认消息,默认为ACK模式。

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

from

可选

String(128)

body

表示消息发布者的地址。

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

toType

可选

Enum

body

消息接收者的类型,默认为GATEWAY。

to

可选

String(128)

body

消息接收者的地址。

method

必选

String(1-32)

body

命令名称,要与profile中定义的命令名保持一致。

响应参数

Status Code: 202 Accepted

参数

类型

描述

status

String(128)

命令状态。

  • sent:已发送
  • delivered:已投递
  • failed:失败

timestamp

String(128)

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

若需要显示本地时区时间,您需要自己进行时间转换。

requestId

String(128)

设备命令ID。如果请求有requestId则同请求的requestId一致,如果请求无requestId则平台分配一个序列号。

请求示例

POST https://{host}:{port}/iocm/app/signaltrans/v1.1.0/devices/{deviceId}/services/{serviceId}/sendCommand
Content-Type: application/json
app_key: ******
Authorization: Bearer ******

{
  "header": {
    "mode": "ACK",
    "from": "/users/23212121",
    "method": "INVITE-INIT"
  },
  "body": {
    "from": "************",
    "sessionID": "**********",
    "sdp": "**********"
  }
}

正常响应示例

Status Code: 202 Accepted
Content-Type: application/json

{
  "requestId": "************",
  "status": "sent",
  "timestamp": "**********"
}

错误码

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

Invalid access token or appId.

错误的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

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

相关文档