创建批量任务
典型场景
应用服务器若需要对多个设备进行批量操作时，可调用此接口创建设备的批量操作任务，当前仅支持给批量设备下发缓存命令。
接口功能
支持应用服务器在物联网平台创建设备的批量操作任务。
接口原型
|
请求方法 |
POST |
|---|---|
|
请求地址 |
https://server:port/iocm/app/batchtask/v1.1.0/tasks |
|
传输协议 |
HTTPS |
请求参数
|
参数 |
必选/可选 |
类型 |
位置 |
描述 |
|---|---|---|---|---|
|
app_key |
必选 |
String |
header |
访问物联网平台的应用ID，在物联网平台创建应用时由平台分配获得。 |
|
Authorization |
必选 |
String |
header |
访问物联网平台的认证信息，值为“Bearer {accessToken}”，其中{accessToken}为调用鉴权接口返回的accessToken。 |
|
appId |
必选 |
String(64) |
body |
访问物联网平台的应用ID，在物联网平台创建应用时由平台分配获得。此处填写授权应用的appId。 |
|
param |
必选 |
body |
任务详细参数，根据taskType任务类型的不同对应不同类型参数。 |
|
|
taskName |
必选 |
String |
body |
任务名称，最大长度256字符。 |
|
taskType |
必选 |
String |
body |
任务类型，取值范围：DeviceCmd。 |
|
timeout |
必选 |
Integer |
body |
任务超时时长，单位分钟，范围为10到2880。 |
|
tags |
可选 |
List<TagDTO2> |
body |
标签列表。 |
|
参数 |
必选/可选 |
类型 |
位置 |
描述 |
|---|---|---|---|---|
|
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 |
必选 |
body |
命令信息。 |
|
|
callbackUrl |
可选 |
String |
body |
命令执行结果的推送地址。 |
|
maxRetransmit |
可选 |
Integer(0~3) |
body |
命令下发最大重传次数，取值范围：0-3。 |
|
groupTag |
可选 |
String |
body |
群组标签。 |
|
参数 |
必选/可选 |
类型 |
位置 |
描述 |
|---|---|---|---|---|
|
serviceId |
必选 |
String(1-64) |
body |
命令对应的服务ID，要与profile中定义的serviceId保持一致。 |
|
method |
必选 |
String(1-128) |
body |
服务下具体的命令名称，要与profile中定义的命令名保持一致。 |
|
paras |
可选 |
ObjectNode |
body |
命令参数，jsonString格式，里面是一个个健值对，每个健都是profile中命令的参数名（paraName），具体格式需要应用和设备约定。 |
|
参数 |
必选/可选 |
类型 |
位置 |
描述 |
|---|---|---|---|---|
|
tagName |
必选 |
String(1-128) |
body |
标签名称。 |
|
tagValue |
必选 |
String(1-1024) |
body |
标签值。 |
响应参数
Status Code: 200 OK
|
参数 |
类型 |
描述 |
|---|---|---|
|
taskID |
String |
批量任务的ID。 |
请求示例
Method: POST
request:
https://server:port/iocm/app/batchtask/v1.1.0/tasks
Header:
app_key: ******
Authorization: Bearer ******
Content-Type: application/json
Body:
{
"appId": "******",
"timeout": 1000,
"taskName": "******",
"taskType": "DeviceCmd",
"param": {
"type": "******",
"deviceList": [
"********",
"********",
"********"
],
"command": {
"serviceId": "********",
"method": "********",
"paras": {
"paraName1": "paraValue1",
"paraName2": "paraValue2"
}
}
}
}
响应示例
response:
Status Code: 200 OK
Content-Type: application/json
Body:
{
"taskID": "******"
}
错误码
|
Http状态码 |
错误码 |
错误描述 |
说明 |
|---|---|---|---|
|
200 |
100203 |
The application is not existed. |
应用不存在。 处理建议：
|
|
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. |
应用不存在。 处理建议：
|
|
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. |
应用不存在。 处理建议：
|
|
500 |
50252 |
Internal server error. |
服务器运行内部错误。 处理建议：物联网平台内部错误，请联系物联网平台维护人员处理。 |
