云端可以调用SetDeviceDesiredProperty接口，设置期望属性值来控制设备。在云端设置设备期望属性值后，若设备在线，将实时更新设备属性状态；若设备离线，期望属性值将缓存云端，待设备上线后，获取期望属性值，并更新属性状态。本文介绍设备期望属性值的数据格式。

说明 云端通过调用接口设置期望属性值，请参见SetDeviceDesiredProperty。

获取期望属性值

上行（Alink JSON）。

设备向云端请求获取设备属性的期望值。

  • 请求Topic：/sys/${productKey}/${deviceName}/thing/property/desired/get。
  • 响应Topic：/sys/${productKey}/${deviceName}/thing/property/desired/get_reply。

Alink请求数据格式：

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

Alink响应数据格式：

{
    "id":"123",
    "code":200,
    "data":{
        "power": {
            "value": "on",
            "version": 2
        }
    }
}
表 1. 请求参数描述
参数类型说明
idString消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
versionString协议版本号，目前协议版本号唯一取值为1.0。
sysObject扩展功能的参数，其下包含各功能字段。
说明 使用设备端SDK开发时，如果未设置扩展功能，则无此参数，相关功能保持默认配置。
ackIntegersys下的扩展功能字段，表示是否返回响应数据。
  • 1：云端返回响应数据。
  • 0：云端不返回响应数据。
重要 该功能配置说明，请参见物模型使用示例。

如果未配置该功能，则无此参数，云端默认返回响应数据。

paramsList要获取期望值的属性标识符（Identifier）列表。

如示例中列举了两个属性的标识符：

[ 
 "power",
 "temperature"
 ]

如果是自定义模块属性，属性标识符格式为模块标识符:属性标识符（中间为英文冒号）。示例：

[ 
 "test:power",
 "test:temperature"
 ]
methodString请求方法，取值thing.property.desired.get。
表 2. 返回参数描述
参数类型说明
idString消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
codeInteger结果信息， 具体参考设备端通用code。
dataObject返回的期望值信息。

示例中，返回了属性power的期望值数据，包含期望值value和当前期望值版本version。

{
  "power": {
    "value": "on", 
    "version": 2
  }
}

如果是自定义模块属性，属性标识符格式为模块标识符:属性标识符（中间为英文冒号）。示例：

{
  "test:power": {
    "value": "on", 
    "version": 2
  }
}
说明 若未在云端设置过该属性的期望值，或期望属性值已被清空，返回对象中不包含该属性的标识符。如示例中，属性temperature无期望值，返回数据中不包含该属性标识符。

Data所包含的参数具体说明，请见下表data。

表 3. data
参数类型说明
keyStringkey即属性的标识符。如示例中为power。
valueO​bject期望属性值。
versionInteger当前期望属性值的版本。
说明 首次设置期望属性值后，期望值版本为1。以后每次设置后，期望值版本号自动加1。

清空期望属性值

上行（Alink JSON）。

设备清除云端设备的期望属性值。

  • 请求Topic：/sys/${productKey}/${deviceName}/thing/property/desired/delete。
  • 响应Topic：/sys/${productKey}/${deviceName}/thing/property/desired/delete_reply。

Alink请求数据格式：

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

Alink响应数据格式：

{
    "id": "123",
    "code": 200,
    "data": { }
}
表 4. 请求参数描述
参数类型说明
idString消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
versionString协议版本号，目前协议版本号唯一取值为1.0。
sysObject扩展功能的参数，其下包含各功能字段。
说明 使用设备端SDK开发时，如果未设置扩展功能，则无此参数，相关功能保持默认配置。
ackIntegersys下的扩展功能字段，表示是否返回响应数据。
  • 1：云端返回响应数据。
  • 0：云端不返回响应数据。
重要 该功能配置说明，请参见物模型使用示例。

如果未配置该功能，则无此参数，云端默认返回响应数据。

paramsO​bject要清除期望值的属性信息列表。传入数据包含属性的标识符和期望值版本version。如： 
{
  "power": {
    "version": 1
  }, 
  "temperature": { }
}

如果是自定义模块属性，属性标识符格式为模块标识符:属性标识符（中间为英文冒号）。示例：

{
  "test:power": {
    "version": 1
  }, 
  "test:temperature": { }
}

params所包含的参数具体说明，请见下表params。

methodString请求方法，取值thing.property.desired.delete。
表 5. params
参数类型说明
keyStringkey即属性的标识符。如示例中，列出了power和temperature两个属性标识符。
versionInteger要删除期望属性值的版本号。
说明
  • version版本号可从Topic：/sys/${productKey}/${deviceName}/thing/property/desired/get 获取。
  • 如果指定version为2，则表示云端最新版本是2时执行清除。如果指定版本为2，但是云端最新版本是3，则忽略这个清除请求。
  • 若请求中，未指定要清除的期望值版本version，则不验证版本号，该属性的期望值将被清除。
表 6. 返回参数描述
参数类型说明
idString消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
codeInteger结果信息，具体参考设备端通用code。
dataO​bject返回数据。清空期望属性值时，返回数据为空。

相关文档