Creating a Device Command Revocation Task
Typical Scenario
After an application delivers commands to a device, the platform does not deliver the commands to the device for execution (the commands are in the DEFAULT state) if the commands are in queue or the device is offline. In this case, the application can call this API to revoke all the undelivered commands of a specified device. Commands that have been delivered cannot be revoked.
API Function
This API is used by an application to create a command revocation task to revoke all undelivered commands (commands in the DEFAULT state) with the specified device ID on the platform.
API Description
1 | CreateDeviceCmdCancelTaskOutDTO createDeviceCmdCancelTask(CreateDeviceCmdCancelTaskInDTO cdcctInDTO, String appId, String accessToken) throws NorthApiException
|
Parameter Description
| Parameter | Mandatory or Optional | Type | Location | Description |
|---|---|---|---|---|
| cdcctInDTO | Mandatory | CreateDeviceCmdCancelTaskInDTO structure | body | For details, see CreateDeviceCmdCancelTaskInDTO structure. |
| appId | Mandatory | String | query | If the command 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. |
CreateDeviceCmdCancelTaskInDTO structure
| Parameter | Mandatory or Optional | Type | Location | Description |
|---|---|---|---|---|
| deviceId | Mandatory | String(1-64) | body | Identifies the device whose commands are to be revoked. The revocation task will revoke all commands delivered to this device. |
Response Parameters
CreateDeviceCmdCancelTaskOutDTO structure
| Parameter | Type | Description |
|---|---|---|
| taskId | String(1-64) | Identifies a command revocation task. |
| appId | String(1-64) | Identifies the application to which the command revocation task belongs. |
| deviceId | String(1-64) | Identifies the device whose commands are to be revoked by the revocation task. |
| status | String | Indicates the status of the command revocation task.
|
| totalCount | Integer | Indicates the total number of revoked commands. |
| deviceCommands | List<DeviceCommandRespV4> | Indicates the revoked device command list. For details, see DeviceCommandRespV4 structure. |
| Parameter | Type | Description |
|---|---|---|
| commandId | String(1-64) | Identifies a device command. |
| appId | String(1-64) | Uniquely identifies an application. This parameter is used to identify an application that can call open APIs provided by the platform. |
| deviceId | String(1-64) | Uniquely identifies the device that delivers the command. |
| command | CommandDTOV4 | Indicates information about the delivered command. For details, see CommandDTOV4 structure. |
| callbackUrl | String(1024) | Indicates the URL for receiving command status change notifications. When the command status changes, such as execution failure, execution success, timeout, sending, or sent, the application is notified. |
| expireTime | Integer(>=0) | Indicates the command expiration time, in units of seconds. The command will not be delivered after the specified time elapses. The default validity period is 48 hours (86400 seconds x 2). |
| status | String | Indicates the status of the command.
|
| result | ObjectNode | Indicates the detailed command execution result. |
| creationTime | String(20) | Indicates the time when the command is created. |
| executeTime | String(20) | Indicates the time when the command is executed. |
| platformIssuedTime | String(20) | Indicates the time when the platform sends the command. |
| deliveredTime | String(20) | Indicates the time when the command is delivered. |
| issuedTimes | Integer(>=0) | Indicates the number of times the platform delivers the command. |
| maxRetransmit | Integer(0-3) | Indicates the maximum number of times the command can be retransmitted. |
| Parameter | Mandatory or Optional | Type | Description |
|---|---|---|---|
| serviceId | Mandatory | String(1-64) | Identifies the service corresponding to the command. |
| method | Mandatory | String(1-128) | Indicates the command name. |
| paras | Optional | Object | Indicates the command parameter, which is a JSON string. The specific format is negotiated by the application and device. |
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 | 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. |
| 200 | 100418 | The device data does not exist. | The device data does not exist. Recommended handling:
|
| 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. |
| 500 | 100001 | Internal server error. | An internal server error occurs. Recommended handling: An internal error occurs on the IoT platform. Contact IoT platform maintenance personnel. |
| 500 | 100220 | Failed to obtain the AppKey from the message header. | Failed to obtain the appKey. Recommended handling: Check whether appId is carried in the API request header. |
| 503 | 100501 | Congestion occurs, and the current network is under flow control. | Congestion occurs. The current network is under flow control. |
Last Article: Modifying a Device Command
Next Article: Querying a Command Revocation Task
Did this article solve your problem?
Thank you for your score！Your feedback would help us improve the website.