Modifying a Device Command
Typical Scenario
Applications can call this API to modify the status of commands that have not been canceled, expired, or executed. Currently, the status of such commands can only be changed to Canceled.
API Function
This API is used by applications to modify the status of commands. Currently, the status of commands can only be changed to Canceled.
API Description
1 | UpdateDeviceCommandOutDTO updateDeviceCommand(UpdateDeviceCommandInDTO udcInDTO, String deviceCommandId, String appId, String accessToken) throws NorthApiException
|
Parameter Description
| Parameter | Mandatory or Optional | Type | Location | Description |
|---|---|---|---|---|
| udcInDTO | Mandatory | UpdateDeviceCommandInDTO structure | body | For details, see UpdateDeviceCommandInDTO structure. |
| deviceCommandId | Mandatory | String | path | Identifies the command whose status is to be modified. The value of this parameter is obtained after the API used for creating device commands is called. |
| 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. |
UpdateDeviceCommandInDTO structure
| Parameter | Mandatory or Optional | Type | Description |
|---|---|---|---|
| status | Mandatory | String | Indicates the command execution result. The value can be CANCELED, which indicates that the command is revoked. |
Response Parameters
UpdateDeviceCommandOutDTO 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 seconds. The command will not be delivered after the specified time elapses. If this parameter is not specified, 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 | Location | Description |
|---|---|---|---|---|
| serviceId | Mandatory | String(1-64) | body | Identifies the service corresponding to the command. |
| method | Mandatory | String(1-128) | body | Indicates the command name. |
| paras | Optional | Object | body | 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:
|
| 200 | 100428 | The device is not online. | The device is not online. Recommended handling: Check whether the connection between the device and the IoT platform is normal. |
| 200 | 100431 | The service type does not exist. | The service type does not exist. Recommended handling:
|
| 200 | 100434 | The device command does not exist. | The device command does not exist. Recommended handling: Check whether the device command ID in the request is correct. |
| 200 | 100435 | The device command has been canceled, expired, or executed. It cannot be canceled. | The device command has been canceled, expired, or executed. It cannot be canceled. |
| 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 | 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 | 100023 | The data in the database is abnormal. | The database is abnormal. 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. |
| 500 | 101016 | Failed to obtain the IoTWS address. | Failed to obtain the IoTWS address. Recommended handling: An internal error occurs on the IoT platform. Contact IoT platform maintenance personnel. |
| 500 | 101017 | Failed to obtain a new callback URL from OSS. | Obtaining a new callback URL from the OSS fails. Recommended handling: An internal error occurs on the IoT platform. Contact IoT platform maintenance personnel. |
| 503 | 100501 | Congestion occurs, and the current network is under flow control. | Congestion occurs. The current network is under flow control. |
Last Article: Querying Device Commands
Next Article: Creating a Device Command Revocation Task
Did this article solve your problem?
Thank you for your score！Your feedback would help us improve the website.