嵌入式分析 JS

嵌入式分析JS允许您使用可定制的组件将Metabase实体（如问题、仪表板，甚至查询生成器）嵌入到您自己的应用程序中。

嵌入式分析JS是一个基于Metabase的嵌入式分析React SDK构建的JavaScript库。但它不需要使用React或设置完整的SDK嵌入。与交互式嵌入（您在iframe中嵌入整个Metabase应用程序）不同，嵌入式分析JS允许您从一组预定义组件中选择，例如单个图表、带有可选钻取的仪表板或查询生成器，并自定义这些组件。

嵌入式分析JS使用JWT或SAML来验证用户并自动应用正确的权限。

目前您可以选择嵌入

• 一个仪表板
• 一个问题（图表）。您可以嵌入使用查询生成器构建的问题和使用SQL构建的问题。
• 完整的图形化查询生成器，让人们能够构建自己的图表和探索。
• 一个浏览器，用于导航集合并打开仪表板或问题。

快速入门

1. 启用嵌入式分析JS

1. 在 Metabase 中，转到 Admin Settings > Embedding > Modular embedding。
2. 打开 嵌入式分析 JS。
3. 在跨域资源共享 (CORS) 下，添加您希望嵌入 Metabase 的网站 URL（例如 https://*.example.com）。为了测试嵌入，您可以使用 localhost，它始终包含在 CORS 策略中。

2. 创建新的嵌入

1. 在Metabase中，点击右上角的“+ 新建”按钮，然后选择“嵌入”。请注意，这仅对管理员可见。
2. 选择要嵌入的实体类型
   • 仪表盘
   • 问题
   • 探索（将嵌入Metabase查询生成器）
   • 浏览器
3. 接下来，选择您要嵌入的实体。对于浏览器，选择您希望用户从哪个集合开始。

选择要嵌入的内容后，单击“下一步”以自定义您的嵌入。

3. 自定义您的嵌入

您看到的具体自定义选项将取决于您嵌入的实体类型。您将看到嵌入在所选选项下的实时预览。有关自定义选项的更多详细信息，请参阅自定义嵌入。

您还可以选择所有嵌入使用的品牌、文本和背景颜色。要配置其他颜色（例如辅助颜色、查询生成器颜色等）以及字体，您可以在嵌入代码片段中指定主题。

您在此交互式流程中选择的所有自定义选项都将反映在嵌入代码中的参数值中，因此您可以稍后通过编辑嵌入代码片段进行调整。

完成嵌入自定义后，点击“下一步”。

4. 选择认证方法

您将获得“现有 Metabase 会话”和“单点登录 (SSO)”之间的选择。

• 如果您选择现有 Metabase 会话，您将能够以您当前登录 Metabase 的用户身份预览您的嵌入，并且只能在与您当前会话相同的浏览器中进行。并非所有浏览器都受支持 - 我们建议使用 Google Chrome。要在其他环境中测试嵌入，您可以使用API 密钥。对于生产使用，请使用SSO。

• 如果您在 Metabase 实例中设置了 JWT，您将能够选择 单点登录 (SSO)，请参阅 设置 SSO。

5. 将嵌入脚本添加到您的应用程序中

Metabase 将生成一个代码片段，您可以复制并粘贴到您的应用程序中，请参阅嵌入代码片段以获取示例。您可以稍后修改此代码片段以指定其他外观选项或更改某些组件的行为。

将代码片段添加到您的应用程序中，然后刷新页面。

嵌入代码片段

使用嵌入式分析 JS 嵌入 Metabase 实体的代码片段应包含三个部分：

1. 从您的 Metabase 实例加载嵌入式分析 JS 库。
2. 用于所有嵌入的全局配置设置，例如您的 Metabase 实例的 URL、外观主题等。请参阅配置嵌入。
3. 用于嵌入 Metabase 实体的组件及其参数。请参阅组件。

这是一个脚本示例

<!-- Load embedding library -->
<!-- REPLACE WITH YOUR METABASE URL HERE -->
<script defer src="https://your-metabase-url/app/embed.js"></script>
<script>
  function defineMetabaseConfig(config) {
    window.metabaseConfig = config;
  }
</script>

<!-- Embedding configuration -->
<script>
  defineMetabaseConfig({
    instanceUrl: "https://your-metabase-url",
    theme: {
      colors: {
        background: "#ffffff",
      },
    },
  });
</script>

<!--Embedded entities -->
<metabase-question question-id="1"></metabase-question>

<metabase-dashboard dashboard-id="2" with-title="false"></metabase-dashboard>

请注意defer属性和脚本中对您的Metabase URL的引用，该脚本加载embed.js库。

如果同一页面中嵌入了多个实体，则只需全局包含一次 <script> 标签。

