data-metabase

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Metabase

Automate Metabase via API: reports (cards), dashboards, and chart settings.

通过API实现Metabase自动化：报表（即cards）、仪表板和图表设置。

Quick Start

快速开始

Inputs (env vars)

输入项（环境变量）

METABASE_URL

(e.g.,

https://metabase.example.com

)

Preferred:
```
METABASE_API_KEY
```
Fallback:
```
METABASE_USERNAME
```
+
```
METABASE_PASSWORD
```

METABASE_URL

（例如：

https://metabase.example.com

）

优先选择：
```
METABASE_API_KEY
```
备选方案：
```
METABASE_USERNAME
```
+
```
METABASE_PASSWORD
```

Sanity checks

完整性检查

bash

python3 frameworks/shared-skills/skills/data-metabase/scripts/metabase_api.py health
python3 frameworks/shared-skills/skills/data-metabase/scripts/metabase_api.py whoami

bash

python3 frameworks/shared-skills/skills/data-metabase/scripts/metabase_api.py health
python3 frameworks/shared-skills/skills/data-metabase/scripts/metabase_api.py whoami

Live API documentation

在线API文档

Your Metabase instance serves OpenAPI docs at

/api/docs

(e.g.,

https://metabase.example.com/api/docs

). Use this to discover version-specific endpoints and request shapes.

你的Metabase实例在

/api/docs

路径下提供OpenAPI文档（例如：

https://metabase.example.com/api/docs

）。你可以通过它查看特定版本的接口和请求格式。

Workflow

工作流程

Confirm API availability (
```
GET /api/util/health
```
).
Authenticate with an API key (preferred) or a short-lived session (fallback).
Discover IDs (prefer discovery over hardcoding across environments):
- ```
collection_id
```
  for where to save
- ```
database
```
  id for
```
dataset_query
```
- ```
source-table
```
  / field ids if using MBQL
Create/update a card:
- Prefer native SQL for stable automation.
- Set
```
display
```
  +
```
visualization_settings
```
  explicitly.
Create/update a dashboard and add cards with consistent layout.
Validate by running/exporting results.

确认API可用（调用
```
GET /api/util/health
```
接口）。
进行身份验证（优先使用API密钥，短期会话验证作为备选）。
查找ID（跨环境时优先通过接口查找，而非硬编码）：
- ```
collection_id
```
  ：用于指定保存位置
- ```
database
```
  ID：用于
```
dataset_query
```
  配置
- 若使用MBQL，则需要
```
source-table
```
  /字段ID
创建/更新card：
- 为实现稳定的自动化，优先使用原生SQL。
- 显式设置
```
display
```
  和
```
visualization_settings
```
  参数。
创建/更新仪表板，并添加布局一致的cards。
通过运行/导出结果进行验证。

Key Concepts

核心概念

UI "Question" == API
```
card
```
Chart configuration lives on the card as
```
display
```
+
```
visualization_settings
```
Most viz keys are easiest to manage by copying from an existing card JSON, then editing

UI中的「Question」对应API中的
```
card
```
图表配置存储在card中，以
```
display
```
和
```
visualization_settings
```
的形式存在
大多数可视化配置项最简便的管理方式是从现有card的JSON中复制，再进行编辑

Guardrails

注意事项

Prefer Metabase "serialization" (Pro/Enterprise) for bulk, cross-environment migrations; use direct API for incremental upserts.
Do not hardcode numeric IDs across environments when you can discover them or use serialization/entity IDs.
Never commit
```
METABASE_API_KEY
```
, passwords, or session tokens.
Prefer a dedicated, least-privileged automation account and collection.

若进行批量跨环境迁移，优先使用Metabase的「serialization」功能（仅Pro/Enterprise版本支持）；增量更新插入操作则使用直接API调用。
若可以通过查找或使用serialization/实体ID获取，请勿在跨环境时硬编码数字ID。
绝对不要提交
```
METABASE_API_KEY
```
、密码或会话令牌到代码仓库。
优先使用专用的、权限最小的自动化账号和集合。

References (read only as needed)

参考资料（按需阅读）

Topic	File
Authentication (API key + fallback)	references/api-auth.md
Reports (cards): create/edit patterns	references/reports-cards.md
Dashboards and card placement	references/dashboards.md
Charts and `visualization_settings`	references/charts-settings.md

主题	文件
身份验证（API密钥+备选方案）	references/api-auth.md
报表（cards）：创建/编辑模式	references/reports-cards.md
仪表板与卡片布局	references/dashboards.md
图表与 `visualization_settings` 配置	references/charts-settings.md

Scripts

脚本

scripts/metabase_api.py

is a small, dependency-free helper to test auth and upsert cards.

Examples:

bash

undefined

scripts/metabase_api.py

是一个轻量、无依赖的辅助脚本，用于测试身份验证和更新插入cards。

示例：

bash

undefined

Print authenticated user (tries API key, then session)

打印已认证用户信息（优先尝试API密钥，再尝试会话验证）

python3 frameworks/shared-skills/skills/data-metabase/scripts/metabase_api.py whoami

Export an existing card JSON (use as a template for visualization_settings)

导出现有card的JSON（可作为visualization_settings的模板）

python3 frameworks/shared-skills/skills/data-metabase/scripts/metabase_api.py export-card --id 123 --out card.json

Export an existing dashboard JSON (use as a template for layout)

导出现有仪表板的JSON（可作为布局模板）

python3 frameworks/shared-skills/skills/data-metabase/scripts/metabase_api.py export-dashboard --id 5 --out dashboard.json

Create/update a card from a JSON spec (see references/reports-cards.md)

从JSON配置文件创建/更新card（详见references/reports-cards.md）

python3 frameworks/shared-skills/skills/data-metabase/scripts/metabase_api.py upsert-card --spec card-spec.json

Create/update a dashboard from a JSON spec (base fields only)

从JSON配置文件创建/更新仪表板（仅基础字段）

python3 frameworks/shared-skills/skills/data-metabase/scripts/metabase_api.py upsert-dashboard --spec dashboard-spec.json

undefined

python3 frameworks/shared-skills/skills/data-metabase/scripts/metabase_api.py upsert-dashboard --spec dashboard-spec.json

undefined