跳至主要內容

转发规则

BladeX大约 10 分钟featurerule

概念说明

转发规则用于将设备数据转发到第三方系统或从第三方系统接收数据，实现与外部平台的数据互通。支持 HTTP、MQTT、Database 等多种转发目标类型，可配置双向数据流（输入/输出），满足各种数据集成场景需求。

一、创建转发规则

  1. 登录物联网平台，选择【规则引擎】>【转发规则】，进入转发规则管理页面。
  2. 点击【创建转发规则】，填写转发名称、转发编码等基础信息。
  3. 其中转发编码支持自动生成，点击输入框右侧的【自动生成】按钮即可。
  4. 选择需要关联的产品，转发规则将应用于该产品下的设备数据。
  5. 创建成功后，可以在转发规则列表中查看。
创建转发规则
创建转发规则

二、配置数据流向

转发规则支持两种数据流向：

1. 输入

将数据从平台转发到目标系统，例如将设备上报的数据推送到业务系统。

  • 适用场景：数据分析、业务处理、第三方集成
  • 数据来源：设备上报数据、平台产生的事件数据
  • 触发时机：实时触发，数据产生即转发

2. 输出

从目标系统获取数据并输出到平台，例如从外部系统拉取配置数据。

  • 适用场景：配置同步、外部数据导入、数据回流
  • 数据来源：外部 HTTP 接口、MQTT 主题、数据库表
  • 触发时机：定时拉取或事件触发
配置数据流向
配置数据流向

三、选择目标类型并配置

1. HTTP 转发

通过 HTTP/HTTPS 协议将数据转发到指定的 Web 服务。请求 URL 未带协议前缀时平台会自动补全为 http://，未配置请求方法时默认使用 POST。

配置项说明：

  • 请求方法：支持 GET、POST、PUT、DELETE，默认 POST
  • 请求地址：目标服务的完整 URL 地址，支持 ${variable} 占位符
  • 请求头：自定义 HTTP Headers（key-value 列表），如 Content-Type、Authorization，支持 ${variable} 占位符
  • 请求参数：URL 查询参数（key-value 列表），自动拼接到 URL 末尾，支持 ${variable} 占位符
  • 请求体类型：支持 json、formdata、none 三种格式，默认按 json 处理
  • 请求体内容：具体的请求数据，支持 ${variable} 占位符；json 类型留空时自动使用平台默认 Payload（结构见下方 MQTT 章节的「默认 Payload 结构」）

配置步骤：

  1. 选择【目标类型】为【HTTP】。
  2. 填写请求地址，例如：https://api.example.com/devices/${productKey}/${deviceName}/data
  3. 选择请求方法，通常使用 POST。
  4. 配置请求头，添加认证信息等。
  5. 配置请求体，定义数据格式和内容（留空则平台自动注入完整设备数据）。
  6. 点击【保存】完成配置。
HTTP转发配置
HTTP转发配置

占位符变量

请求 URL、请求头、请求参数、请求体均支持 ${变量名} 语法，运行时由平台自动替换为设备实时数据，便于将设备具体参数注入到第三方接口调用中。

类别变量说明
设备信息${deviceId}设备 ID
设备信息${deviceName}设备名称
设备信息${productKey}产品标识
设备信息${tenantId}租户编号
时间信息${reportTime}设备数据上报时间（yyyy-MM-dd HH:mm:ss）
时间信息${systemTime}平台系统时间（yyyy-MM-dd HH:mm:ss）
规则信息${ruleId} / ${ruleCode} / ${ruleName}转发规则 ID / 编码 / 名称
转发信息${actionId} / ${dataFlow}动作 ID / 数据流向（input-输入、output-输出）
属性数据${properties}当前上报的全部属性值（JSON 对象）
属性数据${<属性标识符>}当前上报的具体属性值，如 ${temperature}、${humidity}
事件数据${events}当前上报的事件数据

占位符容错机制

若占位符对应的变量缺失（如某次上报未包含某个属性），平台会保留原始占位符而非中断转发，避免因偶发数据缺失影响整条转发链路。建议下游接口对此场景做兼容处理。

实战示例

示例一：URL 中带设备路径参数

https://api.example.com/devices/${productKey}/${deviceName}/report

示例二：请求头携带租户标识与认证信息

KeyValue
AuthorizationBearer your-token
X-Tenant-Id${tenantId}
X-Device-Name${deviceName}

示例三：查询参数附带规则与时间信息

KeyValue
ruleCode${ruleCode}
reportTime${reportTime}
flow${dataFlow}

示例四：JSON 请求体引用具体属性

