使用 Metabase API

本文解释了如何使用 Metabase API 自动执行任务。我们自己也使用该 API 连接前端和后端，因此您可以编写脚本来完成 Metabase 几乎所有能做的事情。

API 参考

您可以在我们的文档中找到 Metabase API 参考。您也可以在正在运行的 Metabase 实例的 /api/docs 路径下查看实时 OpenAPI 文档。例如，如果您的 Metabase 位于 https://www.your-metabase.com，您可以通过 https://www.your-metabase.com/api/docs 访问它们。

警告：Metabase API 可能会更改

• API 可能会更改。我们很少更改 API 端点，也几乎从不删除它们，但如果您编写依赖于 API 的代码，将来可能需要更新您的代码。
• API 未进行版本控制。因此，不要指望通过保留某个特定版本的 Metabase 来使用“稳定”的 API。

有关 API 更改，请查阅开发者指南中的API 变更日志。

Metabase API 入门

为简单起见，我们将使用常用的命令行工具 curl 作为 API 调用示例；您也可以考虑使用专门的工具来开发 API 请求（例如 Postman）。要跟进，您可以在 localhost 上启动一个全新的 Metabase 并进行尝试。

创建 API 密钥

要使用 API，请创建 API 密钥。

GET 请求示例

这是一个 API 请求示例，它访问 /api/permissions/group 端点，该端点返回您在 Metabase 中设置的权限组。将 YOUR_API_KEY 替换为您的 API 密钥。

curl \
-H 'x-api-key: YOUR_API_KEY' \
-X GET 'https://:3000/api/permissions/group'

上述请求返回一个 JSON 对象数组，其中包含您 Metabase 中的组（为便于阅读而格式化）。

[
  {
    "id": 2,
    "name": "Administrators",
    "member_count": 2
  },
  {
    "id": 1,
    "name": "All Users",
    "member_count": 3
  }
]

POST 请求示例

您还可以使用文件来存储 POST 请求的 JSON 有效负载。这使得您可以轻松地拥有一组预定义的 API 请求。

curl -H @header_file.txt -d @payload.json https:///api/card

这是上述命令中的 header_file.text

x-api-key: YOUR_API_KEY

这是一个 JSON 文件示例（上述命令中的 @payload.json），用于创建一个问题

{
  "visualization_settings": {
    "table.pivot_column": "QUANTITY",
    "table.cell_column": "SUBTOTAL"
  },
  "description value": "A card generated by the API",
  "collection_position": null,
  "result_metadata": null,
  "metadata_checksum": null,
  "collection_id": null,
  "name": "API-generated question",
  "dataset_query": {
    "database": 1,
    "query": {
      "source-table": 2
    },
    "type": "query"
  },
  "display": "table"
}

该请求生成了问题

查看 Metabase 的请求和响应

在实时 API 文档中进行试验

您可以通过正在运行的 Metabase 实例的 /api/docs 路径查看由 RapiDoc 提供的实时 OpenAPI 文档。例如，如果您的 Metabase 位于 https://www.your-metabase.com，您可以通过 https://www.your-metabase.com/api/docs 访问它们。

在实时文档中，您可以尝试发送请求并查看示例响应。

使用开发者工具

如果自动生成的 API 文档不清楚，您可以使用浏览器（如 Firefox、Chrome 和 Edge）附带的开发者工具来查看 Metabase 的请求和响应。

在 Metabase 应用程序中，执行您想要编写脚本的操作，例如添加用户或创建仪表板。然后使用浏览器中的开发者工具查看 Metabase 在您执行该操作时向服务器发出的请求。

使用 Metabase API 可以做的几件事

配置 Metabase 实例

除了使用环境变量，您还可以使用 Metabase API 设置 Metabase 实例。一旦您使用首选方法安装了 Metabase，并且 Metabase 服务器已启动并运行，您可以通过向特殊端点 /api/setup 发送 POST 请求来创建第一个用户（作为管理员）。此 /api/setup 端点：

• 创建第一个用户作为管理员（超级用户）。
• 登录该用户。
• 返回会话 ID。

然后，您可以使用 /api/settings 端点配置设置，使用 /api/email 端点设置电子邮件，并使用 /api/setup/admin_checklist 端点验证您的设置进度。

添加数据源

您可以使用 POST /api/database/ 端点添加新数据库，并使用 /api/database/validate/ 端点验证该数据库的连接详细信息。一旦您将数据库连接到您的 Metabase 实例，您可以重新扫描数据库并更新架构元数据。您甚至可以使用 POST /api/database/sample_database 将我们的可靠示例数据库作为新数据库添加到您的实例中。

这是一个 Redshift 数据库的示例数据库创建调用。

curl -s -X POST \
    -H "Content-type: application/json" \
    -H 'x-api-key: YOUR_API_KEY' \
    https://:3000/api/database \
    -d '{
        "engine": "redshift",
        "name": "Redshift",
        "details": {
            "host": "redshift.aws.com",
            "port": "5432",
            "db": "dev",
            "user": "root",
            "password": "password"
        }
    }'

