交互式嵌入

仅需一小时即可构建一个可运行的 POC。

参加我们下一期交互式嵌入研讨会。

立即注册

如果您想提供多租户自助分析，那么交互式嵌入是您所需要的。

交互式嵌入是唯一一种与您的权限和单点登录 (SSO) 集成，以向用户提供适当访问级别，用于查询和下钻数据的功能。

交互式嵌入演示

要了解交互式嵌入的功能，请查看我们的交互式嵌入演示。

要查看查询构建器的实际操作，请点击报告 > + 新建 > 问题。

快速入门

查看交互式嵌入快速入门。

交互式嵌入的先决条件

1. 请确保您拥有 Pro 或 Enterprise 计划的许可证令牌。
2. 将用户组织到 Metabase 群组中。
3. 为每个群组设置权限。
4. 设置单点登录 (SSO) 以在用户登录时自动应用权限并显示正确的数据。通常，我们建议使用基于 JWT 的 SSO。

如果您正在处理多租户情况，请查看我们关于为不同客户模式配置权限的建议。

如果您的应用程序在本地运行，并且您使用的是 Pro 云版本，或者 Metabase 和您的应用程序托管在不同的域中，则需要将 Metabase 环境的会话 cookie 的 SameSite 选项设置为“none”。

在 Metabase 中启用交互式嵌入

1. 前往设置 > 管理设置 > 嵌入。
2. 点击启用。
3. 点击交互式嵌入。
4. 在授权来源下，添加您要嵌入 Metabase 的网站或 Web 应用程序的 URL（例如 https://*.example.com）。

在您的网站上设置嵌入

1. 创建一个 iframe，其 src 属性设置为
   • 您要嵌入的 Metabase 页面的URL，或
   • 一个身份验证端点，该端点会重定向到您的 Metabase URL。
2. 可选：根据您的 Web 应用程序的设置方式，设置环境变量以
   • 添加您的许可证令牌.
   • 在不同域中嵌入 Metabase.
   • 保护您的交互式嵌入.
3. 可选：使用支持的 postMessage 消息启用与嵌入式 Metabase 的通信
   • 从 Metabase
   • 到 Metabase
4. 可选：设置参数以显示或隐藏 Metabase UI 组件。

一旦您准备好推出交互式嵌入，请确保用户允许来自 Metabase 的浏览器 cookie，否则他们将无法登录。

将 iframe 指向 Metabase URL

前往您的 Metabase 并找到您要嵌入的页面。

例如，要嵌入您的 Metabase 主页，请将 src 属性设置为您的站点 URL，例如

src="http://metabase.yourcompany.com/"

要嵌入特定的 Metabase 仪表盘，您需要使用仪表盘的实体 ID URL /dashboard/entity/[Entity ID]。

src="http://metabase.yourcompany.com/dashboard/entity/[Entity ID]"

要获取仪表盘的实体 ID，请访问该仪表盘并点击信息按钮。在概览选项卡中，复制实体 ID。然后将其添加到您 iframe 的 src 属性中

src=http://metabase.yourcompany.com/dashboard/entity/Dc_7X8N7zf4iDK9Ps1M3b

如果您的仪表盘有多个选项卡，请选择您希望用户访问的选项卡并复制其 ID。将该选项卡的 ID 添加到 URL 中

src=http://metabase.yourcompany.com/dashboard/entity/Dc_7X8N7zf4iDK9Ps1M3b?tab=YLNdEYtzuSMA0lqO7u3FD

您可以使用仪表盘的顺序 ID，但应优先使用实体 ID，因为实体 ID 在不同的 Metabase 环境中是稳定的（例如，如果您在暂存环境中进行测试，则在将数据导出并导入到生产环境时，实体 ID 将保持不变）。

如果您想指向问题、集合或模型，请访问该项，点击其信息，获取该项的实体 ID，然后遵循 URL 结构：/[项目类型]/entity/[实体 ID]。示例

• /collection/entity/[实体 ID]
• /model/entity/[实体 ID]
• /question/entity/[实体 ID]

将 iframe 指向身份验证端点

如果您想将用户直接发送到您的 SSO 登录屏幕（即跳过带有 SSO 按钮的 Metabase 登录屏幕），并在身份验证后自动重定向到 Metabase，请使用此选项。

您需要将 src 属性设置为您的身份验证端点，并带有一个 return_to 参数，该参数指向编码后的 Metabase URL。例如，要将用户发送到您的 SSO 登录页面并在身份验证后自动将其重定向到 http://metabase.yourcompany.com/dashboard/1

https://metabase.example.com/auth/sso?return_to=http%3A%2F%2Fmetabase.yourcompany.com%2Fdashboard%2F1

如果您正在使用 JWT，您可以使用重定向的相对路径（即，不带站点 URL 的 Metabase URL）。例如，要将用户发送到 /dashboard/1 的 Metabase 页面

https://metabase.example.com/auth/sso?jwt=<token>&return_to=%2Fdashboard%2F1

您必须对重定向链接中的所有参数进行 URL 编码（或双重编码，取决于您的 Web 设置），包括筛选器参数（例如 filter=value）和UI 设置（例如 top_nav=true）。例如，如果您在上面显示的 JWT 示例中添加了两个筛选器参数，您的 src 链接将变为