{
  "device": "${deviceName}",
  "product": "${productKey}",
  "temperature": ${temperature},
  "humidity": ${humidity},
  "tenantId": "${tenantId}",
  "reportTime": "${reportTime}"
}

示例五：表单（formdata）请求体

将【请求体类型】设为 formdata，并以 key-value 形式配置：

KeyValue
deviceName${deviceName}
productKey${productKey}
value${temperature}

平台会按 application/x-www-form-urlencoded 编码发送，等效于 deviceName=xxx&productKey=yyy&value=25.6。

2. MQTT 转发

通过 MQTT 协议将数据发布到指定的 MQTT Broker。平台内部按 host:port:username 维护客户端连接池，相同连接信息的转发规则会复用同一个客户端，并默认开启自动重连（10 秒连接超时，5 秒重连间隔）。

配置项说明：

  • 客户端ID：MQTT 客户端标识，留空则平台自动生成（格式：blade-forward-{时间戳}）；若手动配置请确保全局唯一，避免被 Broker 踢线
  • 服务器地址：MQTT Broker 的主机地址（必填）
  • 服务器端口：MQTT 服务端口，默认 1883
  • 用户名：MQTT 连接认证用户名（可选）
  • 密码：MQTT 连接认证密码（可选）
  • 主题：数据发布的 MQTT Topic，留空则使用平台默认 Topic（见下方说明）

配置步骤：

  1. 选择【目标类型】为【MQTT】。
  2. 填写 MQTT Broker 的连接信息。
  3. 配置客户端 ID，建议使用有意义的标识，未填写时平台自动生成。
  4. 填写认证信息（如果 Broker 需要）。
  5. 指定数据发布的主题（不填则使用默认 Topic，按设备自动路由）。
  6. 点击【保存】完成配置。
MQTT转发配置
MQTT转发配置

默认 Topic

未指定主题时，平台会发布到固定格式的默认 Topic：

/blade/ext/forward/{productKey}/{deviceName}/data

订阅方可使用 MQTT 通配符按产品或设备维度监听，例如订阅某产品下所有设备的转发数据：

/blade/ext/forward/{productKey}/+/data

自定义主题不支持占位符

与 HTTP 转发不同，MQTT 自定义主题为字面量直发，不会对 ${variable} 进行替换。 若需按设备维度隔离主题，请保持主题留空使用默认 Topic，由平台自动按 productKey/deviceName 路由；或在订阅端使用通配符 + / # 进行多设备聚合监听。

默认 Payload 结构

发布到 MQTT Broker 的消息体为统一的 JSON 结构（HTTP 转发未自定义请求体时同样使用此结构）：

{
  "deviceId": 1782338839768817665,
  "deviceName": "27F86M286eC",
  "productKey": "JkerjK97oub",
  "tenantId": "000000",
  "reportTime": "2026-04-29 10:00:00",
  "systemTime": "2026-04-29 10:00:01",
  "ruleId": "1789876543210000001",
  "ruleCode": "forward_rule_demo",
  "ruleName": "示例转发规则",
  "actionId": "1789876543210000002",
  "dataFlow": "input",
  "properties": {
    "temperature": 25.6,
    "humidity": 60
  },
  "propertyCurrentValues": { "temperature": 25.6, "humidity": 60 },
  "propertyLastValues": { "temperature": 25.4, "humidity": 59 },
  "propertyLatestValues": { "temperature": 25.6, "humidity": 60 },
  "events": [],
  "eventData": [],
  "variables": {}
}

字段说明：

字段说明
deviceId / deviceName / productKey / tenantId触发设备的基础信息
reportTime / systemTime设备上报时间 / 平台系统时间
ruleId / ruleCode / ruleName触发的转发规则信息
actionId / dataFlow转发动作 ID 与数据流向（input-输入、output-输出）
properties本次上报的属性值（精简别名）
propertyCurrentValues本次上报的属性值（完整字段名，与 properties 等价）
propertyLastValues上一次上报的属性值，可用于变化对比
propertyLatestValues截至当前的最新属性快照
events / eventData本次上报的事件数据
variables规则上下文中的扩展变量

连接资源管理

平台会按 host:port:username 复用 MQTT 客户端连接，不同转发规则若指向同一 Broker 与同一账号，将自动共用一个连接，避免连接数膨胀。

3. Database 转发

将数据直接写入到关系型数据库。平台默认使用 HikariCP 连接池管理外部数据源，按 JDBC URL 复用连接。

