Call this operation to set desired property values for a device.

Limits

  • You cannot set desired properties for read-only properties.
  • You can set desired values for up to ten properties at a time.
  • After a device has been created, the desired property version number is 0. Therefore, when you set desired value for a property for the first time, specify the value of the parameter Version to 0.

Request parameters

Parameter Type Required Description
Action String Yes The operation that you want to perform. Set the value to SetDeviceDesiredProperty.
IotId String No

The unique identifier of the device for which you want to set desired property values.

Note If you specify this parameter, ProductKey and DeviceName are not required. IotId is the globally unique identifier (GUID) of a device, and corresponds to the combination of ProductKey and DeviceName. If you specify both IotId and the combination of ProductKeyand DeviceName, the system follows IotId.
ProductKey String No

The ProductKey of the device for which you want to set desired property values.

Note If you use this parameter, DeviceName is required.
DeviceName String No

The name of the device for which you want to set desired property values.

Note If you specify this parameter, you must also specify ProductKey.
Items String Yes

The desired values of properties to be set. The value of this parameter is a JSON string with key:value pairs.

For more information, see the following Items table.

Note You can set desired values for up to 10 properties in a call.
Versions String No

The current versions of desired properties. The value of this parameter is a JSON string with key:value pairs.

For more information, see the following Versions table.

Note If the version you specified in this parameter is not the current version, the system will deny the request. If you are not sure about the current version number, do not specify this parameter.
Common request parameters - No See Common parameters.
Table 1. Items
Parameter Type Description
key String

The identifier of the property. You can view identifiers of properties on the Define Feature page of the product to which the device belongs in the IoT Platform console.

Note
  • The specified property must be read/write type. If you specify a read-only property, the setting will fail.
  • You cannot specify duplicate property identifiers in a call.
value Object

The value that you want to set. The value must be in the value range that you have defined for the property.

Note If you set the value to null, the desired value of this property will be cleared.
Table 2. Versions
Parameter Type Description
key String The identifier of the property. On the Define Feature page of the product to which the device belongs in the IoT Platform console, you can view identifiers of properties.
Note You cannot specify duplicate property identifiers in a call.
value Long

The current version of the desired property value.

When you set desired value for a device property for the first time, set this value to 0. After you successfully set a desired value for a property for the first time, the desired property value version number automatically changes to 1. When you set a desired value for the property for the second time, specify this value to 1. And then, the version number automatically changes to 2. When you set for the third time, set this value to 2, and so on.

Note If the version you specified in this parameter is not the current version, the system will deny the request.

Response parameters

Parameter Type Description
RequestId String The globally unique ID generated by Alibaba Cloud for the request.
Success Boolean Indicates whether the call is successful. A value of true indicates that the call is successful. A value of false indicates that the call failed.
ErrorMessage String The error message returned when the call fails.
Code String The error code returned when the call fails. For more information about error codes, see Error codes.
Data Data The data returned when the call is successful. See the following Data table.
Table 3. Data
Parameter Type Description
MessageId String The ID of the desired property value setting message that IoT Platform sends to the device.

Examples

Request example

https://iot.cn-shanghai.aliyuncs.com/?Action=SetDeviceDesiredProperty
&ProductKey=al*********
&DeviceName=device1
&Items=%7B%22LightAdjustLevel%22%3A1%7D
&Versions=%7B%22LightAdjustLevel%22%3A10%7D
&Common request parameters

Response example

  • JSON format
    { 
      "RequestId":"57b144cf-09fc-4916-a272-a62902d5b207", 
      "Success": true, 
      "Data": {
         "MessageId":"abcabc123"
       } 
    }
  • XML format
    <? xml version='1.0' encoding='utf-8'? >
    <SetDeviceDesiredPropertyResponse>
        <RequestId>57b144cf-09fc-4916-a272-a62902d5b207</RequestId>
        <Success>true</Success>
        <Data>
    	 <MessageId>abcabc123</MessageId>
        </Data>
    </SetDeviceDesiredPropertyResponse>