设备属性、动作与事件
更新时间：2024-06-19 05:54:44下载pdf
涂鸦云端通过物模型描述设备的功能定义，将设备功能抽象为属性、动作与事件。
本文介绍这三种设备能力的通讯机制和协议格式。具体平台操作说明，可查看 功能定义 进行了解。
属性上报
交互示意图
设备发送消息
设备主动向云端上报设备属性值。
Topic：tylink/${deviceId}/thing/property/report
{
"msgId":"45lkj3551234***",
"time":1626197189638,
"data":{
"color":{
"value":"red",
"time": 1626197189638
},
"brightness":{
"value":80,
"time": 1626197189638
}
}
}
参数说明
| 参数 | 类型 | 说明 | 必选 | 备注 |
|---|---|---|---|---|
| ${deviceId} | string | 设备 ID | 是 | 属性上报的来源设备 ID。 |
| version | string | 协议版本 | 否 | 默认 1.0，且仅有 1.0。 |
| msgId | string | 消息 ID | 是 | 总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。 |
| time | number | 消息时间戳 | 是 | 消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。 |
| sys | object | 系统参数 | 否 | 控制消息的系统行为。 |
| sys.ack | number | 属性上报应答行为 | 否 | 默认情况下设备属性上报后云端不会返回应答消息，但可以通过 ack 参数改变这一默认行为。
|
| data | object | 上报的属性值集合 | 是 | key 为属性 code，value 为属性值和属性变更时间戳。 |
| data.${key} | object | 属性上报对象 | 是 | key 为属性 code。 |
| data.${key}.time | number | 属性变更时间戳 | 是 | Unix 时间戳，10 位秒级或 13 位毫秒级。 |
| data.${key}.value | object | 属性上报值 | 是 | 具体的属性值。 |
设备接收消息
云端处理上报后，默认不对属性上报消息进行响应，除非设备端在上报时显式指定 ack 为 1。
Topic：tylink/${deviceId}/thing/property/report_response
{
"msgId":"45lkj3551234***",
"time":1626197189640,
"code":0
}
参数说明
| 参数 | 类型 | 说明 | 必选 | 备注 |
|---|---|---|---|---|
| ${deviceId} | string | 设备 ID | 是 | 属性上报的来源设备 ID。 |
| version | string | 协议版本 | 否 | 默认 1.0，且仅有 1.0。 |
| msgId | string | 消息 ID | 是 | 与对应的上报消息的 msgId 保持一致，通过 msgId 来标识应答关系。 |
| time | number | 消息时间戳 | 是 | 消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。 |
| code | number | 响应状态码 | 否 |
|
状态码说明
| 状态码 | 说明 |
|---|---|
| 0 | 默认状态，代表成功。 |
| 1003 | 数据格式错误。 |
| 1004 | 设备不存在。 |
| 2002 | 设备关联的模型未定义。 |
| 2003 | 设备关联的属性未定义。 |
| 2006 | 数据校验失败。 |
属性下发
交互示意图
设备接收消息
设备接收云端发送的属性设置消息。
Topic：tylink/${deviceId}/thing/property/set
{
"msgId":"45lkj3551234***",
"time":1626197189638,
"data":{
"color":"green",
"brightness":50
}
}
参数说明
| 参数 | 类型 | 说明 | 必选 | 备注 |
|---|---|---|---|---|
| ${deviceId} | string | 设备 ID | 是 | 属性下发的目标设备 ID。 |
| version | string | 协议版本 | 否 | 默认 1.0，且仅有 1.0。 |
| msgId | string | 消息 ID | 是 | 总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。 |
| time | number | 消息时间戳 | 是 | 消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。 |
| sys | object | 系统参数 | 否 | 控制消息的系统行为。 |
| sys.ack | number | 属性下发应答行为 | 否 | 默认情况下设备属性下发后设备不会返回应答消息，但可以通过 ack 参数改变这一默认行为。
|
| data | object | 下发的属性值集合 | 是 | 下发属性值的集合，key 为属性 code，value 为属性值。 |
设备发送消息
设备在处理属性设置之后，默认不对属性设置消息进行响应，除非云端在设置消息中显式指定 ack 为 1。
Topic：tylink/${deviceId}/thing/property/set_response
{
"msgId":"45lkj3551234***",
"time":1626197189640,
"code":0
}
参数说明
| 参数 | 类型 | 说明 | 必选 | 备注 |
|---|---|---|---|---|
| ${deviceId} | string | 设备 ID | 是 | 属性下发的目标设备 ID。 |
| version | string | 协议版本 | 否 | 默认 1.0，且仅有 1.0。 |
| msgId | string | 消息 ID | 是 | 与对应的属性设置消息的 msgId 保持一致，通过 msgId 来标识应答关系。 |
| time | number | 消息时间戳 | 是 | 消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。 |
| code | number | 响应状态码 | 否 |
|
动作执行
交互示意图
设备接收消息
设备接收云端发送的动作执行消息。
Topic：tylink/${deviceId}/thing/action/execute
{
"msgId":"45lkj3551234***",
"time":1626197189638,
"data":{
"actionCode": "testAction",
"inputParams": {
"inputParam1":"value1",
"inputParam2":"value2"
}
}
}
参数说明
| 参数 | 类型 | 说明 | 必选 | 备注 |
|---|---|---|---|---|
| ${deviceId} | string | 设备 ID | 是 | 执行设备动作的目标设备 ID。 |
| version | string | 协议版本 | 否 | 默认 1.0，且仅有 1.0。 |
| msgId | string | 消息 ID | 是 | 总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。 |
| time | number | 消息时间戳 | 是 | 消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。 |
| data | object | 动作执行参数 | 是 | 包含动作 code 与执行参数。 |
| data.actionCode | string | 动作 code | 是 | 动作的模型定义 code。 |
| data.inputParams | object | 动作输入参数 | 否 | 动作执行的输入参数，key 为参数 code，value 为参数值。 |
设备发送消息
当设备执行完动作之后，总是会向云端发送执行结果响应消息。
Topic：tylink/${deviceId}/thing/action/execute_response
{
"msgId":"45lkj3551234***",
"time":1626197189640,
"code":0,
"data":{
"actionCode": "testAction",
"outputParams": {
"outputParam1":"value1",
"outputParam2":"value2"
}
}
}
参数说明
| 参数 | 类型 | 说明 | 必选 | 备注 |
|---|---|---|---|---|
| ${deviceId} | string | 设备 ID | 是 | 执行设备动作的目标设备 ID。 |
| version | string | 协议版本 | 否 | 默认 1.0，且仅有 1.0。 |
| msgId | string | 消息 ID | 是 | 与对应的动作执行消息的 msgId 保持一致，通过 msgId 来标识应答关系。 |
| time | number | 消息时间戳 | 是 | 消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。 |
| code | number | 响应状态码 | 否 |
|
| data | object | 动作执行结果 | 否 | 包含动作 code 和输出参数集合。 |
| data.actionCode | string | 动作 code | 否 | 动作的模型定义 code。 |
| data.outputParams | object | 动作输出参数 | 否 | 动作执行的输出参数，key 为参数 code，value 为参数值。 |
事件上报
交互示意图
设备发送消息
设备主动向云端上报设备事件触发的消息。
Topic：tylink/${deviceId}/thing/event/trigger
{
"msgId":"45lkj3551234***",
"time":1626197189638,
"data":{
"eventCode":"testEvent",
"eventTime":1626197189630, //10 位秒级或 13 位毫秒级事件发生时间戳
"outputParams": { // 事件输出参数
"outputParam1":"value1",
"outputParam2":"value2"
}
}
}
参数说明
| 参数 | 类型 | 说明 | 必选 | 备注 |
|---|---|---|---|---|
| ${deviceId} | string | 设备 ID | 是 | 触发事件的设备 ID。 |
| version | string | 协议版本 | 否 | 默认 1.0，且仅有 1.0。 |
| msgId | string | 消息 ID | 是 | 总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。 |
| time | number | 消息时间戳 | 是 | 消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。 |
| sys | object | 系统参数 | 否 | 控制消息的系统行为。 |
| sys.ack | number | 事件触发应答作为 | 否 | 默认情况事件上报后云端不会返回应答消息，但可以通过 ack 参数改变这一默认行为。
|
| data | object | 事件触发参数 | 是 | 包含事件 code 与输出参数。 |
| data.eventCode | string | 事件code | 是 | 事件的模型定义 code。 |
| data.outputParams | object | 事件输出参数 | 否 | 事件出参，key 为参数code，value 为参数值。 |
设备接收消息
云端接收事件消息之后，默认不对消息进行响应，除非设备在上报消息中显式指定 ack 为 1。
Topic：tylink/${deviceId}/thing/event/trigger_response
{
"msgId":"45lkj3551234***",
"time":1626197189640,
"code":0
}
参数说明
| 参数 | 类型 | 说明 | 必选 | 备注 |
|---|---|---|---|---|
| ${deviceId} | string | 设备 ID | 是 | 触发事件的设备 ID。 |
| version | string | 协议版本 | 否 | 默认 1.0，且仅有 1.0。 |
| msgId | string | 消息 ID | 是 | 与对应的事件触发消息的 msgId 保持一致，通过 msgId 来标识应答关系。 |
| time | number | 消息时间戳 | 是 | 消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。 |
| code | number | 响应状态码 | 否 |
|
状态码说明
| 状态码 | 说明 |
|---|---|
| 0 | 默认状态，代表成功。 |
| 1003 | 数据格式错误。 |
| 1004 | 设备不存在。 |
| 2002 | 设备关联的模型未定义。 |
| 2004 | 设备关联的事件未定义。 |
| 2006 | 数据校验失败。 |
设备批量上报
通过批量上报功能，设备可以一次性向云端上报多个事件、属性数据，同时网关设备还支持同时上报多个子设备的数据。一次性传输内容更多，效率更高。
使用限制：
- 网关设备一次可同时上报的子设备数量不能超过 20 个。
- 受 MQTT 网关限制，最终产生 MQTT 消息报文大小不能超过 64KB 大小，因此需要控制好一次上报的消息大小。
- 涂鸦云端尽可能地接收上报的数据，如果部分数据验证或处理失败，会返回 2121 状态码。如果所有数据都处理失败，会返回 2122。更多错误情况，请查看状态码说明。
设备发送消息
设备向云端批量上报属性、事件数据或者网关设备代替子设备批量上报。
Topic：tylink/${deviceId}/thing/data/batch_report
{
"msgId":"45lkj3551234***",
"time":1626197189638,
"data":{
"properties":{
"color":{
"value":"red",
"time": 1626197189638
}
},
"events":{
"event1":{
"outputParams": {
"outputParam1":"value1",
"outputParam2":"value2"
},
"eventTime":1626197189001
},
"event2":{
"outputParams": {
"outputParam1":"value1",
"outputParam2":"value2"
},
"eventTime":1626197189001
}
},
"subDevices":[
{
"deviceId":"asd453452***",
"properties":{
"color":{
"value":"red",
"time": 1626197189638
},
"brightness":{
"value":80,
"time": 1626197189638
}
},
"events":{
"event1":{
"outputParams": {
"outputParam1":"value1",
"outputParam2":"value2"
},
"eventTime":1626197189001
}
}
}
]
}
}
参数说明
| 参数 | 类型 | 说明 | 必选 | 备注 |
|---|---|---|---|---|
| ${deviceId} | string | 设备 ID | 是 | 批量上报的来源设备 ID。 |
| version | string | 协议版本 | 否 | 默认 1.0，且仅有 1.0。 |
| msgId | string | 消息 ID | 是 | 总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。 |
| time | number | 消息时间戳 | 是 | 消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。 |
| sys | object | 系统参数 | 否 | 控制消息的系统行为。 |
| sys.ack | number | 批量上报应答行为 | 否 | 默认情况下设备批量上报后云端不会返回应答消息，但可以通过 ack 参数改变这一默认行为。
|
| data | object | 上报的数据集合 | 是 | 包含设备自身的批量上报数据和子设备的上报数据。 |
| data.properties | object | 批量上报的属性集合 | 否 | key 为属性 code，value 为属性值和属性变更时间戳。 |
| data.properties.${key} | object | 属性上报对象 | 是 | key 为属性的 code。 |
| data.properties.${key}.time | number | 属性变更时间戳 | 是 | Unix 时间戳，10 位秒级或 13 位毫秒级。 |
| data.properties.${key}.value | object | 属性上报值 | 是 | 具体的属性值。 |
| data.events | object | 批量上报的事件集合 | 否 | key 为事件 code，value 为事件参数和发生时间。 |
| data.events.${key} | object | 事件上报对象 | 是 | code 为事件的 code。 |
| data.events.${key}.eventTime | number | 事件发生时间 | 是 | Unix 时间戳，10 位秒级或 13 位毫秒级。 |
| data.events.${key}.outputParams | object | 事件输出参数 | 是 | 事件输出的参数集合。 |
| data.subDevices | array | 子设备上报数据列表，子设备个数上限不能超过 20 个 | 否 | 当设备为网关时，可以为子设备批量上报数据，每一个列表元素代表一个子设备的数据。 |
| data.subDevices[] | object | 子设备上报数据 | 是 | 每个元素代表一个子设备的数据。 |
| data.subDevices[].deviceId | string | 子设备 ID | 是 | 上报的子设备 ID。 |
| data.subDevices[].properties | object | 子设备批量上报的属性集合 | 否 | 结构定义与 data.properties 类似。 |
| data.subDevices[].events | object | 子设备批量上报的事件集合 | 否 | 结构定义与 data.events 类似。 |
设备接收消息
云端处理批量上报后，默认不对上报消息进行响应，除非设备端在上报时显式指定 ack 为 1。
Topic：tylink/${deviceId}/thing/data/batch_report_response
参数说明
| 参数 | 类型 | 说明 | 必选 | 备注 |
|---|---|---|---|---|
| ${deviceId} | string | 设备 ID | 是 | 批量上报的来源设备 ID。 |
| version | string | 协议版本 | 否 | 默认 1.0，且仅有 1.0。 |
| msgId | string | 消息 ID | 是 | 与对应的批量上报消息的 msgId 保持一致，通过 msgId 来标识应答关系。 |
| time | number | 消息时间戳 | 是 | 消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。 |
| code | number | 响应状态码 | 否 |
|
状态码说明
| 状态码 | 说明 |
|---|---|
| 0 | 默认状态，代表成功。 |
| 1003 | 数据格式错误。 |
| 2121 | 批量上报部分数据处理失败。 |
| 2122 | 批量上报完全处理失败。 |
| 2123 | 批量上报子设备个数超过限制，目前子设备个数上限不能超过 20 个。 |
设备历史上报
设备向云端批量上报历史数据，或者网关设备代替子设备上报历史数据。
适用场景
- 可用于设备短时间产生大量上报数据的情况，将多次上报请求合并在一次上报中，以便提高效率。
- 也可用于离线或周期间隔上报的情况下，同时又要保留设备历史变化的场景。设备可在本地暂存过程历史数据，上报时将暂存的数据批量上报到云端。
使用限制
- 网关设备一次可同时上报的子设备数量不能超过 20 个。
- 受 MQTT 网关限制，最终产生 MQTT 消息报文大小不能超过 64KB 大小，因此需要控制一次上报的消息大小。
- 一次上报的历史数据量不超过 500 条，换言之， [属性数组 size + 事件数组 size + 子设备（属性数组 size + 事件数组 size）] < 500。
- 涂鸦 IoT 云尽可能地接收上报的数据，如果部分数据验证/处理失败，会返回 2121 状态码。如果所有数据都处理失败，会返回 2122。更多错误情况，请查看状态码说明部分。
注意事项
- 设备上报历史数据应按时间升序排序，存入属性数组或者事件数组中。
- 涂鸦 IoT 云按顺序遍历属性数组或者事件数组，进行数据处理。
- 属性最终存储的状态值以一次上报时序最新的数据为准，因此历史数据中应尽量带上时间戳。
设备发送消息
设备向云端批量上报历史数据，或者网关设备代替子设备上报历史数据。
Topic: tylink/${deviceId}/thing/data/history_report
{
"msgId":"45lkj3551234001",
"time":1626197189638,
"data":{
"properties":[
{
"color":{
"value":"red",
"time":1626197190000
},
"brightness":{
"value":80,
"time":1626197190000
}
},
{
"color":{
"value":"blue",
"time":1626197189000
},
"brightness":{
"value":79,
"time":1626197189000
}
}
],
"events":[
{
"event1":{
"outputParams":{
"outputParam1":"value11",
"outputParam2":"value21"
},
"eventTime":1626197190000
},
"event2":{
"outputParams":{
"outputParam1":"value11",
"outputParam2":"value21"
},
"eventTime":1626197190000
}
},
{
"event1":{
"outputParams":{
"outputParam1":"value10",
"outputParam2":"value20"
},
"eventTime":1626197189000
},
"event2":{
"outputParams":{
"outputParam1":"value10",
"outputParam2":"value20"
},
"eventTime":1626197189000
}
}
],
"subDevices":[
{
"deviceId":"asd453452444",
"properties":[
{
"color":{
"value":"red",
"time":1626197190000
},
"brightness":{
"value":80,
"time":1626197190000
}
},
{
"color":{
"value":"blue",
"time":1626197189000
},
"brightness":{
"value":79,
"time":1626197189000
}
}
],
"events":[
{
"event1":{
"outputParams":{
"outputParam1":"value11",
"outputParam2":"value21"
},
"eventTime":1626197190000
},
"event2":{
"outputParams":{
"outputParam1":"value11",
"outputParam2":"value21"
},
"eventTime":1626197190000
}
},
{
"event1":{
"outputParams":{
"outputParam1":"value10",
"outputParam2":"value20"
},
"eventTime":1626197189000
},
"event2":{
"outputParams":{
"outputParam1":"value10",
"outputParam2":"value20"
},
"eventTime":1626197189000
}
}
]
}
]
}
}
参数说明
| 参数 | 类型 | 说明 | 必选 | 备注 |
|---|---|---|---|---|
| ${deviceId} | string | 设备 ID | 是 | 清除期望属性的设备 ID。 |
| version | string | 协议版本 | 否 | 默认 1.0，且仅有 1.0。 |
| msgId | string | 消息 ID | 是 | 总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。 |
| time | number | 消息时间戳 | 是 | 消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。 |
| data | object | 批量上报的历史数据集合 | 是 | 包含设备自身的批量上报历史数据和子设备的上报历史数据。 |
| data.properties | array | 批量上报的历史属性集合 | 否 | / |
| data.properties[] | object | 批量上报的属性集合 | 是 | 数组按照属性变更时间升序存储，元素的 key 为属性 code，value 为属性值和属性变更时间戳。 |
| data.properties[].${key} | object | 属性上报对象 | 是 | key 为属性的 code。 |
| data.properties[].${key}.time | object | 属性变更时间戳 | 否 | Unix 时间戳，10 位秒级或 13 位毫秒级。 |
| data.properties[].${key}.value | object | 属性上报值 | 是 | 具体的属性值。 |
| data.events | array | 批量上报的历史事件集合 | 否 | / |
| data.events[] | object | 批量上报的事件集合 | 是 | 数组按照事件发生的时间升序存储，元素的 key 为事件 code，value 为事件参数和发生时间。 |
| data.events[].${key} | object | 事件上报对象 | 是 | code 为事件的 code。 |
| data.events[].${key}.time | object | 事件发生时间 | 否 | Unix 时间戳，10 位秒级或 13 位毫秒级。 |
| data.events[].${key}.outputParams | object | 事件输出参数 | 是 | 事件输出的参数集合。 |
| data.subDevices | array | 子设备上报数据列表 | 否 | 当设备为网关时，可以为子设备批量上报数据。每一个列表元素代表一个子设备的数据。 |
| data.subDevices[] | object | 子设备上报数据 | 是 | 每个元素代表一个子设备的数据。 |
| data.subDevices[].deviceId | string | 子设备 ID | 是 | 上报的子设备 ID。 |
| data.subDevices[].properties | array | 子设备批量上报的历史属性集合 | 否 | 结构定义与 data.properties 类似。 |
| data.subDevices[].events | array | 子设备批量上报的历史事件集合 | 否 | 结构定义与 data.events 类似。 |
设备接收消息
云端处理上报后，默认不对上报消息进行响应，除非设备端在上报时显式指定 ack 为 1。
Topic: tylink/${deviceId}/thing/data/history_report_response
{
"msgId":"45lkj3551234001",
"time":1626197189640,
"code":0
}
参数说明
| 参数 | 类型 | 说明 | 必选 | 备注 |
|---|---|---|---|---|
| ${deviceId} | string | 设备 ID | 是 | 历史上报的来源设备 ID。 |
| version | string | 协议版本 | 否 | 默认 1.0，且仅有 1.0。 |
| msgId | string | 消息 ID | 是 | 与对应的历史上报消息的 msgId 保持一致，通过 msgId 来标识应答关系。 |
| time | number | 消息时间戳 | 是 | 消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。 |
| code | number | 响应状态码 | 否 | 0 代表成功，非 0 代表失败，默认 0。 |
状态码说明
| 状态码 | 说明 |
|---|---|
| 0 | 默认状态，代表成功。 |
| 1003 | 数据格式错误。 |
| 2121 | 历史上报部分数据处理失败。 |
| 2122 | 历史上报完全处理失败。 |
| 2123 | 历史上报子设备个数超过限制，目前子设备个数上限不能超过 20 个。 |
| 2124 | 历史数据量超过限制，目前数据量上限不能超过 500。 |
获取模型
设备发送消息
设备向云端发送设备模型查询请求。
Topic：tylink/${deviceId}/thing/model/get
{
"msgId":"45lkj3551234***",
"time":1626197189638,
"data":{
"format":"simple"
}
}
参数说明
| 参数 | 类型 | 说明 | 必选 | 备注 |
|---|---|---|---|---|
| ${deviceId} | string | 设备 ID | 是 | 要查询设备模型的具体设备。 |
| version | string | 协议版本 | 否 | 默认 1.0，且仅有 1.0。 |
| msgId | string | 消息 ID | 是 | 总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。 |
| time | number | 消息时间戳 | 是 | 消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。 |
| data | object | 查询参数 | 否 | - |
| data.format | string | 设备模型的格式类型 | 否 |
|
设备接收消息
云端查询设备的模型定义，然后通过响应消息返回给设备端。
以下示例返回的设备模型定义结构是经过精简后、去除 name、description 等设备侧不关心的描述信息之后的版本。
Topic：tylink/${deviceId}/thing/model/get_response
{
"msgId":"45lkj3551234***",
"time":1626197189640,
"code":0,
"data":{
"modelId":"0000001***",
"services":[
{
"code":"",
"properties":[
{
"abilityId":1,
"code":"foodRemaining",
"accessMode":"ro",
"typeSpec":{
"type":"value",
"min":0,
"max":2000,
"step":1,
"unit":"g",
"scale":0
}
}
],
"events":[
{
"abilityId":101,
"code":"feedEvent",
"outputParams":[
{
"code":"time",
"typeSpec":{
"type":"date"
}
},
{
"code":"quantity",
"typeSpec":{
"type":"value",
"min":0,
"max":2000,
"step":1,
"unit":"g",
"scale":0
}
}
]
}
],
"actions":[
{
"abilityId":101,
"code":"feed",
}
]
}
]
}
}
参数说明
| 参数 | 类型 | 说明 | 必选 | 备注 |
|---|---|---|---|---|
| ${deviceId} | string | 设备 ID | 是 | 查询设备模型的具体设备。 |
| version | string | 协议版本 | 否 | 默认 1.0，且仅有 1.0。 |
| msgId | string | 消息 ID | 是 | 与对应的查询请求消息的 msgId 保持一致，通过 msgId 来标识应答关系。 |
| time | number | 消息时间戳 | 是 | 消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。 |
| code | number | 响应状态码 | 否 |
|
| data | object | 结果 | 否 | 设备模型定义的 JSON 格式。 |
状态码说明
| 状态码 | 说明 |
|---|---|
| 0 | 默认状态，代表成功。 |
| 1001 | 服务异常。 |
| 1002 | 参数不合法。 |
| 1003 | 消息格式错误。 |
| 1004 | 设备不存在。 |
获取期望属性
适用场景
- 设备处于离线状态，无法直接下发指令。希望在云端提供暂存指令的能力，当设备上线时可以主动查询，然后执行状态更新。
- 低功耗类设备周期性的休眠/唤醒。当设备被唤醒时，可以主动查询云端是否有需要执行的指令。
交互示意图
设备发送消息
设备向云端发送获取期望属性值的请求消息。
Topic：tylink/${deviceId}/thing/property/desired/get
{
"msgId":"45lkj3551234001",
"time":1626197189638,
"data":{
"properties":[
"color",
"brightness"
]
}
}
参数说明
| 参数 | 类型 | 说明 | 必选 | 备注 |
|---|---|---|---|---|
| ${deviceId} | string | 设备 ID | 是 | 查询期望属性的设备 ID。 |
| version | string | 协议版本 | 否 | 默认 1.0，且仅有 1.0。 |
| msgId | string | 消息 ID | 是 | 总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。 |
| time | number | 消息时间戳 | 是 | 消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。 |
| data | object | 期望属性查询参数 | 否 | - |
| data.properties | array | 筛选指定的期望属性列表 | 否 | 为空代表返回当前设备所有的期望属性，否则只返回被筛选的属性 Code 列表。 |
设备接收消息
设备接收云端发送的期望属性响应。
Topic：tylink/${deviceId}/thing/property/desired/get_response
{
"msgId":"45lkj3551234001",
"time":1626197189640,
"data":{
"properties":{
"color":{
"value":"red",
"version":1
},
"brightness":{
"value":80,
"version":2
}
}
}
}
参数说明
| 参数 | 类型 | 说明 | 必选 | 备注 |
|---|---|---|---|---|
| ${deviceId} | string | 设备 ID | 是 | 查询期望属性的设备 ID。 |
| version | string | 协议版本 | 否 | 默认 1.0，且仅有 1.0。 |
| msgId | string | 消息 ID | 是 | 总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。 |
| time | number | 消息时间戳 | 是 | 消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。 |
| code | number | 响应状态码 | 否 | 0 代表成功，非 0 代表失败，默认 0。 |
| data | object | 返回结果 | 否 | - |
| data.properties | object | 期望属性集合 | 是 | key 为属性的 Code，value 为属性值和版本号。 |
| data.properties.${key} | object | 期望属性对象 | 是 | 属性 Code。 |
| data.properties.${key}.version | number | 期望属性的版本号 | 是 | 云端每次对期望属性做修改都会导致期望属性版本号自增，清除期望属性时也需要该值。 |
| data.properties.${key}.value | object | 属性期望值 | 是 | 具体的期望值。 |
状态码说明
| 状态码 | 说明 |
|---|---|
| 0 | 默认状态，代表成功。 |
| 1001 | 服务异常。 |
| 1003 | 消息格式错误。 |
清除期望属性
设备发送消息
设备接收期望属性后，更新本地状态成功，然后向云端发送清除期望属性的消息。
Topic：tylink/${deviceId}/thing/property/desired/delete
{
"msgId":"45lkj3551234001",
"time":1626197189600,
"data":{
"properties": {
"color":{
"version":1
},
"brightness":{
"version":2
}
}
}
}
参数说明
| 参数 | 类型 | 说明 | 必选 | 备注 |
|---|---|---|---|---|
| ${deviceId} | string | 设备 ID | 是 | 清除期望属性的设备 ID。 |
| version | string | 协议版本 | 否 | 默认 1.0，且仅有 1.0。 |
| msgId | string | 消息 ID | 是 | 总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。 |
| time | number | 消息时间戳 | 是 | 消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。 |
| data | object | 清除参数 | 是 | - |
| data.properties | object | 清除的期望属性集合 | 是 | key 为属性 code，value 为期望属性值的版本号。 |
| data.properties.${key} | object | 期望属性清除参数 | 是 | 属性 code。 |
| data.properties.${key}.version | number | 期望属性的版本号 | 是 | 当清除期望属性时需要带上查询时获取的版本号。只有当清除请求的版本号等于云端记录的版本号时，才能清除成功。 |
设备接收消息
设备接收云端返回的期望属性删除响应。
Topic：tylink/${deviceId}/thing/property/desired/delete_response
{
"msgId":"45lkj3551234001",
"time":1626197189640,
"code":0
}
参数说明
| 参数 | 类型 | 说明 | 必选 | 备注 |
|---|---|---|---|---|
| ${deviceId} | string | 设备 ID | 是 | 清除期望属性的设备 ID。 |
| version | string | 协议版本 | 否 | 默认 1.0，且仅有 1.0。 |
| msgId | string | 消息 ID | 是 | 总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。 |
| time | number | 消息时间戳 | 是 | 消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。 |
| code | number | 响应状态码 | 否 | 0 代表成功，非 0 代表失败，默认 0。 |
状态码说明
| 状态码 | 说明 |
|---|---|
| 0 | 默认状态，代表成功。 |
| 1001 | 服务异常。 |
该内容对您有帮助吗？
是意见反馈该内容对您有帮助吗？
是意见反馈
关注“涂鸦智能”
涂鸦服务尽在掌握
关注“全球智能商业”
第一时间获取物联网资讯
