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

查询指定批量任务信息

典型场景

应用服务器通过“创建批量任务”接口创建了设备的批量操作任务后,可调用此接口查询该批量任务的信息,包括任务的当前状态、子任务(指批量任务中一个设备执行的任务)完成情况等。

接口功能

支持应用服务器通过任务ID查询单个批量任务的信息。

接口原型

请求方法

GET

请求地址

https://server:port/iocm/app/batchtask/v1.1.0/tasks/{taskId}?appId={appId}&select={select}

传输协议

HTTPS

请求参数

参数

必选/可选

类型

位置

描述

app_key

必选

String

header

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

Authorization

必选

String

header

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

taskId

必选

String

path

批量任务ID,创建批量任务后获得。

appId

可选

String

query

访问物联网平台的应用ID,在物联网平台创建应用时由平台分配获得。此处填写授权应用的appId。

select

可选

String

query

指定可选的返回值,可取值:tag。

响应参数

Status Code: 200 OK

参数

类型

描述

appId

String

批量任务所归属的appId。

taskId

String

批量任务ID。

taskName

String

批量任务名称。

operator

String

下发该批量任务的操作员。

taskFrom

String

批量任务的来源。

  • Portal:通过SP Portal创建的。
  • Northbound:调用北向API接口创建的。

taskType

String

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

status

String

批量任务的状态,取值范围:Pending/Running/Complete/Timeout。

startTime

String

批量任务的创建时间。

timeout

Integer

批量任务的超时时间,单位秒。

progress

Integer

批量任务的进度,单位:千分比,范围:0-1000,向下取整。

totalCnt

Integer

任务的总数。

successCnt

Integer

成功的任务数。

failCnt

Integer

失败的任务数。

timeoutCnt

Integer

超时的任务数。

expiredCnt

Integer

未执行的失效任务数。

completeCnt

Integer

完成的任务数,完成的任务数=成功的任务数+失败的任务数+超时的任务数。

successRate

Integer

任务成功率,单位:千分比,范围:0-1000,向下取整。

param

ObjectNode

不同任务类型的具体参数。

tags

List<TagDTO2>

批量任务的标签列表。

ObjectNode:

参数

类型

描述

type

String

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

deviceList

List<String>

设备ID列表,type为DeviceList时返回值。

deviceType

String

设备类型,type为DeviceType时返回值,其值应当与profile中定义的一致。

manufacturerId

String

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

model

String

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

deviceLocation

String

设备位置,type为DeviceArea时返回值。

groupList

List<String>

群组名称列表,type为GroupList时返回值。

command

CommandDTO

命令信息。

callbackUrl

String

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

maxRetransmit

Integer(0~3)

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

groupTag

String

群组标签。

CommandDTO:

参数

类型

描述

serviceId

String(1-64)

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

method

String(1-128)

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

paras

ObjectNode

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

TagDTO2:

参数

类型

描述

tagName

String(1-128)

标签名称。

tagValue

String(1-1024)

标签值。

请求示例

Method: GET
request:
https://server:port/iocm/app/batchtask/v1.1.0/tasks/******?appId=******
Header:
app_key: ******
Authorization: Bearer ******
Content-Type: application/json;

响应示例

response:
Status Code: 200 OK
Content-Type: application/json
Body:
{
  "taskId": "********",
  "taskName": "********",
  "appId": "********",
  "operator": "********",
  "taskFrom": "********",
  "taskType": "********",
  "status": "********",
  "startTime": "********",
  "timeout": 1000,
  "progress": 100,
  "totalCnt": 100,
  "successCnt": 70,
  "failCnt": 10,
  "timeoutCnt": 10,
  "expiredCnt": 10,
  "completeCnt": 100,
  "successRate": 70,
  "param": {
    "fileId": "******"
  }
}

错误码

Http状态码

错误码

错误描述

说明

400

100019

Illegal request.

非法请求。

处理建议:请检查接口请求中的必须参数是否为空。

400

100022

The input is invalid

输入参数无效。

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

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

105005

The batchTask is not existed.

批量任务不存在。

处理建议:请检查接口请求中的taskId是否有误。

500

100203

The application is not existed.

应用不存在。

处理建议:

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