TBMQ HTTP集成提供了一种通过HTTP协议将设备MQTT消息转发至外部系统的简便方式。 它作为TBMQ与外部应用之间的桥梁，确保数据交换顺畅可靠。
数据流概述TBMQ HTTP集成支持将MQTT消息转发至外部HTTP服务：
- 设备（客户端）发布MQTT消息到匹配集成主题过滤器的主题。
- TBMQ代理接收消息并转发至TBMQ Integration Executor。
- TBMQ Integration Executor处理消息，将其格式化为HTTP请求并转发至外部服务。
- 外部服务接收请求并相应处理数据。
前置条件
设置集成前，请确保：
- 有正在运行的TBMQ实例。
- 有可接收HTTP请求的外部服务（如ThingsBoard Cloud）。
- 有可发布MQTT消息的客户端（如TBMQ WebSocket Client）。
创建ThingsBoard集成
本教程以ThingsBoard作为接收TBMQ HTTP请求的外部服务，也可使用其他兼容HTTP的服务。
按照官方ThingsBoard HTTP集成指南在ThingsBoard Cloud上创建集成。
创建HTTP集成后：
- 打开详情页并启用调试模式以验证数据接收。
- 复制HTTP端点URL，下一步将用到。
创建TBMQ HTTP集成
- 进入集成页面，点击 “+” 创建新集成。
- 选择 HTTP 作为集成类型，点击下一步。
- 在主题过滤器页面点击下一步，订阅默认主题
tbmq/#。 - 在配置步骤，粘贴ThingsBoard集成的端点URL。
- 打开高级设置，将负载内容类型设为
JSON。 - 点击添加保存集成。
可使用“检查连接”按钮发送HEAD请求测试与已配置HTTP端点的连通性。
Topic Filters
Topic filters 定义基于 MQTT 的订阅，并作为 TBMQ HTTP Integration 的触发器。当 broker 收到与 configured topic filters 匹配的消息时，integration 会处理并转发到指定外部系统。
若 integration 配置了如下 topic filter：
1
tbmq/devices/+/status
则匹配该模式的消息都会触发 integration，例如：
1
2
tbmq/devices/device-01/status
tbmq/devices/gateway-01/status
配置
| 字段 | 描述 |
|---|---|
| 仅发送消息负载 | 启用时，传入消息的负载按原样转发。禁用时，发送包含负载及其他属性的JSON对象。 |
| 端点URL | 发送HTTP请求的外部服务URL。 |
| 请求方法 | 定义请求方式。支持：GET、POST、PUT、DELETE。 |
| 凭证 | 支持的认证选项： |
| 匿名 – 无需认证。 | |
基本认证 – 使用 用户名 和 密码 认证。 |
|
| PEM认证 – 使用PEM证书认证。 | |
| Headers | 添加到HTTP请求头的键值对集合。 |
| 负载内容类型 | 定义请求体格式。支持：JSON、Text、Binary (Base64)。 |
| 解析失败时按二进制发送 | 启用时，JSON 或 Text 解析失败的消息将作为二进制负载发送。禁用时，失败消息不会发送。 |
| 读取超时 | 请求在超时前等待响应的最长时间。 |
| 最大并行请求数 | 限制并发HTTP请求数。 |
| 最大响应大小 | 定义允许的传入响应最大大小。 |
| Metadata | 可用于额外处理的自定义元数据。 |
事件
TBMQ 为 integration 相关事件提供日志，便于调试和排查 integration 行为。 以下为三种「Event」类型：
-
Lifecycle Events – 记录
Started、Created、Updated、Stopped等事件 -
Statistics – 提供 integration 性能洞察，包括已处理消息数和错误数
-
Errors – 记录与认证、超时、payload 格式或外部服务连通性相关的失败
Lifecycle Events – 记录 Started、Created、Updated、Stopped 等事件
Statistics – 提供 integration 性能洞察，包括已处理消息数和错误数
Errors – 记录与认证、超时、payload 格式或外部服务连通性相关的失败
发送上行消息
发送消息请按以下步骤：
- 进入WebSocket Client页面。
- 选择“WebSocket Default Connection”或其他可用连接，点击连接。确保“连接状态”显示为
Connected。 - 将“主题”字段设为
tbmq/http-integration，以匹配集成的主题过滤器tbmq/#。 - 点击发送图标发布消息。
- 成功后，消息应出现在“消息”表中。
消息发布后：
- 在 ThingsBoard Cloud 中打开HTTP集成详情。
- 进入事件标签页。
- 若配置正确，应看到状态为 ‘OK’ 的事件及类似如下的消息负载：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
"payload": {
"temperature": 25
},
"topicName": "tbmq/http-integration",
"clientId": "tbmq_7QUvZzow",
"eventType": "PUBLISH_MSG",
"qos": 1,
"retain": false,
"tbmqIeNode": "tbmq_ie_node",
"tbmqNode": "tbmq_node",
"ts": 1742553324248,
"props": {},
"metadata": {
"integrationName": "HTTP integration"
}
}
消息说明：
- payload：MQTT消息内容。
- topicName：发布消息的MQTT主题。
- clientId：发布消息的MQTT客户端ID。
- eventType：MQTT事件类型，此处为已发布消息（当前唯一支持的类型）。
- qos：传入消息使用的服务质量等级。
- retain：表示消息是否为保留MQTT消息。
- tbmqIeNode：处理消息的Integration Executor服务节点ID。
- tbmqNode：接收消息的TBMQ代理节点ID。
- ts：接收消息时的时间戳（毫秒）。
- props：MQTT5.0用户属性或其他MQTT属性。
- metadata：从集成配置添加的额外元数据，默认包含处理消息的集成名称。
