定价
登录 开始使用
文档 学习
首页
分析
嵌入
管理
其他资源

静态嵌入的参数

也称为：签名嵌入或独立嵌入的参数。

参数是在 Metabase 和您的网站之间通过嵌入 URL传递的信息片段。您可以使用参数来指定 Metabase 项目在您网站上的 iframe 中的外观和行为。

参数类型

参数可以是签名的或未签名的。

签名参数

签名参数，例如筛选器名称和值，必须添加到您的服务器代码中。

未签名参数

未签名参数，例如外观设置，应直接添加到 iframe 的 src 属性中。

向静态嵌入添加筛选器小部件

您可以使用可编辑参数向嵌入式仪表板或 SQL 问题添加筛选器小部件。

  1. 转到您的仪表板或 SQL 问题。确保您已设置仪表板筛选器或SQL 变量。
  2. 点击共享图标 > 将此项目嵌入到应用程序中。
  3. 在参数下，您将找到仪表板筛选器或 SQL 变量的名称。
  4. 为应在嵌入中获取筛选器小部件的每个参数选择可编辑。
  5. 点击发布以保存您的更改。
  6. 添加或更新服务器上的代码以匹配 Metabase 生成的代码。

可编辑参数负责将筛选器值从嵌入式筛选器小部件（显示在 iframe 上）传递到原始仪表板或 SQL 问题（在您的 Metabase 中）上的筛选器。

当原始问题或仪表板需要值时，您无法禁用参数

如果仪表板或问题上的筛选器设置为始终需要值，则在嵌入时您将无法禁用该参数。

使用默认值填充嵌入式筛选器小部件

如果您想为可编辑筛选器小部件设置默认值，您可以将该默认值传递到 iframe 的 src 属性中相应的参数名称

your_embedding_url?parameter_name=value

假设您的嵌入式仪表板具有连接到名为“早餐”的可编辑参数的筛选器。如果您想将“早餐”筛选器的默认值设置为“炒鸡蛋”

your_embedding_url?breakfast=Scrambled_eggs

要为多个筛选器指定默认值，请用和号 (&) 分隔筛选器

your_embedding_url?breakfast=Scrambled_eggs&lunch=Grilled_cheese

您可以通过用和号 (&) 分隔 key=value 对来为一个筛选器设置多个默认值

your_embedding_url?breakfast=Scrambled_eggs&breakfast=Bacon

从静态嵌入中隐藏筛选器小部件

如果您有很多可编辑参数（导致很多筛选器小部件），您可以通过在 iframe 的 src 属性中的 URL 末尾添加 #hide_parameters 来从静态嵌入中隐藏它们

your_embedding_url#hide_parameters=parameter_name

例如，如果您想从嵌入式仪表板中隐藏名为“早餐”的筛选器

your_embedding_url#hide_parameters=breakfast

您可以通过用逗号分隔参数名称来隐藏多个筛选器小部件

your_embedding_url#hide_parameters=breakfast,lunch

您还可以同时为参数分配默认值并隐藏其筛选器小部件

your_embedding_url?breakfast=Scrambled_eggs#hide_parameters=breakfast

未签名参数语法

每当您将参数添加到 iframe 的 src 属性中的嵌入 URL 时，请注意

  • 参数名称为小写。
  • 参数值区分大小写（值必须与您的数据匹配）。
  • 空格应替换为下划线。

使用锁定参数限制静态嵌入中的数据

如果您想限制嵌入式仪表板或 SQL 问题中显示的数据，您可以设置锁定参数。锁定参数在结果显示给静态嵌入中的人员之前筛选仪表板或 SQL 问题中的数据。

  1. 转到您的仪表板或 SQL 问题。确保您已设置仪表板筛选器或SQL 变量。
  2. 点击共享图标 > 将此项目嵌入到应用程序中。
  3. 在参数下，您将找到仪表板筛选器或 SQL 变量的名称。
  4. 为您要使用其限制数据的每个参数选择锁定。
  5. 可选：在预览锁定参数下选择一个值，以查看受限数据的外观。
  6. 点击发布以保存您的更改。
  7. 添加或更新服务器上的代码以匹配 Metabase 生成的代码。

您可以使用锁定参数来显示基于您的 Web 服务器捕获的属性（例如用户名或租户 ID）的筛选数据。有关更多示例，请参阅参考应用仓库。

锁定参数会将选定的筛选器值应用于原始仪表板或 SQL 问题，但它们不会作为筛选器小部件显示在您的嵌入中。锁定参数也可能限制您的可编辑筛选器小部件中显示的值。

如果您只是想要求参数的值，您可以将筛选器设置为可编辑，并将底层问题或仪表板配置为始终需要值。

更新锁定参数

如果您需要更改锁定参数，请记住以下几点。

在服务器代码中包含所有锁定参数

一旦您发布带有锁定参数的图表或仪表板，您必须在服务器代码中包含锁定参数的名称。如果您排除参数名称，日志将温和地提醒您：您必须在 JWT 中为 :parameter 指定一个值。

要关闭锁定参数，请在 JWT 中传递一个空数组作为其值

如果您不希望应用锁定筛选器，您可以在 JWT 中传递一个空数组 [] 作为参数的值。

确保筛选器名称与锁定参数名称匹配

如果您更改了用作锁定参数的查询构建器筛选器的名称，请确保也更新服务器代码中的参数名称和值。如果您的锁定参数连接到SQL 变量，则无需更改参数的名称和值。