设置用户、组和权限

您可以使用 /api/user 端点来创建、更新和禁用用户，或者使用 /api/permissions 端点来设置组或将用户添加到其中。这是一个创建用户的 curl 命令示例

curl -s "https://:3000/api/user" \
    -H 'Content-Type: application/json' \
    -H 'x-api-key: YOUR_API_KEY' \
    -d '{
    "first_name":"Basic",
    "last_name":"Person",
    "email":"basic@somewhere.com",
    "password":"Sup3rS3cure_:}"
}'

生成报告

在 Metabase 中，“报告”被称为仪表板。您可以使用/api/dashboard端点与仪表板进行交互。您可以使用POST /api/dashboard/创建新的仪表板，并使用 [POST/api/dashboard/:id/cards]将已保存的问题添加到仪表板。

有用的端点

下表中“端点”列中的链接将带您到该端点可用的第一个操作，按字母顺序通常是 DELETE 操作。您可以在 API 文档中向下滚动，查看该端点的所有操作和 URL 的完整列表，并查看每个操作的描述。

还有一些其他很酷的端点可以查看，例如 api/database/:virtual-db/metadata，它用于“欺骗”前端，使其能够将已保存的问题视为虚拟数据库中的表。这就是 Metabase 允许您将已保存问题用作数据源的方式。

文档包含完整的 API 端点列表以及每个端点的文档，所以请深入探索，看看还能找到哪些其他很酷的端点。

端点参考会定期随 Metabase 的新版本更新。您还可以通过运行以下命令生成参考：

java -jar metabase.jar api

运行自定义查询

使用查询构建器编写的查询以我们自定义的基于 JSON 的查询语言 MBQL 保存。

为了熟悉 MBQL，我们建议您使用 Metabase 应用程序，通过查询构建器创建一个问题，然后使用浏览器的开发者工具查看 Metabase 如何使用查询格式化请求体。

Python、R 和 JavaScript 示例

Curl 是一个方便的 API 探索工具，但如果您将 Metabase 集成到大型数据生态系统中，您可能会使用其他工具。为了展示如何使用 Python、R 和 Node.js 访问 API，我们创建了两个问题。第一个问题是查找按类别分组的订单（价值超过 100 美元）的平均税前值。它已公开共享——本教程解释了如何操作。

第二个问题统计数据库中的人数。它*未*共享：我们将其包含在内以显示如何区分共享和非共享问题。

Python

我们的第一个示例是用 Python 编写的。像大多数数据科学程序一样，它使用 requests 库发送 HTTP 请求，并使用 Pandas 管理表格数据，因此我们首先导入这些库。

让我们问 Metabase 哪些问题具有公共 ID，即哪些问题已共享以便我们可以远程调用它们。当我们请求所有卡片时，我们得到一个包含所有问题一些信息的列表；只有具有 public_uuid 字段的问题才是可调用的。

import requests
import pandas as pd
# Avoid committing your API KEY to the repository
headers = {'x-api-key': YOUR_API_KEY}
response = requests.get('https://:3000/api/card',
                         headers=headers).json()
questions = [q for q in response if q['public_uuid']]
print(f'{len(questions)} public of {len(response)} questions')

在我们的案例中，输出告诉我们有两个问题，但只有一个是公开的

1 public of 2 questions

让我们获取有关该公共问题的一些信息并打印其标题

uuid = questions[0]['public_uuid']
response = requests.get(f'https://:3000/api/public/card/{uuid}',
                        headers=headers)
print(f'First title: {response.json()["name"]}')

First title: Average value of orders over $100 grouped by category

最后，我们可以从列表中的第一个问题中提取数据。JSON 响应中的 'data' 键包含大量信息；我们最感兴趣的是子键 'rows' 下的值，它以通常的列表-列表形式存储结果表。让我们将其转换为 Pandas 数据框并打印出来

response = requests.get(f'https://:3000/api/public/card/{uuid}/query',
                        headers=headers)
rows = response.json()['data']['rows']
data = pd.DataFrame(rows, columns=['Category', 'Average'])
print('First data')
print(data)

First data
    Category     Average
0  Doohickey  114.679742
1     Gadget  123.530916
2      Gizmo  120.897286
3     Widget  122.078721

R 和 Tidyverse

我们的示例的 R 版本与 Python 版本具有相同的结构。像大多数数据科学家一样，我们使用 tidyverse 库系列，所以让我们加载这些库以及用于管理 HTTP 请求的 httr，用于解析 JSON 的 jsonlite，以及用于字符串格式化的 glue

library(tidyverse)
library(httr)
library(jsonlite)
library(glue)

我们将 API 密钥放在请求头中。

headers <- add_headers('x-api-key' = YOUR_API_KEY)

然后我们获取所有问题的信息，并询问哪些是公开的

data <- GET('https://:3000/api/card', headers) %>%
  content(as = 'text', encoding = 'UTF-8') %>%
  fromJSON()
num_questions <- data %>%
  nrow()
num_public <- data %>%
  pull(public_uuid) %>%
  discard(is.na) %>%
  length()