您还可以通过 Metabase 中的 + 新建 > 嵌入 交互式生成嵌入式分析 JS 的代码片段。请查看快速入门。

自定义嵌入

您看到的具体自定义选项将取决于您嵌入的实体类型。

当您使用“+ 新建 > 嵌入”创建新嵌入时，您将在交互式创建流程中看到以下自定义选项。这些选项对应于组件中的参数。

• 允许用户钻取数据点：决定用户是否可以与图表（或仪表板上的图表）进行交互。交互包括从聚合问题向下钻取到单个记录、点击过滤、放大等。为嵌入式问题禁用钻取还会禁用用户添加筛选器和摘要的功能。

• 允许下载：决定用户是否可以下载问题结果并以 PDF 格式保存仪表板。

• 允许用户保存新问题。如果您嵌入查询生成器但禁用了此选项，用户仍然可以进行自己的探索，只是无法保存它们。

• 参数：对于仪表板过滤器、SQL 变量和时间分组参数，您可以添加默认值。此处设置的默认值会覆盖在仪表板或问题级别设置的默认值。对于仪表板过滤器和参数，您可以选择是否隐藏该参数。

• 显示标题：如标题所示。

• 允许编辑仪表板和问题：允许用户在当前集合中创建和编辑仪表板或问题。禁用后，他们仍然可以执行筛选、汇总和钻取等操作，但无法保存结果。

配置嵌入

要定义适用于页面上所有嵌入的配置，请使用 defineMetabaseConfig() 函数。其参数包括

• instanceUrl: "https://your-metabase-url"（必填）：您的 Metabase 实例的 URL，例如 https://youlooknicetoday.metabaseapp.com

• theme: {...}（可选）：嵌入的外观选项。

• useExistingUserSession: true|false（可选，仅用于开发）- 允许您使用 Metabase 管理员帐户会话在本地预览嵌入。仅支持 Google Chrome。

• apiKey: mb_YourAPIKey（可选，仅用于开发）- 另一种使用 API 密钥在本地预览嵌入的方式。

主题化

您可以使用嵌入配置中的 theme 参数指定颜色、字体、间距和其他外观选项。

例如，此代码定义了文本的字体、颜色和大小、背景颜色以及筛选器和摘要的颜色

<script>
  defineMetabaseConfig({
    instanceUrl: "https://your-metabase-url",
    theme: {
      fontFamily: "Lato",
      fontSize: "16px",
      colors: {
        background: "#11123d",
        "text-primary": "#f9f9fc",
        brand: "#50e397",
        filter: "#7172AD",
        summarize: "#88BF4D",
      },
    },
  });
</script>

请参阅外观。

身份验证

使用现有用户会话测试嵌入

现有会话只能用于在本地测试嵌入。为了使您的嵌入达到生产就绪状态，您需要实现 SSO。

如果您已登录 Metabase，您可以使用现有会话 Cookie 预览和测试您的嵌入。这仅适用于您用于 Metabase 会话的同一浏览器（我们推荐 Chrome）（因此在无痕模式下无法工作）。

在您的嵌入代码中，将 useExistingUserSession: true 添加到 defineMetabaseConfig() 中。请查看配置嵌入。

<script>
  defineMetabaseConfig({
    instanceUrl: "https://your-metabase-url",
    useExistingUserSession: true,
  });
</script>

请注意，这在某些浏览器中或在无痕模式下不起作用。如果您想使用现有的 Metabase 会话来测试您的嵌入，我们建议使用 Chrome。

使用 API 密钥测试嵌入

API 密钥只能用于在本地测试嵌入。要使您的嵌入达到生产就绪状态或将其部署到其他域，您需要实现 SSO。

要使用 API 密钥测试您的嵌入

1. 创建一个API 密钥
2. 将 apiKey: "YOUR_API_KEY" 添加到 defineMetabaseConfig()

<script>
  defineMetabaseConfig({
    instanceUrl: "https://your-metabase-url",
    apiKey: "mb_hopeyouhaveaniceday",
  });
</script>

API 密钥只能用于与受信任的人进行测试。任何可以访问前端的人都可以获取 API 密钥并使用它对 Metabase API 发出请求。因此，我们只允许在 localhost 上使用 API 密钥。

设置 SSO

在 localhost 以外的域中嵌入需要 SSO。您可以使用 JWT 或 SAML SSO。要配置 SAML，请查看使用 SAML 认证。要配置 JWT，请按照以下步骤操作。

1. 在 Metabase 中，配置JWT SSO。

2. 在您的应用程序后端，添加一个新的端点来处理认证。

您需要向后端添加一个库来签署 JSON Web Token。

对于 Node.js，我们推荐 jsonwebtoken

npm install jsonwebtoken --save

