云端可以调用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返回数据。清空期望属性值时,返回数据为空。

相关文档