EMQX 桥接管理 API 增强：为 `/actions_summary` 与 `/sources_summary` 返回新增 `tags` 字段

EMQX 桥接管理 API 增强为/actions_summary与/sources_summary返回新增tags字段【免费下载链接】emqxThe most scalable and reliable MQTT broker for AI, IoT, IIoT and connected vehicles项目地址: https://gitcode.com/gh_mirrors/em/emqx本文基于 EMQX 开源仓库的变更记录 changes/ee/feat-15371.en.md 展开介绍桥接Bridge v2管理 API 的一次向后兼容增强GET /actions_summary、GET /sources_summary的返回项中新增tags字段同时GET /actions/:id返回的 fallback actions 引用条目中也补充了被引用 Action 的tags。读完本文你将掌握该字段在哪些接口生效、返回结构是什么样、底层实现位于哪些模块以及如何通过测试用例验证这一行为。变更背景为桥接资源引入标签分类EMQX 的规则引擎与桥接体系在 v2 架构下统一管理两类桥接资源Actions动作消息处理链中的输出动作例如转发到 Kafka、HTTP 服务、数据库等Sources数据源消息的输入来源例如从 MQTT、Kafka 等订阅数据并注入规则引擎。这两类资源在创建时都支持tags标签字段用于按业务维度对资源进行分组、筛选和检索。在 apps/emqx_bridge/src/schema/emqx_bridge_v2_schema.erl 中top_level_common_action_keys/0与top_level_common_source_keys/0均将tags列为资源的顶层公共键与connector、description、enable、resource_opts等并列top_level_common_action_keys() - [ connector, tags, description, created_at, last_modified_at, enable, parameters, resource_opts ].top_level_common_source_keys()的定义与之对称同样包含tags。这意味着标签是 Action 与 Source 共有的、位于配置顶层的一个通用属性。此前的增强点在于虽然资源创建/详情接口已经能看到tags但汇总类接口/actions_summary、/sources_summary和fallback actions 引用中并未透出标签信息。本变更补齐了这一缺口让基于标签的管理、统计与前端展示成为可能。变更内容一览接口变更前变更后GET /actions_summary返回项不含tags每个 Action 的返回项新增tags字段GET /sources_summary返回项不含tags每个 Source 的返回项新增tags字段GET /actions/:idfallback actions引用类型kind reference的 fallback action 仅含type、name引用条目中补充被引用 Action 的tags说明/actions_summary与/sources_summary的返回结构一致均为资源列表而 fallback actions 仅存在于 Actions 上Sources 没有 fallback 概念源码 emqx_bridge_v2_api.erl 中add_fallback_actions_references/2对?ROOT_KEY_SOURCES直接原样返回。汇总接口/actions_summary与/sources_summary返回tags接口入口与查询参数这两个接口定义在桥接管理 API 模块 apps/emqx_bridge/src/emqx_bridge_v2_api.erl 中路由注册如下/actions_summary(get, #{query_string : QS} Request) - ... /sources_summary(get, #{query_string : QS} Request) - ...它们都支持only_global查询参数当未指定命名空间即请求落在全局命名空间且only_global不为true时返回集群中所有命名空间的资源否则仅返回当前命名空间下的资源见 emqx_bridge_v2_api.erl 与 L997-L1004。返回结构从实现summary_v8/2emqx_bridge_v2_api.erl可以看到每个汇总项现在包含如下字段{ node: emqx127.0.0.1, namespace: default, type: kafka, name: my_kafka_action, description: , tags: [production, log], enable: true, created_at: ..., last_modified_at: ..., status: connected, status_reason: ... }其中关键实现如下emqx_bridge_v2_api.erlCreatedAt maps:get(created_at, RawConfig, undefined), LastModifiedAt maps:get(last_modified_at, RawConfig, undefined), Description maps:get(description, RawConfig, ), Tags maps:get(tags, RawConfig, []), IsEnabled maps:get(enable, RawConfig, true), maps:merge( #{ node node(), namespace Namespace, type Type, name Name, description Description, tags Tags, enable IsEnabled, created_at CreatedAt, last_modified_at LastModifiedAt }, format_bridge_status_and_error(#{status Status, error Error}) )几个要点tags直接从该资源的原始配置RawConfig中读取缺省值为空列表[]返回项同时包含status资源健康状态以及可选的status_reason由format_bridge_status_and_error/1处理仅在存在error时出现整个汇总数据通过集群 BPAPIemqx_bridge_proto_v9:summary/4超时 15 秒从各节点聚合后合并输出。调用示例# 查看所有 Action 的汇总信息含 tags curl -u admin:public http://localhost:18083/api/v5/actions_summary # 查看所有 Source 的汇总信息含 tags curl -u admin:public http://localhost:18083/api/v5/sources_summary从源码结构看tags字段将随同type、name、status一起出现在每个汇总条目中前端可在资源列表中直接展示标签徽标或按标签过滤。详情接口GET /actions/:id的 fallback actions 补充tagsfallback actions 是什么在 EMQX 规则引擎中Action 可以配置fallback_actions回退动作当主 Action 执行失败时按顺序尝试回退动作提高消息投递的容错性。fallback 有两种形态reference引用指向另一个已存在的 Action例如{kind: reference, type: kafka, name: backup_kafka}内联定义如 republish 等直接内嵌的配置。此前GET /actions/:id返回的引用型 fallback 条目只包含type与name调用方若想展示被引用 Action 的标签需要再发一次详情请求。本次变更直接在引用条目中附带被引用 Action 的tags。实现位置这一行为由enrich_fallback_actions_info/2完成emqx_bridge_v2_api.erlenrich_fallback_actions_info(Namespace, Info) - emqx_utils_maps:update_if_present( fallback_actions, fun(FBAs0) - lists:map( fun (#{kind : reference, type : T, name : N} FBA) - Tags get_raw_config(Namespace, [actions, T, N, tags], []), FBA#{tags Tags}; (A) - %% Republish A end, FBAs0 ) end, Info ).要点解读仅对kind reference的条目生效内联定义注释中标注的 Republish 等保持原样被引用 Action 的tags从原始配置树[actions, Type, Name, tags]中读取不存在则为[]该函数在本地节点执行注释明确Called locally, not during RPC避免跨节点二次查询。返回示例假设存在一个名为backup_kafka、带tags: [backup]的 Kafka Action则GET /actions/:id针对引用它的 Action返回的片段为{ fallback_actions: [ { kind: reference, type: kafka, name: backup_kafka, tags: [backup] } ] }测试用例佐证仓库测试 apps/emqx_bridge/test/emqx_bridge_v2_api_SUITE.erl 对本次变更提供了完整覆盖创建带标签的资源L760-L801测试同时覆盖 actions 与 sources 两条路径创建时传入tags [tag1]随后调用summarize_actions_api/0或summarize_sources_api/0校验汇总结果。fallback 引用携带 tagsL2462-L2516先创建被引用的 Action再创建带fallback_actions引用kind reference的 Action断言创建HTTP 201与更新HTTP 200响应中的fallback_actions引用条目均包含tags : [tag1]汇总接口返回的两个 Action 均带tags字段被引用 Action 的返回项包含referenced_as_fallback_action_by列出引用它的 Actiontype、name而引用方该项为空列表。可见标签透出与谁在引用我的关联信息是一同引入的便于运维侧理解 Action 之间的依赖关系。兼容性与注意事项向后兼容tags是新增返回字段不影响既有字段与响应状态码未设置标签的资源返回空数组[]。Sources 无 fallback/sources_summary仅新增tagsSources 不涉及 fallback actions 相关逻辑add_fallback_actions_references/2 对 Sources 直接返回。集群聚合汇总接口依赖节点间 BPAPI v9 协议若集群中存在旧版本节点可能无法获得完整字段升级时建议整集群保持一致。标签的写入tags属于资源顶层配置可在创建/更新 Action 或 Source 时通过 API 或配置文件如emqx_bridge应用的配置设置本次变更只是将其在只读的汇总/详情接口中透出。小结本次变更为 EMQX 的桥接资源管理补齐了标签信息的最后一块拼图GET /actions_summary、GET /sources_summary与GET /actions/:idfallback 引用现在都会返回tags字段使基于标签的资源分组、检索与依赖关系展示成为可能。实现集中在 apps/emqx_bridge/src/emqx_bridge_v2_api.erl 的summary_v8/2与enrich_fallback_actions_info/2两个函数中并通过 apps/emqx_bridge/test/emqx_bridge_v2_api_SUITE.erl 的用例加以固化。若你正在基于 Dashboard 或自建管理端消费这些接口可直接利用新增的tags字段完善资源列表的展示与筛选能力。【免费下载链接】emqxThe most scalable and reliable MQTT broker for AI, IoT, IIoT and connected vehicles项目地址: https://gitcode.com/gh_mirrors/em/emqx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考