Help Center> IoT> API Reference> Northbound PHP SDK API Reference> Service API List> Batch Processing> Querying Information About a Specified Batch Task
Updated at: 2022-02-24 GMT+08:00

Querying Information About a Specified 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
public function queryOneTask($taskId, $select, $appId, $accessToken)

Class

BatchProcess

Parameter Description

Parameter

Mandatory or Optional

Location

Description

$taskId

Mandatory

path

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

$select

Mandatory

query

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

$appId

Mandatory

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

header

This parameter is set to the value of the access token obtained by calling the Authentication API.

Return Value

QueryOneTaskOutDTO

Parameter

Description

$taskId

Identifies a batch task.

$taskName

Indicates the name of the batch task.

$appId

Indicates the appId to which the batch task belongs.

$operator

Indicates the operator who delivers the batch task.

$taskFrom

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

Indicates the type of the batch task. The value options are DeviceReg and DeviceCmd.

$status

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

$startTime

Indicates the time when the batch task is created.

$timeout

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

$progress

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

$totalCnt

Indicates the total number of tasks.

$successCnt

Indicates the number of tasks that are successfully executed.

$failCnt

Indicates the number of tasks that fail to be executed.

$timeoutCnt

Indicates the number of tasks with execution timeout.

$expiredCnt

Indicates the number of expired tasks that are not executed.

$completeCnt

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

$successRate

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

$param

Indicates the parameters of different types of tasks. For details, see DeviceCmd structure.

$tags

Indicates the tag list in the batch task. For details, see TagDTO2 structure.

DeviceCmd structure

Parameter

Description

type

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

deviceList

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

deviceType

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

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

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

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

groupList

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

command

Indicates the command information. . For details, see CommandDTO.

callbackUrl

Indicates the push address of the command execution result..

maxRetransmit

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

groupTag

Indicates the group tag.

CommandDTO:

Parameter

Description

serviceId

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

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

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

Description

$tagName

Indicates the tag name.

$tagValue

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.
close