配置项说明：

  • 驱动类：数据库驱动类名，如 com.mysql.cj.jdbc.Driver
  • JDBC地址：数据库连接字符串，如 jdbc:mysql://localhost:3306/iot_db
  • 用户名：数据库连接用户名
  • 密码：数据库连接密码
  • 表名：数据写入的目标表名，留空则写入默认表 iot_device_forward_data

配置步骤：

  1. 选择【目标类型】为【Database】。
  2. 填写数据库驱动类名。
  3. 配置 JDBC 连接地址，例如：jdbc:mysql://localhost:3306/iot_db
  4. 填写数据库认证信息。
  5. 指定目标表名（不填则使用默认表 iot_device_forward_data）。
  6. 点击【保存】完成配置。
Database转发配置
Database转发配置

默认表与字段说明

未指定表名时，平台会向默认表 iot_device_forward_data 写入数据。请提前在目标数据库中创建该表，字段含义如下：

字段名类型说明
idbigint主键，雪花 ID，由平台自动生成
tenant_idvarchar(12)租户编号
device_namevarchar(255)设备名称
product_keyvarchar(255)产品标识
rule_idvarchar(64)转发规则 ID
rule_codevarchar(255)转发规则编码
data_flowvarchar(50)数据流向：input-输入、output-输出
payloadtext转发数据，JSON 格式
create_timedatetime写入时间
is_deletedint逻辑删除标识，写入时固定为 0

自定义表名

若需要按业务拆表（如按产品、按规则建表），可在表名中填入自定义名称，但该表的字段结构必须与上表一致，否则写入会失败。

默认表建表语句

可直接复制以下语句在目标数据库中执行：

DROP TABLE IF EXISTS `iot_device_forward_data`;
CREATE TABLE `iot_device_forward_data` (
  `id` bigint NOT NULL COMMENT '主键',
  `tenant_id` varchar(12) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NULL DEFAULT '000000' COMMENT '租户ID',
  `device_name` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NULL DEFAULT NULL COMMENT '设备名称',
  `product_key` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NULL DEFAULT NULL COMMENT '产品标识',
  `rule_id` varchar(64) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NULL DEFAULT NULL COMMENT '转发规则ID',
  `rule_code` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NULL DEFAULT NULL COMMENT '转发规则编码',
  `data_flow` varchar(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NULL DEFAULT NULL COMMENT '数据流向:input-输入,output-输出',
  `payload` text CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NULL COMMENT '转发数据(JSON)',
  `create_time` datetime NULL DEFAULT NULL COMMENT '写入时间',
  `is_deleted` int NULL DEFAULT 0 COMMENT '是否已删除',
  PRIMARY KEY (`id`) USING BTREE,
  INDEX `idx_tenant_id`(`tenant_id`) USING BTREE,
  INDEX `idx_device_name`(`device_name`) USING BTREE,
  INDEX `idx_product_key`(`product_key`) USING BTREE,
  INDEX `idx_rule_code`(`rule_code`) USING BTREE,
  INDEX `idx_create_time`(`create_time`) USING BTREE
) ENGINE = InnoDB CHARACTER SET = utf8mb4 COLLATE = utf8mb4_general_ci COMMENT = '设备转发数据表';

其他数据库适配

若目标库非 MySQL（如 PostgreSQL、Oracle、达梦、人大金仓等），请按以下规则映射字段类型后再执行：

  • bigint → PostgreSQL bigint、Oracle NUMBER(19)、达梦 BIGINT
  • varchar(N) → PostgreSQL varchar(N)、Oracle VARCHAR2(N)
  • text → PostgreSQL text、Oracle CLOB
  • datetime → PostgreSQL timestamp、Oracle TIMESTAMP
  • int → PostgreSQL integer、Oracle NUMBER(10)

四、设置优先级

  1. 在规则编辑页面，配置【优先级】字段。
  2. 当多个转发规则应用于同一产品时，按优先级顺序执行。
  3. 数值越大优先级越高，合理规划可实现数据的多级转发。

五、启用与监控

  1. 转发规则配置完成后，通过列表页面的开关启用规则。
  2. 启用后规则立即生效，开始转发数据。
  3. 可以通过平台日志查看转发执行情况。
  4. 监控转发成功率和失败原因，及时处理异常。
启用监控规则
启用监控规则

注意

  • HTTP 转发时请确保目标服务地址可访问，避免网络隔离问题。
  • MQTT 转发需要保证客户端 ID 的唯一性，避免连接冲突。
  • Database 转发需要确保数据库表结构与数据字段匹配。
  • 不同目标类型的配置互不兼容，切换目标类型会清空已有配置。
  • 转发失败时数据可能丢失，建议配置重试机制或备用方案。
上次编辑于:
贡献者: smallchill