Modifying Information in a Device Shadow
Typical Scenario
The platform supports the creation of device shadows. Device shadows store the latest service properties reported by devices and service property configurations delivered by applications. (Service properties are defined in the device's product model.) If the device is offline or abnormal, the application cannot deliver configuration to the device by issuing commands. However, the application can set the configuration to be delivered to the device shadow. When the device goes online again, the device shadow delivers the configuration to the device. The application can call this API to modify the configuration information to be delivered to the device on the device shadow.
Each device has only one device shadow, which contains desired and report sections.
- The desired section stores the configurations of device service properties. If a device is online, the configurations in the desired section are delivered to the device immediately. Otherwise, the configurations in the desired section are delivered to the device when the device goes online.
- The report section stores the latest service properties reported by devices. When a device reports data, the platform synchronizes the data to the report section of the device shadow.
API Function
This API is used to modify the configuration information in the desired section of the device shadow. When the device goes online, the configuration information will be delivered to the device.
API Description
1 | def modifyDeviceShadow(self, mdsInDTO, deviceId, appId, accessToken)
|
Class
DeviceManagement
Parameter Description
| Parameter | Mandatory or Optional | Type | Location | Description |
|---|---|---|---|---|
| mdsInDTO | Mandatory | ModifyDeviceShadowInDTO | body | For details, see ModifyDeviceShadowInDTO structure. |
| deviceId | Mandatory | String(256) | path | Identifies a device. The device ID is allocated by the platform during device registration. |
| appId | Optional | String | query | If the device belongs to the current application, set this parameter to None. Otherwise, set this parameter to the ID of the authorized application. |
| accessToken | Mandatory | String | header | This parameter is set to the value of the accessToken obtained by calling the Authentication API. |
ModifyDeviceShadowInDTO structure
| Parameter | Mandatory or Optional | Type | Location | Description |
|---|---|---|---|---|
| serviceDesireds | Mandatory | List<ServiceDesiredDTO> | body | Indicates the configuration or status to be modified. For details, see ServiceDesiredDTO structure. |
ServiceDesiredDTO structure
| Parameter | Mandatory or Optional | Type | Location | Description |
|---|---|---|---|---|
| serviceId | Optional | String(1-256) | body | Identifies a service. |
| desired | Optional | Object | body | Indicates the device status. |
Return Value
void
Error Codes
| HTTP Status Code | Error Code | Error Description | Remarks |
|---|---|---|---|
| 200 | 100425 | The device template does not exist. | The device template does not exist. Recommended handling: Check whether the device template has been uploaded to the IoT platform. |
| 200 | 100431 | The service type does not exist. | The service type does not exist. Recommended handling:
|
| 400 | 107002 | The device properties do not exist in the database. | The device properties do not exist. Recommended handling: Check whether serviceId carried in the API request is correct. |
| 400 | 107003 | The request properties are unknown. | The device status is unknown. Recommended handling: Check whether the connection between the device and the IoT platform is normal. |
| 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. |
| 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 | 100443 | The property is forbidden to write. | The device properties cannot be written. |
| 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. | The access token is invalid. Recommended handling: Check whether accessToken carried in the API request is correct. |
| 404 | 100403 | The device does not exist. | The device does not exist. Recommended handling: Check whether deviceId is correct. |
| 404 | 100418 | The device data does not exist. | The device data does not exist. Recommended handling:
|
| 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 | 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: Querying Information in a Device Shadow
Next Article: Data Collection
Did this article solve your problem?
Thank you for your score！Your feedback would help us improve the website.