Tuya物联网平台设备期望属性值设置与服务调用指南_云市场(Marketplace)-阿里云帮助中心

设备期望属性值

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

设备在线

设备在线时，在云端设置设备期望属性值，云端将直接投递给设备。

Topic和数据格式（下行）：

数据格式（下行）	请求和响应Topic
JSON	请求Topic：`/sys/${ProductID}/${HardwareID}/thing/service/property/set` 响应Topic：`/sys/${ProductID}/${HardwareID}/thing/service/property/set_reply`

请求数据格式：

{
    "id": "123",
    "version": "1.0",
    "params": {
        "temperature": "30.5"
    },
    "method": "thing.service.property.set"
}

响应数据格式：

成功返回示例

{
    "code": 200,
    "data": {},
    "id": "123",
    "message": "success",
    "version": "1.0"
}

参数说明：

参数	类型	说明
id	String	消息ID号，String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
version	String	协议版本号，目前协议版本号唯一取值为1.0。
params	Object	属性设置参数。如以上示例中，设置属性：`{ "temperature": "30.5" }`。
method	String	请求方法。例如：`thing.service.property.set`。

响应数据格式：

参数	类型	说明
id	String	消息ID号，String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
code	Integer	结果状态码，具体参考设备端通用code。
data	Object	请求成功时，返回的数据固定为空。
message	String	返回结果信息。请求成功时，返回success。
version	String	协议版本号，与请求参数中version相同。

获取期望属性值

上行（JSON）。

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

请求Topic：/sys/${ProductID}/${HardwareID}/thing/property/desired/get。
响应Topic：/sys/${ProductID}/${HardwareID}/thing/property/desired/get_reply。

请求数据格式：

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

响应数据格式：

{
    "id":"123",
    "code":200,
    "data":{
        "power": {
            "value": "on",
            "version": 2
        }
    }
}

表 1. 请求参数描述

参数	类型	说明
id	String	消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
version	String	协议版本号，目前协议版本号唯一取值为1.0。
sys	Object	扩展功能的参数，其下包含各功能字段。
ack	Integer	sys下的扩展功能字段，表示是否返回响应数据。 1：云端返回响应数据。 0：云端不返回响应数据。
params	List	要获取期望值的属性标识符（Identifier）列表。如示例中列举了两个属性的标识符：
method	String	请求方法，取值`thing.property.desired.get`。

表 2. 返回参数描述

参数	类型	说明
id	String	消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
code	Integer	结果信息，具体参考设备端通用code。
data	Object	返回的期望值信息。示例中，返回了属性power的期望值数据，包含期望值value和当前期望值版本version。

表 3. data

参数	类型	说明
key	String	key即属性的标识符。如示例中为power。
value	Object	期望属性值。
version	Integer	当前期望属性值的版本。

清空期望属性值

上行（JSON）。

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

请求Topic：/sys/${ProductID}/${HardwareID}/thing/property/desired/delete。
响应Topic：/sys/${ProductID}/${HardwareID}/thing/property/desired/delete_reply。

请求数据格式：

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

响应数据格式：

{
    "id": "123",
    "code": 200,
    "data": { }
}

表 4. 请求参数描述

参数	类型	说明
id	String	消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
version	String	协议版本号，目前协议版本号唯一取值为1.0。
sys	Object	扩展功能的参数，其下包含各功能字段。
ack	Integer	sys下的扩展功能字段，表示是否返回响应数据。 1：云端返回响应数据。 0：云端不返回响应数据。
params	Object	要清除期望值的属性信息列表。传入数据包含属性的标识符和期望值版本version。
method	String	请求方法，取值`thing.property.desired.delete`。

表 5. params

参数	类型	说明
key	String	key即属性的标识符。如示例中，列出了power和temperature两个属性标识符。
version	Integer	要删除期望属性值的版本号。

表 6. 返回参数描述

参数	类型	说明
id	String	消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
code	Integer	结果信息，具体参考设备端通用code。
data	Object	返回数据。清空期望属性值时，返回数据为空。