基本概念
消息增强规则是 MQTT 服务端支持的一种配置化能力。通过设置规则，您可以在消息发布时，根据配置的条件动态地为消息附加 MQTT 5.0 的属性。规则支持通过控制台或云 API 进行灵活配置与管理。
一条消息增强规则语句逻辑上包含两部分：
Conditions（条件）：规则触发的条件，如：当消息主题匹配 test/topic时
Actions（动作）：条件满足后执行的操作，如：为消息添加Message Expiry Interval = 30
限制与约束
每个集群最多支持10条消息增强规则，如有更多配额需求，请联系我们。
规则具备优先级设置，优先级数值越小则优先级越高。服务端会按照消息增强规则列表页的规则顺序执行，高优先级规则将覆盖低优先级规则中的动作；如果规则配置冲突，以优先级排序更高的为准。
若使用变量替换后字段内容超出长度或大小限制，服务端将自动对超出部分截断处理。
配置消息增强规则
新建规则
1. 登录消息队列 MQTT 版控制台 > 集群管理 > 消息增强规则，单击左上角新建规则按钮，进行消息增强规则的配置。
2. 根据实际情况填写规则基本信息、匹配条件及具体增强规则的配置，具体字段填写参考下文 填写说明。填写完毕后单击创建规则，如创建时开启了基本信息中的“是否启用该规则”按钮，创建后此规则将在 1 分钟内生效；如创建时未选择开启，也可在规则创建后通过列表页进行启用。
3. 创建成功的规则可在列表页进行查看和管理，对于处于“激活”状态的规则不支持删除。
规则优先级
1. 单击调整优先级按钮可调整规则执行的顺序，服务端会按照当前列表的规则顺序执行；如果规则配置冲突，以优先级排序更高的为准。
2. 通过拖拽每行规则前的
填写说明
展示名称 | API 参数 | 说明 | 是否必填 | 示例值 |
规则名称 | RuleName | 设置规则名称。需符合命名规则：3-64个字符，支持中文、字母、数字、“-”及“_”。 | 是 | “rule001” |
描述 | Remark | 设置规则描述，不得超过128个字符。 | 否 | “设定过期时间” |
用户名 | username | 填写单个用户名或单条资源表达式，支持使用通配符和规则变量，为 "*" 表示支持所有用户名 | 是 | "user*" |
客户端 ID | clientId | 填写单条资源表达式，支持使用通配符和规则变量，为 "*"表示支持所有客户端。 | 是 | "sensor*" |
Topic | topic | 填写单条资源表达式，支持使用通配符和规则变量，为 "*"表示支持所有 Topic。 | 是 | "home/room1/*" |
Message Expiry Interval | messageExpiryInterval | 设定消息的过期时间，单位为秒。必须为正整数，取值范围为 0–259200 秒（即 0–72 小时），不允许填0。 | 否 | 3600（表示1小时后过期） |
Response Topic | responseTopic | 指定响应主题，必须为有效的UTF-8 字符串，长度不超过 256 个字符，不得包含通配符“+”或“#”。支持使用规则变量替换。 | 否 | "client/response/123" |
Correlation Data | correlationData | 用于关联请求与响应的数据字段，必须为有效的UTF-8 字符串，总大小不超过 8KB。支持使用规则变量替换。 | 否 | "request-20251031" |
User Properties | userProperty | 自定义用户属性列表，必须为有效的UTF-8 字符串，每个属性值总大小（key-value对）不超过 8KB，最多添加10个用户属性。支持使用规则变量替换。 | 否 | [{"key":"env","value":"production"}，{"key":"version","value":"1.1.1"}] |
通配符替换
用户名
username 参数支持下列通配符：
通配符/Wildcard | 语义 |
? | 任何一个字符。 |
* | 任意个字符。 |
客户端 ID
clientId 参数支持下列通配符：
通配符/Wildcard | 语义 |
? | 任何一个字符。 |
* | 任意个字符。 |
Topic
topic 参数支持下列通配符：
通配符/Wildcard | 语义 |
+ | 与 MQTT 协议 Topic Filter Wildcard 一致。 |
# | 与 MQTT 协议 Topic Filter Wildcard 一致。 |
? | 任何一个字符。 |
* | 任意个字符。 |
变量替换
使用方法
在输入框内输入
${，将自动展示系统默认的规则变量替换列表。
支持参数
支持规则变量替换的参数有：
topic
clientId
username
responseTopic
correlationData
userProperty
注意：
在规则执行时，
${Variable}将被动态替换为对应的真实值；若变量不存在，则替换为空字符串。请在使用前确认变量有效性。规则变量
客户端变量字段
变量名/Variable | 语义 |
InstanceID | MQTT 实例 ID |
ClientId | MQTT Client ID |
Username | MQTT 客户端连接 Username |
Password | MQTT 客户端连接 Password |
Clientip | MQTT 客户端 IP 地址 |
Certificate.Pem | 客户端证书的 PEM 格式内容 |
Certificate.ChainSn | 证书链的序列号 |
证书主题字段
变量名/Variable | 语义 |
Certificate.Subject.Organization | 证书主题 - 组织名称 |
Certificate.Subject.OrganizationalUnit | 证书主题 - 组织单元 |
Certificate.Subject.State | 证书主题 - 州/省 |
Certificate.Subject.CommonName | 证书主题 - 通用名称 |
Certificate.Subject.SerialNumber | 证书主题 - 序列号 |
Certificate.Subject.Title | 证书主题 - 头衔 |
Certificate.Subject.Surname | 证书主题 - 姓氏 |
Certificate.Subject.GivenName | 证书主题 - 名字 |
Certificate.Subject.Initials | 证书主题 - 缩写 |
Certificate.Subject.Pseudonym | 证书主题 - 别名 |
Certificate.Subject.GenerationQualifier | 证书主题 - 代际限定符 |
Certificate.Subject.DistinguishedNameQualifier | 证书主题 - 可辨别名称限定符 |
Certificate.Subject.Country | 证书主题 - 国家/地区代码 |
证书颁发者字段
变量名/Variable | 语义 |
Certificate.Issuer.Organization | 证书颁发者 - 组织名称 |
Certificate.Issuer.OrganizationalUnit | 证书颁发者 - 组织单元 |
Certificate.Issuer.State | 证书颁发者 - 州/省 |
Certificate.Issuer.CommonName | 证书颁发者 - 通用名称 |
Certificate.Issuer.SerialNumber | 证书颁发者 - 序列号 |
Certificate.Issuer.Title | 证书颁发者 - 头衔 |
Certificate.Issuer.Surname | 证书颁发者 - 姓氏 |
Certificate.Issuer.GivenName | 证书颁发者 - 名字 |
Certificate.Issuer.Initials | 证书颁发者 - 缩写 |
Certificate.Issuer.Pseudonym | 证书颁发者 - 别名 |
Certificate.Issuer.GenerationQualifier | 证书颁发者 - 代际限定符 |
Certificate.Issuer.DistinguishedNameQualifier | 证书颁发者 - 可辨别名称限定符 |
Certificate.Issuer.Country | 证书颁发者 - 国家/地区代码 |
替代名称字段
变量名/Variable | 语义 |
Certificate.Subject.AlternativeName.RFC822Name | 主题备用名称 - 电子邮件地址 |
Certificate.Subject.AlternativeName.DNSName | 主题备用名称 - DNS 域名 |
Certificate.Subject.AlternativeName.DirectoryName | 主题备用名称 - 目录名称 |
Certificate.Subject.AlternativeName.UniformResourceIdentifier | 主题备用名称 - 统一资源标识符 |
Certificate.Subject.AlternativeName.IPAddress | 主题备用名称 - IP 地址 |
Certificate.Issuer.AlternativeName.RFC822Name | 颁发者备用名称 - 电子邮件地址 |
Certificate.Issuer.AlternativeName.DNSName | 颁发者备用名称 - DNS 域名 |
Certificate.Issuer.AlternativeName.DirectoryName | 颁发者备用名称 - 目录名称 |
Certificate.Issuer.AlternativeName.UniformResourceIdentifier | 颁发者备用名称 - 统一资源标识符 |
Certificate.Issuer.AlternativeName.IPAddress | 颁发者备用名称 - IP 地址 |
