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

静态嵌入参数

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

参数是通过嵌入 URL 在 Metabase 和您的网站之间传递的信息。您可以使用参数来指定 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

例如，如果您的嵌入式仪表板有一个连接到名为“Breakfast”的可编辑参数的过滤器，并且您想将默认值设置为“Hash browns”

your_embedding_url?breakfast=Hash_browns

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

your_embedding_url?breakfast=Hash_browns&lunch=Sandwich

您可以通过使用和号 (&) 分隔值来为一个过滤器设置多个默认值

your_embedding_url?breakfast=Hash_browns&breakfast=Pancakes

从静态嵌入中隐藏过滤器组件

如果您有多个可编辑参数（导致多个过滤器组件），您可以通过在 iframe src 属性的 URL 末尾添加 #hide_parameters 来从静态嵌入中隐藏特定的参数

your_embedding_url#hide_parameters=parameter_name

例如，要从嵌入式仪表板中隐藏名为“Breakfast”的过滤器

your_embedding_url#hide_parameters=breakfast

您可以通过逗号分隔参数名称来隐藏多个过滤器组件

your_embedding_url#hide_parameters=breakfast,lunch

您还可以同时为一个参数分配默认值并隐藏其过滤器组件

your_embedding_url?breakfast=Hash_browns#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忽略其他锁定参数。

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

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

例如，假设您正在嵌入一个包含两个过滤器（州和城市）的仪表板。如果您将州参数锁定为“Vermont”，Metabase 将只在仪表板上显示城市过滤器组件，并且该城市过滤器组件的下拉菜单将仅限于佛蒙特州的城市。虽然您没有明确链接这两个过滤器，但这两个过滤器会隐式地像关联过滤器一样工作。

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

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

例如，假设您有一个名为“Breakfast”的仪表板过滤器，其值为“Hash browns”、“Muffin”和“Waffles”。如果“Breakfast”过滤器链接到仪表板上的任何 SQL 问题，您将只能为链接到“Breakfast”过滤器的锁定参数选择其中一个选项。

使用锁定参数为应用中的自定义组件提供支持

由于 Metabase 不会将锁定参数显示为过滤器组件，您可以使用锁定参数来为在您的应用中构建的自定义过滤器组件提供支持。您可能希望构建自己的过滤器组件以

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

自定义静态嵌入的外观

Look and feel: appearance settings on static embed

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

例如，以下嵌入 URL 将以深色模式显示嵌入项，无边框，并带有其原始标题

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

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

参数名称 可能的值
背景 true（默认），false。仅适用于仪表板。
有边框 true（默认），false。
语言环境* 例如，ko。请参阅语言环境列表
带标题的 true（默认），false。
主题 null（默认），night。theme=transparent 应该有效，但已弃用（请参阅透明背景）
refresh（仅限仪表板） 整数（秒，例如，refresh=60）。
字体* 字体名称
下载** true（默认），false，results，pdf

* 在专业版和企业版计划中可用

** 禁用下载功能在专业版和企业版计划中可用。

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

设置静态嵌入的语言

静态嵌入的本地化功能仅适用于专业版和企业版计划（包括自托管和 Metabase Cloud）。

要更改静态嵌入的 UI 语言，您可以设置其区域设置。例如，要将公共链接的语言设置为韩语，请附加 #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（已弃用，但仍受支持）。

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

禁用下载功能仅适用于专业版和企业版计划（包括自托管和 Metabase Cloud）。

默认情况下，Metabase 会在嵌入式问题上包含一个下载按钮，并在嵌入式仪表板上包含一个导出为 PDF 选项。

您可以使用 iframe 的 src 属性中的嵌入 URL 中的 downloads 参数配置这些选项，请参阅自定义静态嵌入的外观。

downloads 接受以下值

  • true（默认值）：包括下载和导出为 PDF 两个选项。
  • false：隐藏下载和导出为 PDF 两个选项。
  • results：显示下载选项。
  • pdf：显示导出为 PDF 选项（仅限仪表板）。

您可以组合显式选项：downloads=results,pdf 与 downloads=true 相同。

downloads 参数取代了旧版 hide_download_button 参数。

最大请求大小

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

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

进一步阅读

阅读其他Metabase 版本的文档。

© . All rights reserved.