Metabase API 破坏性变更全解析v0.49.0 – v0.64.0从 MBQL 4 迁移、权限图重构到 Notification 新架构【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase本文基于仓库中的 API changelog系统梳理 Metabase 自 0.49.0 至 0.64.0 各版本对 REST API 接口所做的破坏性变更。面向集成开发者、脚本维护者与升级实施者帮助你理解每一个变更的动机、新旧接口的对应关系、以及迁移时的注意点从而在升级 Metabase 时提前规避集成故障。为什么需要关注 API 破坏性变更Metabase 的 REST API 是自托管实例、嵌入式分析与自动化脚本与产品交互的主要通道。Metabase 在持续演进过程中会出于架构升级、安全加固与产品重构的需要对已有接口做不向后兼容的调整有的接口被重命名、有的从 GET 改为 POST、有的被整体移除并替换为新的子系统。本文档覆盖 0.49.0 到 0.64.0 的变更记录其中含多个需要开发者主动迁移的关键节点0.57.0MBQL 查询序列化从 MBQL 4 切换到 MBQL 5影响所有通过 API 读写 Carddataset_query的集成0.54.0告警系统从 legacy pulse 基础设施迁移到新的 notification 系统/api/alert大部分端点下线0.50.0权限图permissions graph数据结构发生根本性重构脚本化权限管理的代码需要重写0.55.0/api/util/*下的一批工具端点集中搬迁到新的领域化路径0.64.0Action 预填值接口由 GET 改为 POST且 bug-report 接口收紧。建议集成方在升级前通读本清单并对脚本做一次接口健康检查。同时Metabase 提供了 OpenAPI 规格文件GET /api/docs/openapi.json可作为校验接口签名变更的权威依据其实现位于 src/metabase/api/docs.clj。Metabase 0.64.0bug-report 收紧与 Action 预填值接口迁移0.64.0 是本清单中变更最密集的一个版本包含三组互不相关的破坏性变更。1.POST /api/slack/bug-report的请求模型收紧从 0.64.0 起POST /api/slack/bug-report要求必须先启用 bug 报告功能通过环境变量MB_BUG_REPORTING_ENABLED。同时请求体内的diagnosticInfo.reporter字段语义发生改变该字段现在是一个布尔值true将报告归属到当前已认证用户false或省略该字段以匿名方式提交报告。旧的{ name: ..., email: ... }对象形式仍然被接受并会被视为true处理但其内部的 name 与 email 会被忽略。请求体会针对一组固定的 key 进行校验未声明的 key 会被直接丢弃。这一变更是安全与隐私导向的通过固定 key 白名单与显式归属声明避免任意字段被注入到报告内容中同时保证匿名提交路径的确定性。该变更同时回溯到了 0.58 及之后的维护版本详见下文各小版本条目意味着所有仍在接收 0.58.x–0.63.x 安全更新的实例也会同步生效。相关后端实现位于 bug-reporting 模块路由挂载可见于 src/metabase/api_routes/routes.clj/bug-reporting前缀。2. 自托管环境必须显式启用 transforms自 0.64.0 起自托管self-hosted环境在通过 API 使用 transforms数据变换功能之前必须显式开启该能力。管理员可以通过两种方式启用在Data Studio界面中开启设置环境变量MB_TRANSFORMS_ENABLED为true。此前默认可用、无需额外配置的行为被移除。这一改动让 transforms 成为opt-in能力便于自托管部署按需控制功能面。仓库中 transforms 的实现分布于 src/metabase/transforms、src/metabase/transforms_base 与 src/metabase/transforms_rest 等命名空间API 层位于transforms_rest。3. Action 表单预填值接口从 GET 迁移到 POST为了让参数值通过 JSON 请求体传输而不是 URL query string以下三个获取 Action 表单预填值的接口被从 GET 改为 POST原 GET 接口新 POST 接口GET /api/action/:action-id/executePOST /api/action/:action-id/execute/valuesGET /api/dashboard/:dashboard-id/dashcard/:dashcard-id/executePOST /api/dashboard/:dashboard-id/dashcard/:dashcard-id/execute/valuesGET /api/public/dashboard/:uuid/dashcard/:dashcard-id/executePOST /api/public/dashboard/:uuid/dashcard/:dashcard-id/execute/values同时parameters的传递方式也变了过去它是 JSON 编码的 query-string 参数现在必须作为请求体中的 JSON 对象提交。GET 变体没有经过弃用期就直接被移除因此升级到 0.64.0 后仍调用旧 GET 地址的集成会立即失败需要同步更新。新端点已在源码中确认落地src/metabase/actions_rest/api.cljPOST /:action-id/execute/valuessrc/metabase/dashboards_rest/api.cljPOST /:dashboard-id/dashcard/:dashcard-id/execute/valuessrc/metabase/public_sharing_rest/api.cljPOST /dashboard/:uuid/dashcard/:dashcard-id/execute/values公开分享场景。可以看出Metabase 采用/:xxx-id/execute/values作为统一的预填值端点命名与原有的执行查询端点/execute在语义上做了区分。0.63.15 / 0.62.18 / 0.61.20 / 0.60.26 / 0.59.30 / 0.58.32bug-report 变更回溯以下维护版本均只包含一条变更即 0.64.0 中POST /api/slack/bug-report的变更diagnosticInfo.reporter变为布尔值、必须启用 bug 报告被回溯移植Metabase 0.63.15Metabase 0.62.18Metabase 0.61.20Metabase 0.60.26Metabase 0.59.30Metabase 0.58.32对集成方的实际含义只要你的实例处于 0.58 及以上的受支持版本线就应假定 bug-report 接口已按新模型工作。因此这一组小版本条目只需阅读 0.64.0 的完整说明即可无需重复迁移逻辑。Metabase 0.61.0移除 LLM 自动描述端点0.61.0 移除了两个依赖旧版 OpenAI client的 LLM 自动描述端点POST /api/metabot/describe/cardPOST /api/metabot/describe/dashboard/:id这两个端点此前用于对 Card 和 Dashboard 生成 LLM 驱动的自动描述如今已被Metabot agentMetabase 的 AI 助手体系取代。Metabot 相关实现见 src/metabase/metabot118 个文件与 src/metabase/agent_api。如果你的集成依赖这两个端点提供自动描述能力需要迁移到新的 Metabot agent 交互方式而不是直接替换 URL。Metabase 0.57.0MBQL 4 到 MBQL 5 的序列化切换0.57.0 是对数据集查询最根本的一次变更MBQL 查询包括 Card 及其他场景在应用数据库和REST API 响应中的序列化格式从 MBQL 4即 legacy MBQL切换为MBQL 5。官方立场与兼容策略Metabase不正式支持通过 REST API 编辑或内省 MBQL官方建议将dataset_query视为一个不透明对象opaque object——即读写时原样传递不解析其内部结构为了支持既有用法GET /api/card/:id端点提供了一个兼容开关附加查询参数?legacy-mbqltrue时返回的 Carddataset_query仍以 MBQL 4 格式输出。从源码结构看legacy MBQL 的整套实现被独立存放于 src/metabase/legacy_mbql 命名空间下包含normalize归一化、schemaMalli 模式定义等模块src/metabase/lib_be与src/metabase/lib则承载新一代 MBQL 的解析与处理逻辑。此外驱动接口 src/metabase/driver.clj 中对legacy-mbql-native-inner-query的 arglist 已标注:deprecated 0.62.0进一步印证 legacy MBQL 正逐步退出核心调用链。迁移建议升级到 0.57 后先确认你的脚本是否有解析dataset_query的逻辑。如果有要么切换到不解析、原样透传的方式要么在读取 Card 时显式附带?legacy-mbqltrue以维持 MBQL 4 输出并为最终移除该兼容参数做好计划。Metabase 0.56.13collection graph 不再返回none权限/api/collection/graph相关端点的响应结构发生变更权限图中不再返回none权限值。缺失的字段即表示该组对该集合没有任何权限。变更前后的对比来自原文档变更前0.56.13 之前{ revision: 2, groups: { 1: { root: write, 1: read, 2: none } } }变更后0.56.13 及之后{ revision: 2, groups: { 1: { root: write, 1: read } } }迁移建议凡是解析 collection graph 的脚本需要把字段缺失当作none处理而不是依赖显式的none值。如果代码中硬编码了2: none这样的断言升级后会解析出错。Metabase 0.55.0/api/util/*工具端点集中重组0.55.0 将一批散落在/api/util/*下的工具端点搬迁到领域化路径全部是重命名/迁移move/rename语义与行为保持不变旧端点新端点说明POST /api/card/from-csvPOST /api/upload/csvCSV 上传归入 upload 模块GET /api/util/statsGET /api/analytics/anonymous-stats匿名统计信息GET /api/util/bug_report_detailsGET /api/bug-reporting/details错误报告详情POST /api/util/product-feedbackPOST /api/product-feedback产品反馈POST /api/util/entity_idPOST /api/eid-translation/translateEntity ID 翻译POST /api/util/password_checkPOST /api/session/password-check密码强度校验GET /api/util/logsGET /api/logger/logs日志读取GET /api/util/diagnostic_info/connection_pool_infoGET /api/bug-reporting/connection-pool-details连接池诊断GET /api/util/openapi移除改用GET /api/docs/openapi.json功能等价新端点已在源码中得到验证src/metabase/analytics/api.clj 定义了GET /anonymous-statssrc/metabase/api/docs.clj 提供GET /openapi.jsonupload 路由挂载于 src/metabase/api_routes/routes.clj/upload前缀。迁移建议这是一次机械性的路径替换建议全量搜索脚本中的/api/util/前缀并逐一映射到新路径。特别注意GET /api/util/openapi已被移除需切换为GET /api/docs/openapi.json。Metabase 0.54.0告警系统迁移到 Notification 架构0.54.0 完成了告警系统从legacy pulse 基础设施到全新 notification 系统的架构迁移这是对集成方影响面较大的一次变更。变更内容/api/alert的大部分端点被移除改用新的/api/notification端点为兼容起见以下端点在本版本仍可用但下一个版本就会移除GET /api/alertGET /api/alert/:idDELETE /api/alert/:id/subscription迁移方向使用/api/notification端点作为告警管理的新入口新 notification 系统的架构说明见 src/metabase/notification/README.md运行时可通过实例上的/api/docs交互式 API 文档查看apinotification标签下的全部端点定义。新架构的三个核心组件来自源码文档根据 src/metabase/notification/README.md一个 Notification 由三部分构成Payload载荷实际要发送的数据内容。由metabase.notification.payload.core/payloadmultimethod 按 payload 类型分派生成当前有 3 种类型:notification/card、:notification/dashboard、:notification/system-event实现位于metabase.notification.payload.impl.*Handlers处理器决定 payload 如何渲染、发送到哪个渠道的配置。每个 handler 包含一个 channel、可选的模板以及一个或多个 recipients。渲染通过metabase.channel.core/render-notification发送通过metabase.channel.core/send!channel 是可扩展的实现metabase.channel.core命名空间中的方法即可接入新渠道Subscriptions订阅/触发器决定何时发送通知。目前有两种:notification-subscription/cron由 Quartz 调度器管理参见metabase.task.notification与:notification-subscription/system-event。该 README 还给出了一个可运行的 Clojure 示例用于同步发送一条 Card 通知1 个 cron 订阅 2 个 handler分别走 Slack 与 email(require [metabase.notification.test-util :as notification.tu]) (require [metabase.notification.core :as notification]) (notification.tu/with-card-notification [notification {:card {:dataset_query (mt/mbql-query users)} :subscriptions [{:type :notification-subscription/cron :cron_schedule 0 0 0 * * ?}] :handlers [{:channel_type :channel/slack :recipients [{:type :notification-recipient/raw-value :details {:value #general}}]} {:channel_type :channel/email :recipients [{:type :notification-recipient/user :user_id (mt/user-id :crowberto)}}]}]} (notification/send-notification! notification :notification/sync? true))迁移建议如果你的自动化依赖/api/alert系列端点创建、列举或取消订阅告警务必在升级到 0.54.0 的同时切换到/api/notification因为旧端点只保留一个版本周期。Metabase 0.53.0导出查询参数不再支持 query stringPOST /api/card/:card-id/query/:export-format端点的参数传递方式收紧此前请求参数parameters、pivot-results?、format-rows?可以通过URL query 参数或application/x-www-form-urlencoded表单内容发送从 0.53.0 起参数必须通过以下两种方式之一提交application/x-www-form-urlencoded表单内容JSON 编码在请求体中。URL 中的 query 参数方式不再被支持。这条规则同样影响使用该端点做 CSV/JSON/XLSX 导出的脚本——检查你的导出代码确保参数放在表单或 JSON body 里而不是拼在 URL 上。Metabase 0.52.0邀请端点移除与 pulse/alert 弃用预告POST /api/user/:id/send_invite被移除GET /:id/fields的响应中现在包含 Table ID解析字段元数据的脚本需要注意字段集合的变化官方在文档中预告/api/pulse与/api/alert下的 API 将在未来版本移除架构正过渡到新系统即 0.54.0 落地的新 notification 架构。迁移建议用户邀请能力需要改用其他路径如POST /api/user结合邮件配置pulse/alert 类集成应尽早规划迁移。Metabase 0.51.0查询元数据聚合端点与订阅端点搬家0.51.0 包含两个新增端点与一批移除/搬迁新增合并的 query_metadata 端点GET /api/dashboard/:id/query_metadata合并了/api/field/:id、/api/database/:id、/api/table/:id/query_metadata的响应大幅减少渲染一个 Card 所需的请求数GET /api/card/:id/query_metadata同理合并了上述三个端点的响应减少渲染一个 Dashboard 所需的请求数。如果你的集成此前为渲染卡片依次调用多个元数据端点可改用这两个合并端点降低延迟与请求量。移除与搬迁/api/legacy-metric端点被移除POST /api/session/pulse/unsubscribe与POST /api/session/pulse/unsubscribe/undo分别迁移到POST /api/pulse/unsubscribe与POST /api/pulse/unsubscribe/undo。Metabase 0.50.0权限图重构与归档Trash语义0.50.0 是权限相关脚本受影响最深的一个版本同时引入了回收站归档语义。1. 集合接口的排序行为GET /api/collection/tree与GET /api/collection/:id/items现在总是先返回官方收藏official collections再返回集合中的其他条目。依赖返回顺序的脚本可能需要显式排序。2. 归档到回收站Trash的语义PUT /api/dashboard/:id、PUT /api/card/:id、PUT /api/collection/:id的行为变化当设置archived: true时Dashboard、Card 或 Collection 会被自动移动到 Trash 集合一个专门存放所有已归档条目的特殊集合当设置archived: false时可以可选地提供collection_id对 Dashboard 或 Cardparent_id对 Collection。提供这些字段时条目从 Trash 移出并被重新挂载到指定集合若未提供条目会尽量移回原始位置如果原始位置不可用例如原始位置本身也在 Trash 中则会发生错误。3./api/metric重命名为/api/legacy-metric/api/metric被重命名为/api/legacy-metric以反映它不再服务于新版本指标的事实——新版指标使用/api/card端点承载。4. 权限图数据结构重构重点GET /api/permissions/graph与PUT /api/permissions/graph中datakey 被移除替换为两个新 keyview-data合法值为unrestricted、blocked、sandboxed、restrictedcreate-queries合法值为query-builder-and-native、query-builder、no。如果你在脚本化权限管理必须重写读写权限图的代码以适配新结构。关于新的 View data / Create queries 数据权限模型可参考 数据权限文档 与 为何取消无自助服务权限的解释。5. 其他GET /api/transform/:db-id/:schema/:transform-name被移除Metabase 内部早已不再使用POST /api/user/:id/send_invite被标记为弃用将在下一版本移除见 0.52.0 条目。Metabase 0.49.5导出端点的format_rows参数注意这批端点变更实际上是在0.49.3加入的而GET /api/embed/card/:token/query/:export-format的 bug 在0.49.5修复。以下导出端点新增了format_rowsquery 参数POST /api/card/:card-id/query/:export-formatPOST /api/:dashboard-id/dashcard/:dashcard-id/card/:card-id/query/:export-formatPOST /api/dataset/:export-formatGET /api/embed/card/:token/query/:export-formatGET /api/embed/dashboard/:token/dashcard/:dashcard-id/card/:card-id/:export-format参数语义format_rows是可选布尔值未提供时默认为true为true时导出结果会应用格式化使值的外观与应用内显示一致为false时不应用格式化导出行为与 0.49.0 之前一致导出 xlsx 文件时format_rows的值不生效。迁移建议如果你依赖导出值的原始未格式化形态需要在升级后显式传format_rowsfalse因为默认值已变为true。Metabase 0.49.0datasetkey 弃用与本地化格式化输出1.dataset字段被type取代POST /api/card与PUT /api/card/:id中datasetkey 被标记弃用预告将在后续版本移除最可能为 50新增typekey用于区分 Model 与 Questiontypemodel等价于datasettruetypequestion等价于datasetfalse。2. 数据格式化输出从 v49 开始所有返回数据的端点例如 JSON、XLSX、CSV 导出以及所有以/query结尾的端点都会按照实例的本地化localization选项对值进行格式化。这意味着通过 API 拿到的值外观可能与直接读库不同——如果你的集成需要原始值请结合 0.49.5 引入的format_rowsfalse参数控制格式化行为。迁移速查表按版本汇总版本变更类型关键动作0.64.0接口模型变更 GET→POSTbug-report 需启用MB_BUG_REPORTING_ENABLED且reporter改布尔transforms 需显式启用3 个 Action 预填值接口迁到/execute/valuesPOST0.63.15 – 0.58.32bug-report 回溯同上适用于所有 0.58 受支持版本线0.61.0端点移除弃用旧 OpenAI 的/api/metabot/describe/*改用 Metabot agent0.57.0序列化变更Carddataset_query默认输出 MBQL 5读取可用?legacy-mbqltrue保持 MBQL 40.56.13响应结构变更collection graph 不再返回none缺失即无权限0.55.0路径重组/api/util/*系列迁移到领域化路径/api/util/openapi移除改用/api/docs/openapi.json0.54.0架构迁移/api/alert迁移到/api/notification旧端点仅保留一个版本0.53.0参数传递收紧导出端点参数不再支持 URL query必须放表单或 JSON body0.52.0移除 预告send_invite移除pulse/alert 预告弃用0.51.0新增/移除新增合并的query_metadata端点/api/legacy-metric移除unsubscribe 端点迁移到/api/pulse0.50.0结构重构权限图data拆为view-datacreate-queries归档进 Trash 语义/api/metric→/api/legacy-metric0.49.5参数新增导出端点新增format_rows默认truexlsx 无效0.49.0字段弃用 输出变化Card 的dataset→type数据端点按本地化选项格式化输出给集成开发者的升级检查清单先在开发/预发实例上验证升级后立即用GET /api/docs/openapi.json实现见 src/metabase/api/docs.clj导出全量 API 规格与旧版本规格做 diff找出被移除或签名变化的端点搜索全部/api/util/、/api/alert、/api/pulse、/api/metric、/api/action/:id/execute、/api/card/from-csv等旧路径引用对照上表逐一迁移检查dataset_query的读写优先不解析、原样透传如需解析请确认使用 MBQL 5或临时使用?legacy-mbqltrue检查导出格式确认是否需要显式传format_rowsfalse以获得未格式化值检查权限与归档脚本适配新的view-data/create-queries权限图结构以及 Trash 归档后的collection_id/parent_id重新挂载逻辑告警集成尽早迁移0.54.0 之后/api/alert只剩一个版本的生命周期直接切换到/api/notification并参考 src/metabase/notification/README.md 理解 Payload / Handler / Subscription 三层模型。本清单的权威来源即仓库中的 API changelog各条目的源码实现可沿 src/metabase/api_routes/routes.clj 的路由挂载逐层深入验证。【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考