[Metabase 系列] Metabase API 使用教學，輕鬆串接自己的系統

前言

前幾篇我們學會了安裝 Metabase、建立提問和圖表、建立 Dashboard，那你有沒有想過能否把 Metabase 串接到自己的系統內呢？例如可以做一些自動化執行任務，或需要大量批次處理。

其實 Metabase 本身就有提供很完善的 API。應該說，Metabase 本身連接前端和後端，就是使用這組 API，所以幾乎你在 Metabase 執行的所有操作，都有對應的 API 端點可以使用。

今天我們來學習一下如何使用 Metabase API。

Metabase 系列教學文章：

* 本文使用 Metabase 版本為：v0.50.28

Metabase API

Metabase 本身連接前端和後端，就是使用這組 API，所以幾乎我們在 Metabase 可以執行的所有操作，都有對應的 API 端點。
例如新增資料庫、建立提問、建立 Dashboard、人員權限設定、管理員設定、搜尋功能…

* 這邊有官方的 API 教學和 API documentation 可以參考。

但該如何知道，我們想要的功能該用哪個 API 端點，以及需要帶上哪些參數呢？

有三種方法可以來尋找：

從 Metabase API documentation
在 API live docs 進行測試
使用瀏覽器的開發人員工具

Metabase API documentation 就是官方整理的文件，可以快速查詢。

但有些看出不出參數要如何帶入，以及它回傳資料的內容與格式，所以我自己比較常用 "開發人員工具" 的方式來查詢。
(API live docs 好像是最近才加入的功能)

API live docs 是可以在你自己運行的 Metabase 上，查看透過 RapiDoc 提供的即時 OpenAPI 文件。只要前往 /api/docs 路徑 (例如 http://localhost:3000/api/docs)。

左邊清單可以方便找到 API 端點，點擊右方的 "TRY" 會發送請求，並且會顯示回傳的結果，挺方便的。

而瀏覽器的開發人員工具，就跟我們在寫網站或網路爬蟲時，使用的方式一樣。

開啟瀏覽器的 開發人員工具 (F12 或 Ctrl + Shift + i)，切換到 "Network" > "Fetch/XHR" 分頁。

"Headers" 頁面可以查看請求的網址與方法
"Payload" 頁面可以查看請求的 Body
"Preview" 頁面可以查看請求的回傳結果

API 金鑰 (API key)

剛剛我們再查看有哪些 API 端點時，因為是在登入的瀏覽器內操作，所以它有自動帶上我們的身分認證，但之後要整合進我們的程式或專案，那就需要使用 API 金鑰做身分認證。

在 Metabase 裡右上角齒輪 > 管理員設定 > 設定 > 授權認證 > API 金鑰。

點擊「建立 API 金鑰」。

金鑰名稱自己取一個，純粹為了區分用。
接下來要選擇一個群組，該 API 金鑰會擁有與此群組相同的權限。

建立後，它會顯示完整的 API 金鑰，這時候要將其複製並保存起來。

之後只能編輯 API 金鑰名稱跟改群組，金鑰內容忘記就只能再產生新的了。

在使用 API 時，只要將此 API 金鑰帶入 Headers 內即可：

x-api-key: YOUR_API_KEY

關於其他說明，可以參考官方文件 API keys。

Session Token

除了使用 API key 驗證以外，其實還可以使用 session token 來驗證，這個就等同輸入帳號密碼的方式。

(在以前的版本，還沒有 API key 的時候，就只能透過 session token 驗證，不過它過一段時間後會過期，需要再重新取得，現在新版都建議直接使用 API key 即可)

* 帳號是 email 格式，例如 person@metabase.com

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"username": "帳號", "password": "密碼"}' \
  http://localhost:3000/api/session

它會回傳像是 { "id": "38f4939c-ad7f-4cbe-ae54-30946daf8593" }。

之後在使用 API 時，將此 id 帶入 Headers 內：

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

* 預設情況，session token 有效期為 14 天。可以透過設定環境變數 MB_SESSION_AGE （值以分鐘為單位）來修改持續時間。
* 最好將 session token 保存起來重複使用，直到過期再重新取得。因為安全因素，使用帳密取得 ession token 有速率限制。

API 如何使用

在整合進我們的程式或專案之前，可以先使用 HTTP Request、測試 API 的工具，例如 Postman 來先測試，方便我們理解該如何使用、回傳資料長怎樣。

以下就以最有名的 Postman 工具來示範。

我們就以取得「全部群組的清單」來當第一個例子。
* 官方 API 文件：GET /api/permissions/group

