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.