Help Center> IoT Device Access> API Reference> 历史API> 应用侧API参考> 批量处理> 创建批量任务
View PDF

创建批量任务

接口说明

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

URI

请求方法

POST

URI

/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，当创建授权应用下的批量任务时才需要填写。

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。

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。

请求示例

POST https://{host}:{port}/iocm/app/batchtask/v1.1.0/tasks
Content-Type: application/json
app_key: ******
Authorization: Bearer ******

{
  "appId": "******",
  "timeout": 1000,
  "taskName": "******",
  "taskType": "DeviceCmd",
  "param": {
    "type": "******",
    "deviceList": [
      "********",
      "********",
      "********"
    ],
    "command": {
      "serviceId": "********",
      "method": "********",
      "paras": {
        "paraName1": "paraValue1",
        "paraName2": "paraValue2"
      }
    }

  }
}

正常响应示例

Status Code: 200 OK
Content-Type: application/json

{
  "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.

单个用户未完成的批量任务数大于等于1个时，返回任务达到数量限制。

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

Invalid access token or appId.

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

服务器运行内部错误。

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