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

创建批量任务

典型场景

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

接口功能

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

接口原型

请求方法

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

必选

ObjectNode

body

任务详细参数,根据taskType任务类型的不同对应不同类型参数。

taskName

必选

String

body

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

taskType

必选

String

body

任务类型,取值范围:DeviceCmd。

timeout

必选

Integer

body

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

tags

可选

List<TagDTO2>

body

标签列表。

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

标签值。

响应参数

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.

应用不存在。

处理建议:

  • 请检查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.

服务器运行内部错误。

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