Creating a Batch Task
Typical Scenario
When an application needs to perform an operation on a batch of devices, the application can call this API to create a batch task. Currently, the supported batch operations include delivering pending commands to devices in batches.
API Function
This API is used by an application to create a batch task for devices on the platform.
API Description
1 | BatchTaskCreateOutDTO createBatchTask(BatchTaskCreateInDTO2 btcInDTO, String accessToken) throws NorthApiException
|
Class
BatchProcess
Parameter Description
| Parameter | Mandatory or Optional | Type | Location | Description |
|---|---|---|---|---|
| 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. |
| btcInDTO | Mandatory | BatchTaskCreateInDTO2 | body | For details, see BatchTaskCreateInDTO2 structure. |
BatchTaskCreateInDTO2 structure
| Parameter | Mandatory or Optional | Type | Location | Description |
|---|---|---|---|---|
| appId | Mandatory | String(64) | body | If the device belongs to the current application, set this parameter to null. Otherwise, set this parameter to the ID of the authorized application. |
| timeout | Mandatory | Integer | body | Indicates the timeout duration of a task, in minutes. The value range is 10–2880. |
| taskName | Mandatory | String | body | Indicates the task name. The value is a string of a maximum of 256 characters. |
| taskType | Mandatory | String | body | Indicates the task type. The value can be DeviceCmd. |
| param | Mandatory | ObjectNode | body | Indicates task parameters. The value of this parameter varies depending on the taskType. For details, see ObjectNode structure. |
| tags | Optional | List<TagDTO2> | body | Indicates the tag list. For details, see TagDTO2 structure. |
| Parameter | Mandatory or Optional | Type | Location | Description |
|---|---|---|---|---|
| type | mandatory | String | body | Indicates the batch command type. The options include DeviceList, DeviceType, DeviceArea, GroupList, Broadcast, and GroupIdList. |
| deviceList | Conditionally mandatory | List<String> | body | Indicates the device ID list. This parameter is mandatory when type is set to DeviceList. |
| deviceType | Conditionally mandatory | String | body | Indicates the device type. This parameter is mandatory when type is set to DeviceType. Set this parameter to the value defined in the product model. |
| manufacturerId | Conditionally optional | String | body | Identifies the manufacturer. This parameter is mandatory when type is set to DeviceType. Set this parameter to the value defined in the product model. |
| model | Conditionally optional | String | body | Indicates the device model. This parameter is mandatory when type is set to DeviceType. Set this parameter to the value defined in the product model. |
| deviceLocation | Conditionally mandatory | String | body | Indicates the location of the device. This parameter is mandatory when type is set to DeviceArea. |
| groupList | Conditionally mandatory | List<String> | body | Indicates the group ID list or device group name list. When type is set to GroupIdList, set this parameter to the group ID. When type is set to GroupList, set this parameter to the device group name. |
| command | mandatory | body | Indicates the command information. | |
| callbackUrl | optional | String | body | Indicates the push address of the command execution result. |
| maxRetransmit | optional | Integer(0~3) | body | Indicates the maximum number of retransmissions of a command. The value ranges from 0 to 3. |
| groupTag | optional | String | body | Indicates the group tag. |
| Parameter | Mandatory or Optional | Type | Location | Description |
|---|---|---|---|---|
| serviceId | Mandatory | String(1-64) | body | 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 | Mandatory | String(1-128) | body | 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 | Optional | ObjectNode | body | 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 | Mandatory or Optional | Type | Location | Description |
|---|---|---|---|---|
| tagName | Mandatory | String(1-128) | body | Indicates the tag name. |
| tagValue | Mandatory | String(1-1024) | body | Indicates the tag value. |
Return Value
BatchTaskCreateOutDTO
| Parameter | Type | Description |
|---|---|---|
| taskID | String | Identifies a batch task. |
Error Codes
| HTTP Status Code | Error Code | Error Description | Remarks |
|---|---|---|---|
| 200 | 100203 | The application does not exist. | The application does not exist. Recommended handling:
|
| 200 | 101001 | The resource does not exist. | The resource does not exist. |
| 200 | 105001 | The number of batch tasks has reached the upper limit. | If the number of unfinished tasks is greater than or equal to 1, a message is returned, indicating that the number of tasks reaches the limit. |
| 200 | 105002 | The batch task name exists. | The task name exists. Recommended handling: Change the task name. |
| 400 | 105201 | The tagName and tagValue have been used on the platform. | The tagName and tagValue have been used on the IoT platform. |
| 400 | 50400 | An input parameter is invalid. | An input parameter is invalid. Recommended handling: Check whether parameters carried in the API call request are valid. |
| 401 | 100028 | The user has no right. | The user has no operation permission. |
| 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 | 105202 | The tag does not exist. | The tag does not exist. |
| 500 | 100203 | The application does not exist. | The application does not exist. Recommended handling:
|
| 500 | 50252 | Internal server error. | An internal server error occurs. Recommended handling: An internal error occurs on the IoT platform. Contact IoT platform maintenance personnel. |
Last Article: Batch Processing
Next Article: Querying Details of a Batch Task
Did this article solve your problem?
Thank you for your score！Your feedback would help us improve the website.