glue('{num_public} public of {num_questions} questions')

1 public of 2 questions

显示第一个公开卡的标题，结果与 Python 相同，这令人放心

uuid <- data %>%
  pull(public_uuid) %>%
  discard(is.na) %>%
  first()
data <- glue('https://:3000/api/public/card/{uuid}') %>%
  GET(headers) %>%
  content(as = 'text', encoding = 'UTF-8') %>%
  fromJSON()
glue('First title: {data$name}')

First title: Average value of orders over $100 grouped by category

并且，一旦我们将其转换为 tibble，与该卡关联的数据也相同，尽管 R 的默认显示不会给出那么多小数位

data <- glue('https://:3000/api/public/card/{uuid}/query') %>%
  GET(headers) %>%
  content(as = 'text', encoding = 'UTF-8') %>%
  fromJSON()
rows <- data$data$rows
colnames(rows) <- c('Category', 'Average')
rows <- rows %>% as_tibble()
rows$Average <- as.numeric(rows$Average)
glue('First data')
rows

First data
# A tibble: 4 x 2
  Category  Average
  <chr>       <dbl>
1 Doohickey    115.
2 Gadget       124.
3 Gizmo        121.
4 Widget       122.

Node.js 上的 JavaScript

JavaScript 是一种越来越流行的服务器端脚本语言，但与 Python 和 R 不同，JavaScript 缺少一个占主导地位的数据表库。对于大型项目，我们偏爱 data-forge，但对于小型示例，我们坚持使用 Dataframe-js。我们还使用 got 进行 HTTP 请求，而不是较旧的 request 包，因为后者已被弃用。最后，由于我们发现 async/await 语法比 promise 或回调更容易阅读，我们将所有代码放在一个立即调用的 async 函数中

const got = require("got");
const DataFrame = require("dataframe-js").DataFrame;

const main = async () => {
  // ...program goes here...
};

main();

我们再次开始进行身份验证

headers = { "x-api-key": YOUR_API_KEY };

然后我们请求完整的问卷列表，并过滤它们以选择公开的问卷

response = await got.get("https://:3000/api/card", {
  responseType: "json",
  headers: headers,
});
// filter for public questions
questions = response.body.filter((q) => q.public_uuid);
console.log(`${questions.length} public of ${response.body.length} questions`);

1 public of 2 questions

第一个公共卡片仍然是我们之前看到的标题

const uuid = questions[0].public_uuid;
response = await got.get(`https://:3000/api/public/card/${uuid}`, {
  responseType: "json",
  headers: headers,
});
console.log(`First title: ${response.body.name}`);

First title: Average value of orders over $100 grouped by category

当我们下载它的数据时，我们得到相同的值，尽管数字以略微不同的方式显示

response = await got.get(
  `https://:3000/api/public/card/${uuid}/query`,
  {
    responseType: "json",
    headers: headers,
  },
);
const rows = response.body.data.rows;
const df = new DataFrame(rows, ["Category", "Average"]);
df.show();

| Category  | Average   |
------------------------
| Doohickey | 114.67... |
| Gadget    | 123.53... |
| Gizmo     | 120.89... |
| Widget    | 122.07... |

使用会话令牌验证您的请求

您应该改为使用 API 密钥。包含以下信息只是以防万一您出于某种原因需要使用会话令牌。

您还可以使用会话令牌来验证您的请求。要获取会话令牌，请使用您的用户名和密码向 /api/session 端点提交请求

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"username": "person@metabase.com", "password": "fakepassword"}' \
  https://:3000/api/session

如果您正在使用远程服务器，您需要将 localhost:3000 替换为您的服务器地址。此请求将返回一个 JSON 对象，其中包含一个名为 id 的键，以及作为该键值的令牌，例如：

{ "id": "38f4939c-ad7f-4cbe-ae54-30946daf8593" }

然后您可以将该会话令牌包含在后续请求的头部中，如下所示

"X-Metabase-Session": "38f4939c-ad7f-4cbe-ae54-30946daf8593"

关于会话的一些注意事项

• 默认情况下，会话有效期为 14 天。您可以通过设置环境变量 MB_SESSION_AGE（以分钟为单位）来配置此会话持续时间。
• 您应该缓存凭据 以便在它们过期之前重复使用，因为登录操作会受到安全方面的速率限制。
• 无效和过期的会话令牌返回 401（未授权）状态码。
• 优雅地处理 401 状态码。我们建议您编写代码，在 API 返回 401 状态码时，自动获取新的会话令牌并重试请求。
• 某些端点要求用户是管理员，也称为超级用户。要求管理员或超级用户身份的端点（管理员 = 超级用户）通常会在其文档中说明。如果当前用户不是管理员，它们将返回 403（禁止访问）状态码。

简而言之：请改用 API 密钥。

玩得开心

如果您觉得本教程很有趣，您可以启动一个本地 Metabase 实例，尝试使用 API，尽情玩乐！如果您遇到困难，可以查看我们的论坛，看看是否有人遇到过类似的问题，或者发布新问题。