v0.53

交互式嵌入

交互式嵌入仅在 Pro 和 Enterprise 计划（自托管和 Metabase Cloud）中可用。

如果您想提供多租户自助分析，交互式嵌入是您的理想选择。

交互式嵌入是唯一一种与您的权限和 SSO 集成的嵌入类型，可为用户提供适当级别的访问权限，以查询和向下钻取到您的数据中。

交互式嵌入演示

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

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

快速入门

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

交互式嵌入的先决条件

确保您拥有许可证令牌，适用于 Pro 或 Enterprise 计划。
将人员组织到 Metabase 群组中。
为每个群组设置权限。
设置 SSO 以自动应用权限，并在用户登录时向其显示正确的数据。通常，我们建议使用带有 JWT 的 SSO。

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

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

在 Metabase 中启用交互式嵌入

转到设置 > 管理设置 > 嵌入。
单击启用。
单击交互式嵌入。
在授权来源下，添加您要嵌入 Metabase 的网站或 Web 应用的 URL（例如 https://*.example.com）。

在您的网站上设置嵌入

创建一个 iframe，并将 src 属性设置为
- 您要嵌入的 Metabase 页面的URL，或者
- 重定向到您的 Metabase URL 的身份验证端点。
可选：根据您的 Web 应用的设置方式，设置环境变量以
可选：使用受支持的 postMessage 消息启用与嵌入式 Metabase 的通信
- 来自 Metabase
- 发送到 Metabase
可选：设置参数以显示或隐藏 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 结构：/[Item type]/entity/[Entity-Id]。示例

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

将 iframe 指向身份验证端点

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

您需要将 src 属性设置为您的身份验证端点，并使用指向编码后的 Metabase URL 的 return_to 参数。例如，要将用户发送到您的 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 由 Web 地址的最后一部分指示，例如 .com 或 .org。

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

在不同的域中嵌入 Metabase

如果您的 Metabase 和嵌入应用已在同一顶级域 (TLD) 中，请跳过本节。

如果您想在另一个域中嵌入 Metabase（例如，如果 Metabase 托管在 metabase.yourcompany.com，但您想在 yourcompany.github.io 中嵌入 Metabase），您可以告知 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 的“frame”消息（模式为“normal”）

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

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

{
  "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 组件

要更改交互式嵌入的界面，您可以将参数添加到嵌入 URL 的末尾。如果您想更改嵌入中的颜色或字体，请参阅自定义外观。

例如，您可以像这样禁用 Metabase 的顶部导航栏和侧边导航菜单

your_embedding_url?top_nav=false&side_nav=false

Top nav and side nav disabled

选项包括

操作按钮
附加信息
面包屑
标题
区域设置
徽标
新建按钮
搜索
侧边导航
顶部导航

为了确保在使用点击行为时保留查询参数，请将站点 URL 管理设置配置为您的 Metabase 服务器 URL。

`action_buttons`

当 header 启用时，默认在问题页面上可见。

要隐藏操作按钮（例如筛选、汇总、查询构建器按钮等）

header=false&action_buttons=false

Action buttons

`additional_info`

当 header 启用时，默认在问题和仪表盘页面上可见。

要隐藏灰色文本“由 FirstName LastName 于 X 天前编辑”，以及包含集合、数据库和表名称的面包屑

header=false&additional_info=false

Additional info

`breadcrumbs`

默认情况下在顶部导航栏中显示。集合面包屑显示项目的路径（即，项目所在的集合）。要隐藏面包屑

breadcrumbs=false

`header`

默认情况下在问题和仪表盘页面上可见。

要隐藏问题或仪表盘的标题、附加信息和操作按钮

header=false

`locale`

您可以通过参数更改用户界面的语言。例如，要将区域设置设置为西班牙语

locale=es

阅读有关本地化的更多信息。

`logo`

是否显示用于打开和关闭侧边栏导航的徽标。默认为 true。Metabase 显示徽标的方式取决于 side_nav 设置。以下是这两个参数如何交互的粗略分解

如果 logo=true 并且

side_nav=true：看起来像常规 Metabase（带有您设置的任何徽标）。
side_nav=false：没有侧边栏，因此当您将鼠标悬停在徽标上时，不会发生任何事情。

如果 logo=false 并且

side_nav=true：Metabase 显示通用侧边栏图标，正常状态下为灰色，悬停时为品牌颜色。
side_nav=false：没有侧边导航栏和 logo，所以面包屑导航会移动到屏幕的最左侧。

`new_button`

默认隐藏。用于显示创建查询或仪表板的 + New 按钮

top_nav=true&new_button=true

`search`

默认隐藏。用于在顶部导航栏中显示搜索框

top_nav=true&search=true

`side_nav`

导航侧边栏在 /collection 和主页路由上显示，默认在其他任何地方隐藏。

允许用户最小化侧边栏

top_nav=true&side_nav=true

`top_nav`

默认显示。用于隐藏顶部导航栏

top_nav=false

search、new_button 和 breadcrumbs 都依赖于 top_nav 设置为 true。如果这三个子项（search、new_button 和 breadcrumbs）都为 false，Metabase 将隐藏顶部导航栏。

参考应用

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

Node.js + Express (带有快速入门指南)
Node.js + React

延伸阅读

阅读其他Metabase 版本的文档。

商业智能

嵌入式分析

文档

学习

分析

嵌入

管理

其他资源