Request URL：http://localhost:3000/api/permissions/group
Request Method：GET
Headers：
x-api-key:mb_GEeE7gBEcObtBFvanzyeTMIBzvCUmhEvjYv729OCkIA=
(請換成自己剛剛建立的 API 金鑰)

Send 送出請求後，可以收到回覆，這就是我們目前的全部群組：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
[
    {
        "id": 2,
        "name": "Administrators",
        "entity_id": null,
        "member_count": 2
    },
    {
        "id": 1,
        "name": "All Users",
        "entity_id": null,
        "member_count": 4
    }
]

還記得剛剛建立 API 金鑰時，有指定一個群組嗎？
我們是選擇「Administrators」，代表它有管理者的權限。那假如我們再創建一個「All Users」群組的 API 金鑰，測試同一個 API 呢？

可以看到它回覆 "您沒有權限那麼做"，HTTP Status Code 是 403 Forbidden，代表客戶端沒有訪問該資源的權限，這就是權限管控。

就跟一般使用者登入 Metabase 後，他也沒有權限進入 "管理員設定" 一樣。

再來試一個。

我想查看一個「提問 (Questions，也就是圖表) 的資訊」，該如何操作？

* 在 API 中，提問被稱為卡片(card)
* 官方 API 文件：GET /api/card/:id

例如網址是在 http://localhost:3000/question/27-products 的圖表。

card id 就是在網址後面的數字，以上範例的話就是 27。

Request URL：http://localhost:3000/api/card/27
Request Method：GET
Headers：
x-api-key:mb_j6OtF0o24wnnJb3A/wteFfuilW4lKyKHtx9Cl6cQKBE=
(請換成自己剛剛建立的 API 金鑰)

Send 送出請求後，可以收到回覆，就是有關這個提問(圖表)的資訊：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
{
    "id": 27,
    "name": "Products 依類別分組",
    "description": null,
    "archived": false,
    "view_count": 2,
    "type": "question",
    "query_type": "query",
    "display": "bar",
    "database_id": 1,
    "can_write": true,
    "average_query_time": 38.0000000000000000,
    "enable_embedding": false,
    "last_query_start": "2024-10-12T13:07:51.402753Z",
    "last_used_at": "2024-10-12T13:07:51.422213Z",
    "updated_at": "2024-10-12T13:31:43.873511Z",
    "created_at": "2024-10-12T13:07:21.456419Z",
    "creator_id": 1,
    ...以下省略
}

以上兩個範例都是 GET 資料，來看看假如是想要 POST 的請求方式呢？

例如想取得「提問 (Questions，圖表) 的查詢資料」，也就是網頁底下切換成原始資料的部分。

* 官方 API 文件：POST /api/card/:card-id/query

Request URL：http://localhost:3000/api/card/27/query
Request Method：POST
Headers：
x-api-key:mb_j6OtF0o24wnnJb3A/wteFfuilW4lKyKHtx9Cl6cQKBE=
(請換成自己剛剛建立的 API 金鑰)
Body:
{
    "ignore_cache": true
}

* 這個 API 端點的 Body 非必要，可以省略

Send 送出請求後，可以收到回覆，是這個提問(圖表)的查詢資料：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
    "data": {
        "rows": [
            [
                "Doohickey",
                42
            ],
            [
                "Gadget",
                53
            ],
            [
                "Gizmo",
                51
            ],
            [
                "Widget",
                54
            ]
        ],
        ...以下省略
    },
    "cached": null,
    "database_id": 1,
    "started_at": "2024-10-12T13:42:49.532062Z",
    "status": "completed",
    "context": "question",
    "row_count": 4,
    "running_time": 25,
    ...以下省略
}

其他更多說明與 API 端點，可以參考 Metabase 官方 API documentation。

備註

雖然他們有說，API 介面盡量不會做更改，但新功能推出、舊 bug 修復可能多多少少 API 還是有調整，因此在升級 Metabase 版本之前，可以先參考官方整理的文章：API 介面的重大更改

結語

在以上了解 Metabase API 的使用之後，我們就可以把 Metabase 串接到自己的系統內，做更深度的整合，或做些自動化的應用了~

而且從 API 回傳資料，也可以發現一些沒有顯示在網頁畫面上的資訊 XD

如果對於 Metabase 有興趣的讀者，記得『IT空間』FB 粉專要追蹤起來，才不會錯過最新的發文通知哦~🔔

參考：
Metabase 官方網站
 Metabase API 官方教學
 Metabase 官方 API documentation
Metabase 官方 GitHub
Metabase API 介面的重大更改

有那個時間絕望的話，還不如去吃好吃的美食，然後好好睡一覺。
—— 《法醫女王》(日本電視劇)

🔻 如果覺得喜歡，歡迎在下方獎勵我 5 個讚~