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

创建批量任务

典型场景

第三方应用若需要对多个设备进行批量操作时,可调用此接口创建设备的批量操作任务,当前仅支持给批量设备下发缓存命令。

接口功能

支持第三方应用在物联网平台创建设备的批量操作任务。

接口描述

1
BatchTaskCreateOutDTO createBatchTask(BatchTaskCreateInDTO2 btcInDTO, String accessToken) throws NorthApiException

接口所属类

BatchProcess

参数说明

参数

必选/可选

类型

位置

描述

accessToken

必选

String

header

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

btcInDTO

必选

BatchTaskCreateInDTO2

body

详细参见BatchTaskCreateInDTO2结构体的描述。

BatchTaskCreateInDTO2结构体:

参数

必选/可选

类型

位置

描述

appId

必选

String(64)

body

第三方应用的身份标识,用于唯一标识一个应用。开发者可通过该标识来指定哪个应用来调用物联网平台的开放API。appid在物联网平台的SP Portal上创建应用时获得。

timeout

必选

Integer

body

任务超时时长,单位分钟,范围为10到2880。

taskName

必选

String

body

任务名称,最大长度256字符。

taskType

必选

String

body

任务类型,DeviceCmd。

param

必选

ObjectNode

body

任务详细参数,根据taskType任务类型的不同对应不同类型参数,具体参见ObjectNode结构体

tags

可选

List<TagDTO2>

body

标签列表,请参见TagDTO2结构体

ObjectNode:

参数

必选/可选

类型

位置

描述

type

必选

String

body

批量命令类型,取值范围: DeviceList/DeviceType/DeviceArea/GroupList/Broadcast/GroupIdList。

deviceList

条件必选

List<String>

body

设备ID列表,type为DeviceList时需要填写。

deviceType

条件必选

String

body

设备类型,type为DeviceType时需要填写,其值应当与profile中定义的一致。

manufacturerId

条件可选

String

body

厂商ID,type为DeviceType时可填写,其值应当与profile中定义的一致。

model

条件可选

String

body

设备型号,type为DeviceType时可填写,其值应当与profile中定义的一致。

deviceLocation

条件必选

String

body

设备位置,type为DeviceArea时需要填写。

groupList

条件必选

List<String>

body

群组Id列表或设备组名称列表,type为GroupIdList时需要填写群组Id,type为GroupList时需要填写设备组名称。

command

必选

CommandDTO

body

命令信息。

callbackUrl

可选

String

body

命令执行结果的推送地址。

maxRetransmit

可选

Integer(0~3)

body

命令下发最大重传次数,取值范围:0-3。

groupTag

可选

String

body

群组标签。

CommandDTO:

参数

必选/可选

类型

位置

描述

serviceId

必选

String(1-64)

body

命令对应的服务ID,要与profile中定义的serviceId保持一致。

method

必选

String(1-128)

body

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

paras

可选

ObjectNode

body

命令参数,jsonString格式,里面是一个个健值对,每个健都是profile中命令的参数名(paraName),具体格式需要应用和设备约定。

TagDTO2结构体说明:

参数

必选/可选

类型

位置

描述

tagName

必选

String(1-128)

body

标签名称。

tagValue

必选

String(1-1024)

body

标签值。

返回值

BatchTaskCreateOutDTO

参数

类型

描述

taskID

String

批量任务的ID。

错误码

Http状态码

错误码

错误描述

说明

200

100203

The application is not existed.

应用不存在。

处理建议:

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

200

101001

Resource doesn't exist.

资源不存在。

200

105001

The batchTask count has reached the limit.

未完成的任务数大于等于10个时,返回任务达到数量限制。

200

105002

The batchTask name has exist.

任务名字已存在。

处理建议:修改任务名称。

400

105201

The tagName and tagValue has been used on the platform.

平台已使用tagName和tagValue 。

400

50400

The input is invalid.

输入参数无效。

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

401

100028

The user has no right.

用户没有操作权限。

403

100203

The application is not existed.

应用不存在。

处理建议:

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

403

100217

The application hasn't been authorized.

应用未被授权。

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

403

1010009

app throttle exceed.

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

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

403

1010005

App_key or access_token is invalid.

错误的token信息。

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

404

105202

The tag is not existed.

标签不存在。

500

100203

The application is not existed.

应用不存在。

处理建议:

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

500

50252

Internal server error.

服务器运行内部错误。

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