接下来，在您的后端设置一个端点（例如 /sso/metabase），该端点使用您的 Metabase JWT 共享密钥为经过身份验证的人员生成 JWT。此端点必须返回一个 JSON 对象，其中包含一个 jwt 属性，该属性包含签名的 JWT。 例如：{ "jwt": "your-signed-jwt" }。

此 Node.js 示例代码使用 Express 设置了一个端点

import express from "express";
import cors from "cors";
import session from "express-session";
import jwt from "jsonwebtoken";
import fetch from "node-fetch";

// Replace this with your Metabase URL
const METABASE_INSTANCE_URL = "YOUR_METABASE_URL_HERE";
// Replace this with the JWT signing secret you generated when enabling
// JWT SSO in your Metabase.
const METABASE_JWT_SHARED_SECRET = "YOUR_SECRET_HERE";

const app = express();

app.get("/sso/metabase", async (req, res) => {
  // Usually, you'd grab the user from the current session
  // Here it's hardcoded for demonstration purposes
  // Example:
  // const { user } = req.session;
  const user = {
    email: "rene@example.com",
    firstName: "Rene",
    lastName: "Descartes",
    group: "Customer",
  };

  if (!user) {
    console.log("no user");
    res.status(401).json({
      status: "error",
      message: "not authenticated",
    });

    return;
  }

  const token = jwt.sign(
    {
      email: user.email,
      first_name: user.firstName,
      last_name: user.lastName,
      groups: [user.group],
      exp: Math.round(Date.now() / 1000) + 60 * 10, // 10 minutes expiration
    },
    METABASE_JWT_SHARED_SECRET,
  );
  // The user backend should return a JSON object with the JWT.
  res.status(200).json({ jwt: token });
});

在嵌入 SDK 文档中查看更多示例。

3. 嵌入将默认自动使用 SSO

默认情况下，Metabase 使用 JWT SSO，但您可以指定其他身份验证方法。要开启 SSO，请确保您没有将配置设置为apiKey或useExistingUserSession。

组件

有不同的组件可用，它们为最终用户提供不同的体验。

虽然您可以使用组件参数来显示或隐藏嵌入式组件的某些部分，但这些参数并不能替代权限。即使您隐藏了内容，用户仍然可以从前端获取其令牌并使用它查询 Metabase API。

仪表盘

渲染仪表板

<metabase-dashboard dashboard-id="1" with-title="true" with-downloads="false">
</metabase-dashboard>

必填参数

• dashboard-id - 这可以是一个常规 ID 或实体 ID。在嵌入中使用实体 ID 可确保在从一个 Metabase 导出到另一个 Metabase 时，ID 保持稳定。

可选参数

• with-title（默认为 true）- 在嵌入中显示仪表板标题
• with-downloads（默认为 false）- 显示将仪表板下载为 PDF 和下载问题结果的按钮
• drills（默认为 true）- 允许您钻取仪表板

• initial-parameters - 仪表板筛选器的默认值，例如 { 'productId': '42' }。

  如果您使用双引号括住属性值，请务必使用单引号

  <metabase-dashboard
    dashboard-id="1"
    initial-parameters="{ 'productId': '42' }"
  ></metabase-dashboard>
  

• hidden-parameters - 从仪表板中隐藏的过滤器名称列表，例如 ['productId']

  如果您使用双引号括住属性值，请务必使用单引号

  <metabase-dashboard
    dashboard-id="1"
    hidden-parameters="['productId']"
  ></metabase-dashboard>
  

问题

渲染一个问题（图表）。

<metabase-question question-id="1"></metabase-question>

必填参数

• question-id - 这可以是一个常规 ID 或实体 ID。在嵌入中使用实体 ID 可确保在从一个 Metabase 导出到另一个 Metabase 时，ID 保持稳定。

  使用 question-id="new" 嵌入查询构建器探索界面。

可选参数

• drills（默认为 true）- 允许您钻取问题
• with-title（默认为 true）- 显示标题
• with-downloads（默认为 false）- 显示下载
• initial-sql-parameters - SQL 参数的默认值，仅适用于原生 SQL 问题，例如 { "productId": "42" }
• is-save-enabled（默认为 false）

• target-collection - 用于强制保存到特定集合。值：常规 ID、实体 ID、"personal”、"root”

• 浏览器

渲染集合浏览器，以便人们可以浏览集合并打开仪表板或问题。

<metabase-browser initial-collection="14" read-only="false"></metabase-browser>

必填参数

• initial-collection - 这可以是一个集合 ID 或 root。使用集合 ID（例如 14）从特定集合开始。使用 root 从顶层“我们的分析”集合开始。

可选参数

• read-only（默认为 true）——如果为 true，用户可以与项目交互（筛选、汇总、钻取）但不能保存。如果为 false，他们可以在集合中创建和编辑项目。