静态嵌入参数

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

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

仅需一小时，构建一个可行的概念验证（POC）。

加入我们的下一次交互式嵌入工作坊。

立即注册

参数类型

参数可以是有符号的或无符号的。

签名参数

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

• 可编辑参数
• 锁定参数

未签名参数

未签名参数，如外观设置，应直接添加到 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 忽略其他锁定参数。

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

因为锁定参数在结果显示在嵌入中*之前*筛选数据，所以锁定参数限制了其他可编辑筛选器小组件的可用值。

例如，假设您正在嵌入一个带有两个筛选器（州和城市）的仪表盘。如果您用值“佛蒙特州”锁定州参数，Metabase 将只在仪表盘上显示城市筛选器小组件，并且该城市筛选器小组件的下拉菜单将仅限于佛蒙特州的城市。虽然您没有明确链接这两个筛选器，但这两个筛选器的行为隐含地像链接的筛选器。

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

如果您的锁定参数链接到一个仪表盘筛选器，而该筛选器又链接到一个 SQL 问题，那么您将只能为您的锁定参数选择*一个*值。

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

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

因为 Metabase 不会将锁定参数显示为筛选器小组件，所以您可以使用锁定参数来为您在应用中构建的自定义筛选器小组件提供支持。您可能希望构建自己的筛选器小组件以便：

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

自定义静态嵌入的外观

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

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

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

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

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

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

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

为静态嵌入设置语言

要更改静态嵌入的 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 元素的语言，例如“导出为 PDF”按钮的标签。要更改静态嵌入中*内容*的语言（如问题和仪表盘的名称），您需要上传翻译词典。

嵌入的透明背景

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

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

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

默认情况下，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 的日志消息。您可以更新环境变量以接受更大的头。如果您正在使用代理服务器，您可能还需要在服务器上设置相应的属性。

延伸阅读

• 静态嵌入文档.
• 提供面向客户的分析的策略.
• 将数据可视化发布到 Web.