企业官网建设流程全解析

5 分钟接通 Metabase API：新手从 0 到 1 完整指南

【免费下载链接】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

每天早上手动导一遍经营报表，丢进群里，这是很多人的日常。Metabase API 就是为这类重复劳动准备的：一段脚本代替手动导数，查询、建仪表盘、同步数据都能用代码完成。这篇指南带你走完第一条真实调用，并把最常见的坑一次说清。

先判断：你的情况值不值得接 API

不是所有需求都需要写代码。对照下面三点，命中两条以上再接：

• 数据动作周期性重复：每天/每周导出报表、定时同步一份数据
• 数据要流进其他系统：业务平台、内部工具、自动化流水线
• 需要程序化批量管理内容：批量建卡、批量调权限

如果只是自己偶尔看一眼图表，网页界面就够了，不必接 Metabase API 调用。

动手前检查清单

• 确认版本号：CSV 上传接口需要v0.55.0+，MBQL 5 完整支持需要v0.57.0+，低版本先升级
• 确认服务端口可访问，默认3000，接口文档在服务的/api/docs路径
• 用管理员账户登录，进入 管理 > 人员，生成 API 密钥并记下过期时间
• 给不同用途发不同密钥：报表脚本一把、内部工具一把，出事了能单独吊销
• 密钥只放后端或环境变量，别写进前端页面源码——它等同于这个账号的完整权限
• 在终端用一条请求试通连通性，再开始写正式代码

第一次调用：拿到第一条数据

用curl打通 Metabase 数据查询接口。/api/dataset是取数入口，body 里的query就是 MBQL（Metabase 自己的查询描述格式，可以理解为"不用写 SQL 的查询"）：

curl -s http://localhost:3000/api/dataset \ -H "Content-Type: application/json" \ -H "X-Metabase-Session: <你的密钥>" \ -d '{ "database": 1, "type": "query", "query": { "source-table": 2, "aggregation": [["count"]] } }'

逐段说明：

• X-Metabase-Session请求头携带密钥，等价于用这个账号登录
• source-table填表 ID，database填数据源 ID——两个 ID 都在响应里回显，第一次可以直接从网页界面的网络请求里抄
• 成功时返回 JSON，核心是data（含columns、rows）和status

拿到"status": "completed"和一行数据，说明链路通了。

三个高频业务场景拆解

场景一：定时导报表到 CSV

要解决什么：每天 8 点自动产出一份问题（card）的结果文件，不再手动点导出。

关键请求：对已有问题调POST /api/card/{card-id}/query/{export-format}，把{export-format}换成csv、json或xlsx，响应体直接是文件内容。

curl -s -o sales.csv \ -H "X-Metabase-Session: <你的密钥>" \ -X POST http://localhost:3000/api/card/17/query/csv

最常见的坑：大查询要跑几分钟时，接口会先返回409（查询还没执行完）。脚本里要处理这个状态——稍等后重试，或改用查询 ID 轮询，别把 409 当失败。

场景二：把业务数据批量灌进来

要解决什么：CRM 里的一批客户名单，直接变成 Metabase 里可查询的表，而不是靠人手动上传。

关键请求：POST /api/upload/csv（旧接口POST /api/card/from-csv已改名，见 API 变更日志），提交 CSV 文件并指定目标集合即可。

最常见的坑：列名对不上语义类型，导入后字段全变文本，求和、排序全废。导入前先在网页界面手动传一次同结构的文件，确认列类型正常，再让脚本复制这套参数。

场景三：用代码建仪表盘

要解决什么：给每个区域自动生成一套同构仪表盘，手动建太慢。

关键请求：POST /api/dashboard，body 只给name和description就能创建，再按需补parameters（仪表盘级过滤器，如按 region 筛选）和卡片位置。创建成功返回id和created_at，后续往上面挂卡片都用它。

最常见的坑：只建了空壳却忘了挂卡片和设归属集合，仪表盘建出来是个空白页，还得再调卡片接口补全。

接入你自己的页面

下面是最短完整链路：取数 → 校验 → 渲染成表格。浏览器直接发请求时注意跨域，生产环境建议走自己后端的代理转发。

async function loadReport() { const res = await fetch("http://localhost:3000/api/dataset", { method: "POST", headers: { "Content-Type": "application/json", "X-Metabase-Session": KEY, // 仅示例，正式环境走后端代理 }, body: JSON.stringify({ database: 1, type: "query", query: { "source-table": 2, "breakout": [["field", 12, null]], "aggregation": [["sum", ["field", 16, null]]], }, }), }); const payload = await res.json(); if (payload.status !== "completed") throw new Error(payload.status); const [cols, ...rows] = payload.data.rows; document.querySelector("#tbl").innerHTML = rows .map((r) => `<tr>${r.map((v) => `<td>${v}</td>`).join("")}</tr>`) .join(""); }

breakout是分组维度，aggregation是聚合指标；rows第一行是列名，后面才是数据行。渲染图表同理：把列名、数值映射给任意前端图表库即可。

踩坑速查

• 现象：返回 401，之前明明能用。原因：密钥过期或被管理员吊销。处理：到 管理 > 人员 重新生成，更新密钥配置；按用途分发的密钥此时正好能定位是哪条链路在用它。

• 现象：返回 403，权限看着没问题。原因：v0.50.0 起旧data权限拆成了view-data和create-queries两把钥匙，老配置可能只授了其中一把。处理：调GET /api/permissions/graph看权限图谱，确认当前账号两个键都有值。

• 现象：查询接口返回 409，不是报错信息。原因：Metabase 还在跑这条查询，属于"进行中"而非失败。处理：脚本加重试或轮询查询 ID，并把超时阈值放宽到能覆盖最慢的那条报表。

• 现象：source-table或field的 ID 填了却报字段找不到。原因：字段 ID 是"某表下的字段"，换了表 ID 就不通用；直接从网页界面网络请求里复制的 payload 最容易犯这个错。处理：用GET /api/tables/{id}核对字段 ID 与表的归属关系，或干脆固定从一次成功查询的响应里取 ID。

• 现象：列表接口一次拉几千条，页面卡住。原因：没做分页，全量返回。处理：列表类接口带上page和limit参数控制单次返回量。

跑通第一条查询后，剩下就是按场景套模板的事。参考资料：

• 完整接口定义：docs/api.json，交互式文档在服务的/api/docs
• 版本变更：docs/developers-guide/api-changelog.md
• 上传相关说明：docs/databases/uploads.md

【免费下载链接】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