Metabase学习教程：系统管理-7

使用MetabaseAPI

MetabaseAPI简介。

本文介绍如何使用Metabase的API。我们自己使用该API连接前端和后端，因此您可以编写Metabase几乎可以执行的所有操作。

警告：MetabaseAPI可能会更改

开始之前有两个注意事项：

1. API可能会更改。API与前端紧密耦合，在不同版本之间可能会发生变化。端点可能不会有那么大的变化（现有的API端点很少被更改，也很少被删除），但是如果您编写代码来使用API，您可能需要在将来更新它。
2. API没有版本。意思是：它可以在不同的版本之间进行更改，因此不要期望为了使用“稳定”的API而停留在Metabase的特定版本上。

MetabaseAPI入门

为了简单起见，我们将使用古老的命令行实用程序curl对于我们的API调用示例；您还可以考虑使用一个专用工具来开发API请求（比如Postman). 要跟上，你可以启动一个新的Metabase本地实例到处玩。

使用session token验证您的请求

你需要一个session token以验证您的请求，否则Metabase将拒绝与您交谈。若要获取session token，请向/api/session具有用户名和密码的终结点：

curl -X POST \

  -H "Content-Type: application/json" \

  -d '{"username": "person@metabase.com", "password": "fakepassword"}' \

  http://localhost:3000/api/session

如果使用的是远程服务器，则需要替换localhost:3000你的服务器地址。此请求将返回一个JSON对象，该对象的键名为id以及令牌作为密钥的值，例如：

{“id”：“38f4939c-ad7f-4cbe-ae54-30946daf8593”}

您将需要在后续请求的标头中包括该session token，如下所示：

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

关于会话的一些注意事项：

• 默认情况下，会话有效期为14天。您可以通过设置环境变量来配置此会话持续时间MB_SESSION_AGE（值以分钟为单位）。
• 你应该缓存凭据重复使用它们直到它们过期，因为登录是安全的速率限制的。
• 无效和过期的session token返回401（未授权）状态代码。
• 优雅地处理401状态码。我们建议您编写代码以获取新的session token，并在API返回401 status code.
• 有些端点要求用户是管理员，也称为超级用户。需要管理员或超级用户状态（admin=superuser）的终结点通常在其文档中这样说。他们将返回一个403 (Forbidden) status code 如果当前用户不是管理员。
• 如果您想使用替代身份验证机制请随意投票功能请求.

获取请求示例

下面是一个示例API请求（注意session token），它将/api/user/current端点，它返回有关当前用户的信息：

curl -X GET \

  -H "Content-Type: application/json" \

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

  http://localhost:3000/api/user/current

上面的请求返回一个JSON对象（格式化为可读性）：

{

    "email": "person@metabase.com",

    "ldap_auth": false,

    "first_name": "Human",

    "locale": null,

    "last_login": "2020-08-31T13:08:50.203",

    "is_active": true,

    "is_qbnewb": false,

    "updated_at": "2020-08-31T13:08:50.203",

    "group_ids": [

        1,

        2

    ],

    "is_superuser": true,

    "login_attributes": null,

    "id": 1,

    "last_name": "Person",

    "date_joined": "2020-08-19T10:50:46.547",

    "personal_collection_id": 1,

    "common_name": "Human Person",

    "google_auth": false

}

POST请求示例

您还可以使用一个文件来存储POST请求的JSON负载。这使得您可以很容易地对API发出一组预定义的请求。

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

下面是一个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"

}

该请求生成了如图1所示的问题。

图1.API生成的Metabase中的问题：一个命令示例数据库中的表

使用开发人员工具查看Metabase如何发出请求

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

图2。使用Firefox的“网络”选项卡检查用户单击以保存在查询编辑器中创建的问题时Metabase发送的JSON请求负载。

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

使用MetabaseAPI可以做的一些事情

设置Metabase实例

除了使用环境变量，您可以使用MetabaseAPI来设置Metabase的实例。一旦您使用首选方法，并且Metabase服务器已启动并正在运行，您可以通过发布到特定端点来创建第一个用户（作为管理员），/api/setup.这个/api/setup终结点：

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

然后可以使用/api/setup端点，使用