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 | def createBatchTask(self, btcInDTO, accessToken)
|
Class
BatchProcess
Parameter Description
| Parameter | Mandatory or Optional | Type | Location | Description |
|---|---|---|---|---|
| btcInDTO | Mandatory | BatchTaskCreateInDTO | body | For details, see BatchTaskCreateInDTO structure. |
| accessToken | Mandatory | String | header | This parameter is set to the value of the accessToken obtained by calling the Authentication API. |
BatchTaskCreateInDTO structure
| Parameter | Mandatory or Optional | Type | Location | Description |
|---|---|---|---|---|
| appId | Mandatory | String(64) | body | If the task belongs to the current application, set this parameter to None. Otherwise, set this parameter to the ID of the authorized application. |
| param | Mandatory | body | Indicates the task parameter, which varies depending on the value of taskType. | |
| 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 values include DeviceCmd. |
| timeout | Mandatory | Integer | body | Indicates the timeout duration of a task, in minutes. The value range is 10–2880. |
| tags | Optional | List<TagDTO2> | body | Indicates the tag list. |
| 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 structure
| 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.