Querying Details of a Batch Task
Typical Scenario
After creating a batch task for devices, an application 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 application 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.
|
| 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 | Indicates the task parameter, which varies depending on the value of taskType. | |
| tags | List<TagDTO2> | Indicates the tag list of the batch task. |
| 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 product model. |
| 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 product model. |
| 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 product model. |
| 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 | 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. |
| 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 product model. |
| 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 product model. |
| 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 product model. The specific format depends on the application and device. |
| 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 | Invalid request. | Invalid request. Recommended handling: Check whether the mandatory parameters in the request are set. |
| 400 | 100022 | An input parameter is invalid. | An input parameter is invalid. Recommended handling: Check whether parameters carried in the API call request are valid. |
| 403 | 100203 | The application does not exist. | The application does not exist. Recommended handling:
|
| 403 | 100217 | The application has not 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 | The application calls the API at a frequency that exceeds the flow control threshold. | The application 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 | Invalid access token or application ID. | The access token is invalid. Recommended handling: Check whether accessToken carried in the API request is correct. |
| 404 | 105005 | The batch task does not exist. | The batch task does not exist. Recommended handling: Check whether taskId carried in the API request is correct. |
| 500 | 100203 | The application does not exist. | The application does not exist. Recommended handling:
|
Last Article: Creating a Batch Task
Next Article: Querying Details of a Subtask of a Batch Task
Did this article solve your problem?
Thank you for your score！Your feedback would help us improve the website.