多个锁定参数或多个值

服务器代码中锁定参数的值应与筛选器的值完全匹配。设置多个锁定参数或将多个值传递给锁定参数的最佳方法是在预览锁定参数下选择一个筛选器值，并预览 Metabase 生成的服务器代码。

一起使用多个锁定参数将使用 AND 而不是 OR 进行筛选。如果您只想应用锁定参数的子集，则必须告诉 Metabase 忽略其他锁定参数。

锁定参数限制其他可编辑参数可用的值

由于锁定参数在结果显示在嵌入中之前筛选数据，因此锁定参数会限制其他可编辑筛选器小部件可用的值。

例如，假设您要嵌入一个带有两个筛选器（州和城市）的仪表板。如果您使用值“佛蒙特州”锁定州参数，Metabase 将仅在仪表板上显示城市筛选器小部件，并且该城市筛选器小部件的下拉菜单将仅限于佛蒙特州的城市。虽然您没有显式链接这两个筛选器，但这两个筛选器的行为隐式地类似于联动筛选器。

带有 SQL 问题的仪表板上的锁定参数

如果您的锁定参数链接到仪表板筛选器，而该筛选器又链接到 SQL 问题，则您只能为锁定参数选择单个值。

例如，假设您有一个名为“早餐”的仪表板筛选器，其值包括“土豆饼”、“松饼”和“华夫饼”。如果“早餐”筛选器链接到仪表板上的任何 SQL 问题，您将只能为链接到“早餐”筛选器的锁定参数选择一个选项。

使用锁定参数为应用程序中的自定义小部件提供支持

由于 Metabase 不会将锁定参数显示为筛选器小部件，因此您可以使用锁定参数为在您的应用程序中构建的自定义筛选器小部件提供支持。您可能需要构建自己的筛选器小部件以

  • 使小部件与您的应用程序的外观和风格更加一致。
  • 包含自定义逻辑。例如，让筛选器小部件记住最近的值。
  • 在应用程序的不同部分以不同的方式重用一个仪表板。例如，您可能有一个带有多个锁定参数的仪表板，在一个案例中使用一个参数，在另一个案例中使用另一个参数。就像一个销售仪表板，在应用程序的一部分中按“区域”锁定，在另一部分中按“团队”锁定。

自定义静态嵌入的外观

Look and feel: appearance settings on static embed

您可以通过在 iframe 的 src 属性中的 URL 末尾添加哈希参数（例如，#theme=night）来更改嵌入项目的外观。

例如，以下嵌入 URL 将以暗模式、无边框且带有其原始标题显示嵌入项目

your_embedding_url#theme=night&bordered=false&titled=true

您可以从问题或仪表板的嵌入外观设置中预览外观设置。

参数名称 可能的值
background true（默认），false。仅限仪表板。
bordered true（默认），false。
locale\* 例如，locale=ko。请参阅语言区域列表
titled true（默认），false。
theme null（默认），night。theme=transparent应该可以工作，但已弃用（请参阅透明背景）
refresh（仅限仪表板） 整数（秒，例如，refresh=60）。
font* 字体名称
downloads** true（默认），false。

* 在 Pro 和 Enterprise 计划中可用

** 禁用下载在 Pro 和 Enterprise 计划中可用。

有关全局外观设置（例如，在整个 Metabase 实例中使用的颜色和字体）的信息，请参阅自定义 Metabase 的外观。

设置静态嵌入的语言

静态嵌入的语言设置仅在 Pro 和 Enterprise 计划中可用（包括自托管和 Metabase 云）。

要更改静态嵌入的 UI 语言，您可以设置其 locale。例如，要将公共链接的语言设置为韩语，您可以附加 #locale=ko。

https://metabase.example.com/public/dashboard/7b6e347b-6928-4aff-a56f-6cfa5b718c6b?category=&city=&state=#locale=ko

如果您有多个参数，请使用 & 符号分隔它们 &

category=Gadget&state=Vermont#theme=night&locale=ko

locale 参数仅更改 Metabase UI 元素的语言。内容的语言由创建该项目的人员定义。例如，Metabase 不会翻译问题的名称，但 Metabase 会翻译 UI 文本“导出为 PDF”。

嵌入的透明背景

使嵌入透明取决于嵌入的类型

  • 仪表盘：设置 background=false。background 参数可以与 theme 参数组合使用（例如，background=false&theme=night）。
  • 问题：设置 theme=transparent（已弃用，但仍受支持）。

禁用嵌入问题或仪表盘的下载

禁用下载仅在 Pro 和 Enterprise 计划中可用（包括自托管和 Metabase 云）。

默认情况下，Metabase 将在嵌入式问题上包含一个下载按钮，并在嵌入式仪表盘上包含导出为 PDF选项。您可以通过在 iframe 的 src 属性的嵌入 URL 中设置 downloads=false 来删除下载结果的选项，请参阅自定义静态嵌入的外观。

如果您期望下载选项可用但却缺失，请检查您的 iframe 的 src 属性中的 URL 是否包含参数 downloads=true。

最大请求大小

静态嵌入 URL（包括所有参数）的最大长度是您的 MB_JETTY_REQUEST_HEADER_SIZE 环境变量的值。默认值为 8192 字节。

如果您的静态嵌入 URL 超过最大标头大小，您将看到类似 URI too long 的日志消息。您可以更新环境变量以接受更大的标头。如果您正在使用代理服务器，您可能还需要在服务器上设置相应的属性。

延伸阅读