https://metabase.example.com/auth/sso?jwt=<token>&redirect=%2Fdashboard%2F1%3Ffilter1%3Dvalue%26filter2%3Dvalue

跨浏览器兼容性

为了确保您嵌入的 Metabase 在所有浏览器中都能正常工作，请将 Metabase 和嵌入应用程序置于相同的顶级域 (TLD) 中。TLD 由网址的最后一部分表示，例如 .com 或 .org。

请注意，您的交互式嵌入必须与 Safari 兼容才能在 iOS 中的任何浏览器（例如 iOS 上的 Chrome）上运行。

在不同域中嵌入 Metabase

如果您的 Metabase 和嵌入应用程序已在相同的顶级域 (TLD) 中，请跳过此部分。

如果您想在另一个域中嵌入 Metabase（例如，如果 Metabase 托管在 metabase.yourcompany.com，但您想将 Metabase 嵌入到 yourcompany.github.io），您可以告诉 Metabase 将会话 cookie 的 SameSite 值设置为“none”。

您可以在管理设置 > 嵌入 > 交互式嵌入 > SameSite cookie 设置中将会话 cookie 的 SameSite 值。

SameSite 值包括

• Lax（默认）：允许在用户从外部站点导航到源站点时（例如点击链接时）发送 cookie。
• None：允许所有跨站点请求。与大多数 Safari 和 iOS 浏览器（例如 iOS 上的 Chrome）不兼容。如果您将此环境变量设置为“None”，则必须在 Metabase 中使用 HTTPS 以防止浏览器拒绝请求。
• Strict（不推荐）：绝不允许在跨站点请求中发送 cookie。警告：这将阻止用户通过外部链接访问 Metabase。

您还可以设置 MB_SESSION_COOKIE_SAMESITE 环境变量。

如果您正在使用 Safari，您需要允许跨站点跟踪。根据浏览器不同，在隐私/无痕模式下查看嵌入项时也可能会遇到问题。

了解更多关于 SameSite cookie 的信息。

保护交互式嵌入

Metabase 使用 HTTP cookie 来验证用户身份并让他们保持登录到您的嵌入式 Metabase 中，即使他们关闭浏览器会话也是如此。如果您喜欢图解的身份验证流程，请查看使用 SSO 进行交互式嵌入。

要限制用户的登录时间，请将 MAX_SESSION_AGE 设置为一个分钟数。默认值为 20,160（两周）。

例如，要让用户最多登录 24 小时

MAX_SESSION_AGE=1440

在用户结束浏览器会话时自动清除其登录 cookie

MB_SESSION_COOKIES=true

要手动将用户从 Metabase 中注销，请加载以下 URL（例如，在您应用程序的注销页面上的隐藏 iframe 中）

https://metabase.yourcompany.com/auth/logout

如果您正在使用 JWT 进行 SSO，我们建议将 exp（过期时间）属性设置为较短的持续时间（例如 1 分钟）。

嵌入式 Metabase 支持的 postMessage 消息

为了跟上嵌入式 Metabase URL 的变化（例如，当应用筛选器时），请设置您的应用程序来监听来自嵌入式 Metabase 的“location”消息。如果您想将此消息用于深度链接，请注意“location”镜像了“window.location”。

{
  "metabase": {
    "type": "location",
    "location": LOCATION_OBJECT_OR_URL
  }
}

要使嵌入式 Metabase 页面（如问题）填满应用程序中的整个 iframe，请设置您的应用程序来监听来自 Metabase 的“normal”模式的“frame”消息

{
  "metabase": {
    "type": "frame",
    "frame": {
      "mode": "normal"
    }
  }
}

要指定应用程序中 iframe 的大小以使其与嵌入式 Metabase 页面（如仪表盘）匹配，请设置您的应用程序来监听来自 Metabase 的“fit”模式的“frame”消息

{
  "metabase": {
    "type": "frame",
    "frame": {
      "mode": "fit",
      "height": HEIGHT_IN_PIXELS
    }
  }
}

发送到嵌入式 Metabase 的 postMessage 消息

要更改嵌入 URL，请从您的应用程序向 Metabase 发送“location”消息

{
  "metabase": {
    "type": "location",
    "location": LOCATION_OBJECT_OR_URL
  }
}

群组策略与沙盒

如果您希望单个客户账户中的多名用户在问题和仪表盘上进行协作，则需要为每个客户账户设置一个群组。

您可以使用一个单独的群组来处理数据沙盒，该群组仅用于数据沙盒。例如，每个人都可以属于一个客户群组，该群组通过适用于所有客户账户的特定属性来设置具有沙盒功能的数据权限。

此外，单个客户账户中的每个人也可以是该客户账户特定群组的成员。这样，他们就可以与组织中的其他人协作处理集合，而不会看到其他客户账户的人员创建的内容。

显示或隐藏 Metabase UI 组件

参阅交互式 UI 组件

参考应用

要使用基于 JWT 的 SSO 构建交互式嵌入示例，请参阅我们的参考应用

• Node.js + Express（附带快速入门指南）
• Node.js + React

延伸阅读

• 交互式嵌入快速入门
• 提供客户导向型分析的策略.
• 权限策略.
• 自定义 Metabase 外观.