调用该接口为指定设备批量设置期望属性值。

限制说明

  • 只读属性不支持设置期望属性值。
  • 一次调用最多可设置10个期望属性值。
  • 设备创建后,期望属性值的版本(Version)为0。首次设置期望属性值时,如果指定Version参数,则需指定Version值为0。

请求参数

名称 类型 是否必需 描述
Action String 要执行的操作,取值:SetDeviceDesiredProperty
IotId String

要设置期望属性值的设备ID。

说明 如果传入该参数,则无需传入ProductKeyDeviceNameIotId作为设备唯一标识符,与ProductKeyDeviceName组合是一一对应的关系。如果您同时传入IotIdProductKeyDeviceName组合,则以IotId为准。
ProductKey String

要设置期望属性值的设备所隶属的产品Key。

说明 如果传入该参数,需同时传入DeviceName
DeviceName String

要设置期望属性值的设备的名称。

说明 如果传入该参数,需同时传入ProductKey
Items String

要设置的期望属性值,组成为key:value,数据格式为 JSON String,如{"Power":1}

详情参见下表Items。

说明 最多可输入10个期望属性值。
Versions String

当前期望属性值版本,组成为key:value,数据格式为 JSON String,如{"Power":2}

详情参见下表Versions。

说明 如果传入的版本号与当前版本不符,服务器将拒绝此次请求。若您不确定当前期望值的版本号,可以不传入版本号,但仍需传入有效的JSON,即传入{}
IotInstanceId String 公共实例不传此参数;仅独享实例需传入实例ID。
公共请求参数 - 请参见公共参数
表 1. Items
名称 类型 描述
key String

取值为属性的标识符(identifier)。可在控制台中,设备所属产品的功能定义中查看属性的identifier。

说明
  • 指定属性必须是读写型。如果您指定了一个只读型的属性,设置将会失败。
  • 一次调用中,key的取值(即属性的identifier)不能重复。
value Object

要设置的期望属性值。取值需符合您为该属性定义的数据类型和取值范围。

说明 若属性值设置为null,则表示清空期望属性值。
表 2. Versions
名称 类型 描述
key String 取值为属性的标识符(identifier)。可在控制台中,设备所属产品的功能定义中查看属性的identifier。
说明 一次调用中,key的取值(即属性的identifier)不能重复。
value Long

当前期望属性值的版本号。

首次设置期望属性值时,指定该参数值为0。首次设置期望属性值后,期望值版本号为1。以后每次设置期望值后,物联网平台自动将期望值版本加1(即第二次设置期望属性值时,指定该参数值为1。设置成功后,版本号自动变为2;第三次设置时,指定该参数值为2。设置成功后,版本号自动变为3;以此类推)。

说明 若传入的版本号与当前版本号不符,请求将失败。

返回参数

名称 类型 描述
RequestId String 阿里云为该请求生成的唯一标识符。
Success Boolean 表示是否调用成功。true表示调用成功,false表示调用失败。
ErrorMessage String 调用失败时,返回的出错信息。
Code String 调用失败时,返回的错误码。错误码详情,请参见错误码
Data Data 调用成功时,返回的数据。详情请参见下表Data。
表 3. Data
名称 类型 描述
MessageId String 云端下发给设备的设置期望属性值的消息ID。
Version String 本次设置期望属性值后,期望属性值的当前版本号。

示例

请求示例

https://iot.cn-shanghai.aliyuncs.com/?Action=SetDeviceDesiredProperty
&ProductKey=al*********
&DeviceName=device1
&Items=%7B%22LightAdjustLevel%22%3A1%7D
&Versions=%7B%22LightAdjustLevel%22%3A10%7D
&公共请求参数

返回示例

  • JSON格式
    {
        "Data": {
            "MessageId": "300511751",
            "Versions": "{\"Power\":2}"
        },
        "RequestId": "AADE79D2-B328-4FC6-A3E0-34BB23BCA440",
        "Success": true
    }
  • XML格式
    <?xml version='1.0' encoding='utf-8'?>
    <SetDeviceDesiredPropertyResponse>
        <RequestId>AADE79D2-B328-4FC6-A3E0-34BB23BCA440</RequestId>
        <Success>true</Success>
        <Data>
         <MessageId>300511751</MessageId>
         <Versions>{"Power":2}</Versions>
        </Data>
    </SetDeviceDesiredPropertyResponse>