Desired device property values - IoT Platform - Alibaba Cloud ドキュメントセンター

To control a device, you can call the SetDeviceDesiredProperty operation in IoT Platform to set desired property values for the device. After you set a desired property value for a device in IoT Platform, the property value is updated in real time if the device is online. If the device is offline, the desired property value is cached in IoT Platform. When the device comes online again, the device obtains the desired property value and updates the existing property value. This topic describes the message formats that are related to desired device property values.

Note For more information about how to call the SetDeviceDesiredProperty operation in IoT Platform to set desired property values for a device, see SetDeviceDesiredProperty.

Obtain desired property values

The following topics are used when a device sends requests to IoT Platform and IoT Platform sends responses to the device:

A device sends a request to obtain the desired property values from IoT Platform.

Request topic: /sys/${productKey}/${deviceName}/thing/property/desired/get
Response topic: /sys/${productKey}/${deviceName}/thing/property/desired/get_reply

Sample request in the Alink JSON format:

{
    "id" : "123",
    "version":"1.0",
    "sys":{
      "ack":0
  },
    "params" : [
        "power",
        "temperature"
    ],
    "method":"thing.property.desired.get"
}

Sample response in the Alink JSON format:

{
    "id":"123",
    "code":200,
    "data":{
        "power": {
            "value": "on",
            "version": 2
        }
    }
}

Table 1. Request parameters
Parameter	Type	Description
id	String	The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
version	String	The version of the protocol. Valid value: 1.0.
sys	Object	The parameter for extended features. The value contains the fields for each feature. Note If no extended features are configured when you use a device SDK to develop device features, this parameter is unavailable. The extended features use the default configurations.
ack	Integer	The extended feature field in the sys parameter. This field specifies whether IoT Platform needs to return response data for the registration request. Valid values: 1: IoT Platform needs to return response data. 0: IoT Platform does not need to return response data. Important For more information about the parameter, see Examples on how to use a TSL model. If the feature is not configured, this parameter is unavailable. By default, IoT Platform returns response data for a registration request.
params	List	The identifier list of properties of which you want to obtain the desired values. In this example, the following property identifiers are listed: `[ "power", "temperature" ]` The identifier of a custom module property is in the format of `Module identifier:Property identifier`. Example: `[ "test:power", "test:temperature" ]`
method	String	The request method. Valid value: `thing.property.desired.get`.

Table 2. Response parameters
Parameter	Type	Description
id	String	The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
code	Integer	The HTTP status code in the response. For more information, see Common codes on devices.
data	Object	The desired value information that is returned. In this example, the desired value information about the power property is returned. The information includes the value and version of the property. `{ "power": { "value": "on", "version": 2 } }` The identifier of a custom module property is in the format of `Module identifier:Property identifier`. Example: `{ "test:power": { "value": "on", "version": 2 } }` Note If no desired value is set for a property in IoT Platform or the desired value has been deleted, the returned data does not contain the identifier of this property. In this example, the temperature property does not have a desired value. Therefore, the returned data does not contain this property identifier. For more information about the parameters in data, see the following table.

Table 3. data
Parameter	Type	Description
key	String	The identifier of the property, such as power in this example.
value	Object	The desired value.
version	Integer	The current version of the desired value. Note When you set the desired property value for the first time, the version is 1. Then, the version increases by 1 every time you set the desired value.

Delete desired property values

The following topics are used when a device sends requests to IoT Platform and IoT Platform sends responses to the device:

A device sends a request to delete the desired property values that are cached in IoT Platform.

Request topic: /sys/${productKey}/${deviceName}/thing/property/desired/delete
Response topic: /sys/${productKey}/${deviceName}/thing/property/desired/delete_reply

Sample request in the Alink JSON format:

{
    "id": "123",
    "version": "1.0",
    "sys":{
      "ack":0
  },
    "params": {
        "power": {
            "version": 1
        },
        "temperature": { }
    },
    "method":"thing.property.desired.delete"  
}

Sample response in the Alink JSON format:

{
    "id": "123",
    "code": 200,
    "data": { }
}

Table 4. Request parameters
Parameter	Type	Description
id	String	The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
version	String	The version of the protocol. Valid value: 1.0.
sys	Object	The parameter for extended features. The value contains the fields for each feature. Note If no extended features are configured when you use a device SDK to develop device features, this parameter is unavailable. The extended features use the default configurations.
ack	Integer	The extended feature field in the sys parameter. This field specifies whether IoT Platform needs to return response data for the registration request. Valid values: 1: IoT Platform needs to return response data. 0: IoT Platform does not need to return response data. Important For more information about the parameter, see Examples on how to use a TSL model. If the feature is not configured, this parameter is unavailable. By default, IoT Platform returns response data for a registration request.
params	Object	The list of the properties of which you want to delete the desired values. A property is identified by the identifier and version. Example: `{ "power": { "version": 1 }, "temperature": { } }` The identifier of a custom module property is in the format of `Module identifier:Property identifier`. Example: `{ "test:power": { "version": 1 }, "test:temperature": { } }` For more information about the parameters in params, see the following table.
method	String	The request method. Valid value: `thing.property.desired.delete`.

Table 5. params
Parameter	Type	Description
key	String	The identifier of the property. In this example, the following property identifiers are listed: power and temperature.
version	Integer	The version of the desired value to be deleted. Note You can obtain the value of the version parameter from the `/sys/${productKey}/${deviceName}/thing/property/desired/get` topic. If you set the version parameter to 2, IoT Platform deletes the desired value only if the current version is 2. If the current version of the desired value is 3 in IoT Platform, this delete request is ignored. If the version parameter is not specified in the request, IoT Platform does not verify the version, but directly deletes the desired value.

Table 6. Response parameters
Parameter	Type	Description
id	String	The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
code	Integer	The HTTP status code in the response. For more information, see Common codes on devices.
data	Object	The returned data. In the response to a request to delete the desired property values, no data is returned.

IoT Platform:Desired device property values

Obtain desired property values

Delete desired property values

References