功能介绍
用户属性（User Properties）是 MQTT 5.0 新增的特性,允许您在 MQTT 消息中添加自定义的键值对元数据。通过用户属性,您可以在不修改消息载荷的情况下传递额外信息,实现消息路由、数据格式标识、设备信息上报等功能。
腾讯云 MQTT 服务完整支持 MQTT 5.0 用户属性特性,提供稳定可靠的消息传输能力。
特性说明
采用 UTF-8 编码的键值对格式
属性数量不受限制,仅受报文最大长度约束
支持同一键名重复出现
可附加在大部分 MQTT 5.0 控制报文上(详见下文支持的报文类型)
服务端透明转发,不修改属性内容
应用场景
数据格式标识: 在消息中标注数据格式,服务端可直接选择对应的解析器
消息路由: 通过用户属性标记消息的目标系统,实现应用层消息分发
文件传输: 将文件元数据存放在用户属性中,消息载荷直接传输二进制数据
设备信息上报: 连接时携带设备型号、固件版本等信息,便于设备管理和权限控制
操作指南
前提条件
已创建 MQTT 实例
客户端 SDK 支持 MQTT 5.0 协议
连接时配置
const mqtt = require('mqtt')const client = mqtt.connect('mqtt://your-endpoint.mqtt.tencentcloudmq.com:1883', {protocolVersion: 5,properties: {userProperties: {device_type: 'sensor',version: '1.0.0'}}})
发布消息时配置
client.publish('sensor/temperature', '25.6', {qos: 1,properties: {userProperties: {sensor_id: 'TH-001',location: 'room_A'}}})
接收消息并读取
client.on('message', (topic, payload, packet) => {const userProps = packet.properties.userPropertiesconsole.log('用户属性:', userProps)console.log('消息内容:', payload.toString())})
注意事项
性能优化
避免在高频上报消息中携带大量用户属性
合理控制属性数量和大小,减少网络传输开销
安全性
不要在用户属性中传输密码、Token、密钥等敏感凭证
不要传输手机号、身份证号等个人隐私数据
敏感信息应通过加密后再传输
相关说明
支持的报文类型
用户属性可用于以下 MQTT 5.0 控制报文:
报文类型 | 说明 |
CONNECT、CONNACK | 连接请求和响应 |
PUBLISH、PUBACK、PUBREC、PUBREL、PUBCOMP | 消息发布和确认 |
SUBSCRIBE、SUBACK | 订阅请求和响应 |
UNSUBSCRIBE、UNSUBACK | 取消订阅请求和响应 |
DISCONNECT、AUTH | 断开连接和认证 |
WILL PROPERTIES | 遗嘱消息属性 |
版本兼容性
用户属性仅在 MQTT 5.0 协议中可用
如果订阅端使用 MQTT 3.x 协议,服务端会自动剥离用户属性,仅传递消息载荷
建议发布端和订阅端都使用 MQTT 5.0 协议以获得完整功能
常见问题
用户属性会被服务端修改吗?
不会。腾讯云 MQTT 服务仅负责透明转发用户属性,不会修改属性内容。
同一个键可以出现多次吗?
可以。MQTT 5.0 协议允许同一个键名重复出现,接收端会收到包含多个值的数组。
用户属性会影响消息的 QoS 等级吗?
不会。用户属性作为消息的一部分,会按照消息指定的 QoS 等级进行传输。
如何查看消息是否成功携带了用户属性?
您可以在订阅端的消息回调函数中打印
packet.properties.userProperties 来查看接收到的用户属性。
