Updated on 2022-02-24 GMT+08:00

Querying Information About a Batch Task

Typical Scenario

After creating a batch task for devices, an NA can call this API to query information about the batch task, including the task status and the subtask completion status.

API Function

This API is used by an NA to query the information about a single batch task by task ID.

API Description

1
QueryOneTaskOutDTO queryOneTask(String taskId, String select, String appId, String accessToken) throws NorthApiException

Class

BatchProcess

Parameter Description

Parameter

Mandatory or Optional

Type

Location

Description

taskId

Mandatory

String

path

Identifies a batch task. The value of this parameter is obtained after the batch task is created.

select

Mandatory

String

query

Indicates an optional return value. The value can be tag. If this parameter is not specified, the value can be null.

appId

Mandatory

String

query

If the task belongs to the current application, set this parameter to null. Otherwise, set this parameter to the ID of the authorized application.

accessToken

Mandatory

String

header

If the Periodically Refreshing a Token API is called, set this parameter to null. Otherwise, set this parameter to the accessToken obtained by the Authentication API.

Return Value

QueryOneTaskOutDTO

Parameter

Type

Description

appId

String

Indicates the appId to which the batch task belongs.

taskId

String

Identifies a batch task.

taskName

String

Indicates the name of the batch task.

operator

String

Indicates the operator who delivers the batch task.

taskFrom

String

Indicates the source of the batch task.

  • Portal: The task is created on the SP portal.
  • Northbound: The task is created by calling a northbound API.

taskType

String

Indicates the type of the batch task. The value can be DeviceCmd.

status

String

Indicates the status of the batch task. The value options are Pending, Running, Complete, and Timeout.

startTime

String

Indicates the time when the batch task is created.

timeout

Integer

Indicates the time when the batch task times out, in seconds.

progress

Integer

Indicates the progress of the batch task. The value is a permillage ranging from 0 to 1000 and is rounded down.

totalCnt

Integer

Indicates the total number of tasks.

successCnt

Integer

Indicates the number of tasks that are successfully executed.

failCnt

Integer

Indicates the number of tasks that fail to be executed.

timeoutCnt

Integer

Indicates the number of tasks with execution timeout.

expiredCnt

Integer

Indicates the number of expired tasks that are not executed.

completeCnt

Integer

Indicates the number of completed tasks, including successful, failed, and timed out tasks.

successRate

Integer

Indicates the task success rate. The value is a permillage ranging from 0 to 1000 and is rounded down.

param

ObjectNode

Indicates the task parameter, which varies depending on the value of taskType.

tags

List<TagDTO2>

Indicates the tag list of the batch task.

ObjectNode structure:

Parameter

Type

Description

type

String

Indicates the batch command type. The options include DeviceList, DeviceType, DeviceArea, GroupList, Broadcast, and GroupIdList.

deviceList

List<String>

Indicates the device ID list. The value is that returned when type is set to DeviceList.

deviceType

String

Indicates the type of the device. The value is that returned when type is set to DeviceType. The value must be the same as that defined in the profile file.

manufacturerId

String

Identifies a manufacturer. The value is that returned when type is set to DeviceType. The value must be the same as that defined in the profile file.

model

String

Indicates the model of the device. The value is that returned when type is set to DeviceType. The value must be the same as that defined in the profile file.

deviceLocation

String

Indicates the location of the device. The value is that returned when type is set to DeviceArea.

groupList

List<String>

Indicates the group name list. The value is that returned when type is set to GroupList.

command

CommandDTO

Indicates the command information. .

callbackUrl

String

Indicates the push address of the command execution result..

maxRetransmit

Integer(0~3)

Indicates the maximum number of retransmissions of a command. The value ranges from 0 to 3.

groupTag

String

Indicates the group tag.

CommandDTO structure:

Parameter

Type

Description

serviceId

String(1-64)

Identifies the service corresponding to the command. The value of this parameter must be the same as the value of serviceId defined in the profile file.

method

String(1-128)

Indicates the name of a specific command under the service. The value of this parameter must be the same as the command name defined in the profile file.

paras

ObjectNode

Indicates a command parameter in the jsonString format. The value consists of key-value pairs. Each key is the paraName parameter in commands in the profile file. The specific format depends on the application and device.

TagDTO2 structure:

Parameter

Type

Description

tagName

String(1-128)

Indicates the tag name.

tagValue

String(1-1024)

Indicates the tag value.

Error Codes

HTTP Status Code

Error Code

Error Description

Remarks

400

100019

Illegal request.

Invalid request.

Recommended handling: Check whether the mandatory parameters in the request are set.

400

100022

The input is invalid

An input parameter is invalid.

Recommended handling: Check whether parameters carried in the API call request are valid.

403

100203

The application is not existed.

The application does not exist.

Recommended handling:

  • Check whether appId carried in the HTTP request header is correct.
  • Check whether appId in the request path (URL) is correct.

403

100217

The application hasn't been authorized

The application has not been authorized.

Recommended handling: In scenarios where applications are not authorized, ensure that request parameter appId is null.

403

1010009

app throttle exceed.

The NA calls the API at a frequency that exceeds the flow control threshold (100 calls per minute by default).

Recommended handling: Contact IoT platform maintenance personnel to adjust the flow control threshold or control the API call frequency.

403

1010005

App_key or access_token is invalid.

The access token is invalid.

Recommended handling: Check whether accessToken carried in the API request is correct.

404

105005

The batchTask is not existed.

The batch task does not exist.

Recommended handling: Check whether taskId carried in the API request is correct.

500

100203

The application is not existed.

The application does not exist.

Recommended handling:

  • Check whether appId carried in the HTTP request header is correct.
  • Check whether appId in the request path (URL) is correct.