在云端设置设备期望属性值后,若设备在线,将实时更新设备属性状态;若设备离线,期望属性值将缓存云端,待设备上线后,获取期望属性值,并更新属性状态。本文讲述设备期望属性值的数据格式。

获取期望属性值

上行(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",
    "params" : [
        "power",
        "temperature"
    ],
    "method":"thing.property.desired.get"  
}

Alink响应数据格式

{
    "id":"123",
    "code":200,
    "data":{
		"power": {
			"value": "on",
			"version": 2
		}
	}
}
表 1. 请求参数描述
参数 类型 说明
id String 消息ID号。需定义为String类型的数字,且设备维度唯一。
version String 协议版本号,目前协议版本号为1.0
params List 要获取期望值的属性标识符(Identifier)列表。

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

[ 
 "power",
 "temperature"
 ]
method String 请求方法,取值thing.property.desired.get
表 2. 返回参数描述
参数 类型 说明
id String 消息ID号。
code Integer 结果信息, 具体参考设备端通用code
data Object 返回的期望值信息。

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

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

data中所包含的参数具体说明,请见下表data

表 3. data
参数 类型 说明
key String key即属性的标识符。如示例中为power。
value O​bject 期望属性值。
version Integer 当前期望属性值的版本。
说明 首次设置期望属性值后,期望值版本为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",
    "params" :  {
		"power": {
			"version": 1
		},
		"temperature": {
		}
	},
    "method":"thing.property.desired.delete"  
}

Alink响应数据格式

{
    "id":"123",
    "code":200,
    "data":{
	}
}
表 4. 请求参数描述
参数 类型 说明
id String 消息ID号。需定义为String类型的数字,且设备维度唯一。
version String 协议版本号,目前协议版本号为1.0
params List 要清除期望值的属性信息列表。传入数据包含属性的标识符和期望值版本version。如:
{
  "power": {
    "version": 1
  }, 
  "temperature": { }
}

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

method String 请求方法,取值thing.property.desired.delete
表 5. params
参数 类型 说明
key String key即属性的标识符。如示例中,列出了power和temperature两个属性标识符。
version Integer 要删除期望属性值的版本号。
说明
  • version版本号可从Topic/sys/{productKey}/{deviceName}/thing/property/desired/get 获取。
  • 如果指定version为2,则表示云端最新版本是2时执行清除。如果指定版本为2,但是云端最新版本是3,则忽略这个清除请求。
  • 若请求中,未指定要清除的期望值版本version,则不验证版本号,该属性的期望值将被清除。
表 6. 返回参数描述
参数 类型 说明
id String 消息ID号。
code Integer 结果信息, 具体参考设备端通用code
data String 返回数据。