Desired property values of a device-IoT Platform (Deprecated)(IoT)-阿里云帮助中心

You can call the SetDeviceDesiredProperty API to set desired property values and control a device. If the device is online, its properties are updated in real time. If the device is offline, the desired property values are cached in the cloud. When the device goes online, it retrieves the desired property values and updates its properties. This topic describes the data format for desired property values.

Note For more information about how to set desired property values by calling an API, see SetDeviceDesiredProperty.

Get desired property values

Uplink (Alink JSON).

The device sends a request to the cloud to retrieve the desired values of its properties.

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

Alink request data format:

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

Alink response data format:

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

Table 1. Request parameters
Parameter	Type	Description
id	String	The message ID. It must be a string that contains a number. The value must be unique for the device. The value range is 0 to 4294967295.
version	String	The protocol version number. The value must be 1.0.
sys	Object	Parameters for extended features. It contains fields for different features. Note If you use a device-side software development kit (SDK) for development and do not set extended features, this parameter is not included. The related features use default configurations.
ack	Integer	An extended feature field under sys. It specifies whether to return a response. 1: The cloud returns a response. 0: The cloud does not return a response. Important For information about how to configure this feature, see Thing Specification Language model usage examples. If this feature is not configured, this parameter is not included. The cloud returns a response by default.
params	List	A list of identifiers for the properties whose desired values you want to get. The following example lists the identifiers of two properties: `[ "power", "temperature" ]` For a custom module property, the identifier format is `ModuleIdentifier:PropertyIdentifier`. The module identifier and property identifier are separated by a colon (:). Example: `[ "test:power", "test:temperature" ]`
method	String	The request method. The value is `thing.property.desired.get`.

Table 2. Response parameters
Parameter	Type	Description
id	String	The message ID. It must be a string that contains a number. The value must be unique for the device. The value range is 0 to 4294967295.
code	Integer	The result information. For more information, see Device-side general codes.
data	Object	The information about the desired values that is returned. In the example, the desired value data for the power property is returned. It includes the desired value and the current desired value version. `{ "power": { "value": "on", "version": 2 } }` For a custom module property, the identifier format is `ModuleIdentifier:PropertyIdentifier`. The module identifier and property identifier are separated by a colon (:). Example: `{ "test:power": { "value": "on", "version": 2 } }` Note If no desired value has been set for a property in the cloud, or if the desired property value has been deleted, the response object does not include the identifier for that property. For example, the temperature property has no desired value, so the response data does not include its identifier. For more information about the parameters in data, see the following data table.

Table 3. data
Parameter	Type	Description
key	String	The key is the property identifier. In the example, the key is power.
value	Object	The desired property value.
version	Integer	The version of the current desired property value. Note After you set a desired property value for the first time, the version is 1. Each time the value is set again, the version number automatically increments by 1.

Delete desired property values

Uplink (Alink JSON).

The device deletes the desired property values that are cached in the cloud.

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

Alink request data format:

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

Alink response data format:

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

Table 4. Request parameters
Parameter	Type	Description
id	String	The message ID. It must be a string that contains a number. The value must be unique for the device. The value range is 0 to 4294967295.
version	String	The protocol version number. The value must be 1.0.
sys	Object	Parameters for extended features. It contains fields for different features. Note If you use a device-side software development kit (SDK) for development and do not set extended features, this parameter is not included. The related features use default configurations.
ack	Integer	An extended feature field under sys. It specifies whether to return a response. 1: The cloud returns a response. 0: The cloud does not return a response. Important For information about how to configure this feature, see Thing Specification Language model usage examples. If this feature is not configured, this parameter is not included. The cloud returns a response by default.
params	Object	A list of properties whose desired values you want to delete. The data includes the property identifier and the desired value version. Example: `{ "power": { "version": 1 }, "temperature": { } }` For a custom module property, the identifier format is `ModuleIdentifier:PropertyIdentifier`. The module identifier and property identifier are separated by a colon (:). Example: `{ "test:power": { "version": 1 }, "test:temperature": { } }` For more information about the parameters in params, see the following params table.
method	String	The request method. The value is `thing.property.desired.delete`.

Table 5. params
Parameter	Type	Description
key	String	The key is the property identifier. In the example, the identifiers for the power and temperature properties are listed.
version	Integer	The version number of the desired property value to delete. Note version number can be obtained from the `/sys/${productKey}/${deviceName}/thing/property/desired/get` topic. If you set version to 2, the delete operation is performed only if the latest version in the cloud is 2. If you specify version 2 but the latest version in the cloud is 3, the delete request is ignored. If the version to delete is not specified in the request, the version number is not validated, and the desired value for the property is deleted.

Table 6. Response parameters
Parameter	Type	Description
id	String	The message ID. It must be a string that contains a number. The value must be unique for the device. The value range is 0 to 4294967295.
code	Integer	The result information. For more information, see Device-side general codes.
data	Object	The returned data. When you delete desired property values, the returned data is empty.

Get desired property values

Delete desired property values

References