Help Center> IoT Device Access> API Reference> 历史API> 应用侧API参考> 命令下发> 创建设备命令
View PDF

创建设备命令

接口说明

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

物联网平台有两种命令下发机制：

  • 立即下发：平台收到命令后立即下发给设备，保证实时性，不保证串行性。
  • 缓存下发：平台收到命令后缓存起来，在设备可达时排队串行下发，平台收到前一个命令的响应（模组自动回复的ACK）才会下发后一个命令，保证串行性，不保证实时性。

此接口适用于使用LWM2M/CoAP协议接入的设备，例如NB-IoT设备。

URI

请求方法

POST

URI

/iocm/app/cmd/v1.4.0/deviceCommands

传输协议

HTTPS

请求参数

参数

必选/可选

类型

位置

描述

app_key

必选

String

header

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

Authorization

必选

String

header

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

appId

可选

String(1-64)

query

命令所属的应用ID，当创建授权应用下的命令时才需要填写。

deviceId

必选

String(64)

body

下发命令的设备ID，用于唯一标识一个设备，在注册设备时由物联网平台分配获得。

command

必选

CommandDTO

body

下发命令的信息。

callbackUrl

可选

String(1024)

body

命令状态变化通知地址，当命令状态变化时（执行失败，执行成功，超时，发送，已送达）会通知应用服务器。

expireTime

可选

Integer(>=0)

body

下发命令的有效时间，单位为秒，表示设备命令在创建后expireTime秒内有效，超过这个时间范围后命令将不再下发，如果未设置则默认为48小时（86400s*2）。

如果expireTime设置为0，则无论物联网平台上设置的命令下发模式是什么，该命令都会立即下发给设备（如果设备处于休眠状态或者链路已老化，则设备收不到命令，平台没收到设备的响应，该命令最终会超时）。

如果expireTime不为0，则在expireTime时间内命令缓存在平台（PENDING状态），仅当设备上线或向平台上报数据时，命令会下发给设备。

maxRetransmit

可选

Integer(0~3)

body

命令下发最大重传次数。

CommandDTO：

参数

必选/可选

类型

位置

描述

serviceId

必选

String(1-64)

body

命令对应的服务ID，用于标识一个服务。要与profile中定义的serviceId保持一致。

method

必选

String(1-128)

body

命令服务下具体的命令名称，要与profile中定义的命令名保持一致。

paras

必选

ObjectNode

body

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

响应参数

StatusCode: 201 Created

参数

类型

描述

commandId

String(1-64)

设备命令ID，用于唯一标识一条命令，在下发设备命令时由物联网平台分配获得。

appId

String(1-64)

设备命令所属应用ID。

deviceId

String(1-64)

下发命令的设备ID，用于唯一标识一个设备，在注册设备时由物联网平台分配获得。

command

CommandDTO

下发命令的信息。

callbackUrl

String(1024)

命令状态变化通知地址，当命令状态变化时（执行失败，执行成功，超时，发送，已送达）会通知应用服务器。

expireTime

Integer(>=0)

下发命令的超时时间，单位为秒，表示设备命令在创建后expireTime秒内有效，超过这个时间范围后命令将不再下发，如果未设置则默认为48小时（86400s*2）。

status

String

下发命令的状态。

  • PENDING表示缓存未下发
  • EXPIRED表示命令已经过期
  • SUCCESSFUL表示命令已经成功执行
  • FAILED表示命令执行失败
  • TIMEOUT表示命令下发执行超时
  • CANCELED表示命令已经被撤销执行
  • DELIVERED表示命令已送达设备
  • SENT表示命令正在下发

creationTime

String(20)

命令创建的UTC时间，时间格式：yyyyMMdd'T'HHmmss'Z'，如20151212T121212Z。

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

executeTime

String(20)

命令执行的UTC时间，时间格式：yyyyMMdd'T'HHmmss'Z'，如20151212T121212Z。

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

platformIssuedTime

String(20)

平台发送命令的UTC时间，时间格式：yyyyMMdd'T'HHmmss'Z'，如20151212T121212Z。

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

deliveredTime

String(20)

平台将命令送达到设备的UTC时间，时间格式：yyyyMMdd'T'HHmmss'Z'，如20151212T121212Z。

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

issuedTimes

Integer(>=0)

平台发送命令的次数。

maxRetransmit

Integer(0~3)

命令下发最大重传次数。

请求示例

POST https://{host}:{port}/iocm/app/cmd/v1.4.0/deviceCommands
Content-Type: application/json
app_key: ******
Authorization: Bearer ******

{
  "deviceId": "********",
  "command": {
    "serviceId": "********",
    "method": "********",
    "paras": {
      "LED": "ON",
      "COLOR": "YELLOW"
    }
  },
  "callbackUrl": "http://127.0.0.1:9999/cmd/callbackUrl",
  "maxRetransmit": ******

}

正常响应示例

Status Code: 201 Created
Content-Type: application/json

{
  "commandId": "********",
  "appId": "********",
  "deviceId": "********",
  "command": {
    "serviceId": "********",
    "method": "********",
    "paras": {
      "paraName1": "paraValue1",
      "paraName2": "paraValue2"
    }
  },
  "callbackUrl": "http://127.0.0.1:9999/cmd/callbackUrl",
  "expireTime": null,
  "status": "PENDDING",
 
  "creationTime": "20170222T164000Z",
  "executeTime": null,
  "platformIssuedTime": null,
  "deliveredTime": null,
  "issuedTimes": null,
  "maxRetransmit": ******
}

错误码

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

100431

The serviceType is not exist.

服务类型不存在。

处理建议：

  • 请检查该设备的Profile文件是否已上传到物联网平台。
  • 请检查请求参数是否正确，或者serviceId在Profile文件中是否存在。

400

100022

The input is invalid.

输入参数无效。

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

400

100223

Command counts has reached the upLimit.

缓存的命令数已到达限制。处于PENDING状态的命令条数不超过限定值。默认限定值为20。

处理建议：如当前平台缓存的命令还需执行，请让设备上报数据触发缓存命令的下发；如当前平台缓存的命令有不需要执行的命令，请调用“修改设备命令V4”接口，将命令的状态从PENDING修改未CANCELED。

403

100217

The application hasn't been authorized.

应用未被授权。

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

403

100612

Device is zombie.

设备为僵尸设备。（距离设备上次上线时间超过阈值，默认7天）

处理建议：请把设备上线后再重新下发命令。

403

1010009

app throttle exceed.

应用调用接口过于频繁，超过流控值（默认值是100次/60s）。

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

403

1010005

Invalid access token or appId.

错误的token信息。

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

500

100001

Internal server error.

服务内部处理错误。

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

500

100023

The data in dataBase is abnomal.

数据库异常。

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

500

100220

Get AppKey from header failed.

获取appKey失败。

处理建议 : 请检查接口请求的header中是否携带appId。

500

101016

Get iotws address failed.

获取iotws地址失败。

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

500

101017

Get newCallbackUrl from oss failed.

从oss获取新的回调地址失败。

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

503

100501

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

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

处理建议：请稍后重新再尝试下发命令。
父主题： 命令下发