已签名的嵌入

签名嵌入是一种向用户呈现私密嵌入的 Look、可视化图表、探索、信息中心或 LookML 信息中心的方式,用户无需登录单独的 Looker。而是通过您自己的应用对用户进行身份验证。

签名嵌入功能的工作原理是,创建一个特殊的 Looker 网址,您将在 iframe 中使用该网址。该网址包含您要分享的信息、您系统中的用户 ID,以及您希望用户拥有的权限。然后,您将使用 Looker 提供的密钥对网址进行签名。

对于公开嵌入,请参阅公开共享、导入和嵌入 Look 文档页面中的使用 iframe 标记进行公开嵌入部分。

在 Looker 实例中使用签名嵌入之前,Looker 管理员必须在 Looker 的管理面板中启用签名嵌入,并创建嵌入密钥。如需相关说明,请参阅嵌入使用入门 - 启用签名嵌入 文档页面。

签名嵌入的正确托管方式

某些浏览器(例如 Safari)或安装了会屏蔽广告或跟踪 Cookie 的扩展程序的浏览器默认采用会屏蔽第三方 Cookie 的 Cookie 政策。启用不使用 Cookie 的嵌入式功能后,阻止第三方 Cookie 的浏览器可以在不同网域的嵌入式 iframe 中对用户进行身份验证。无 Cookie 嵌入式身份验证需要进行服务器端配置。如需查看设置示例,请参阅无 Cookie 嵌入文档页面。

如果未启用不使用 Cookie 的嵌入式功能,Looker 会使用 Cookie 进行用户身份验证。在这种情况下,在阻止第三方 Cookie 的浏览器中,无法尝试跨网域对嵌入式 iframe 进行身份验证(除非用户修改其浏览器的 Cookie 隐私设置)。例如,如果您想嵌入 https://mycompany.com 上的信息,则需要确保 Looker 与该网站共享同一网域,例如 https://analytics.mycompany.com。在这种情况下,如果 Looker 托管您的实例,请与 Looker 支持团队联系,以设置必要的 DNS 配置,从而启用自定义网域。这样一来,Looker 便可与嵌入式应用共享同一网域,并利用第一方 Cookie(所有浏览器默认接受此类 Cookie)。

如果您使用的是客户托管型 Looker 实例,请确保将使用已签名嵌入的应用与您的 Looker 实例使用相同的网域。

通过封闭式系统控制客户端可见性

在已签名的嵌入配置中,Looker 用户通常会向自己的客户展示数据,同时也会有来自不同公司或群组的客户,这些客户彼此之间不应了解对方。在这种情况下,为保护客户的私密信息,我们强烈建议您将 Looker 配置为封闭式系统,也称为多租户安装。在封闭式系统中,内容会进行隔离,以防止不同群组的用户相互了解。因此,我们建议您在向任何外部用户授予对实例的访问权限之前,先启用封闭系统选项。

如需了解详情,请参阅设计和配置访问权限级别系统和嵌入式分析的安全最佳实践文档页面。

生成已签名的嵌入网址

您可以通过多种方式生成签名嵌入网址。您可以使用以下方法之一:

手动对已签名的嵌入网址进行编码

如需对已签名的嵌入网址进行编码,请先收集必要的 Looker 信息,然后创建已签名的嵌入网址。

收集必要的 Looker 信息

首先,您需要确定需要包含的所有信息,以便以此为起点构建网址。您需要有:

嵌入网址

检索要嵌入的 Look、探索、查询可视化图表或信息中心的网址。然后,移除网域并将 /embed 放在路径前面,如下所示:

项 常规网址格式 嵌入网址
Look https://instance_name.looker.com/looks/4 /embed/looks/4
探索 https://instance_name.looker.com/explore/my_model/my_explore /embed/explore/my_model/my_explore
查询可视化 https://instance_name.looker.com/explore/my_model/my_explore?qid=1234567890abcdefghij12

探索网址中 qid= 参数后面的 22 个字母数字字符组成了 Query.client_id。Query.client_id 值是一个唯一字符串,表示查询和可视化设置。

如需嵌入查询可视化图表,请检索查询可视化图表的 Query.client_id 值,并将 Query.client_id 复制到嵌入网址中。

您可以使用 Looker 探索界面构建包含受支持的可视化图表的查询,并从 qid= 参数中复制 Query.client_id 值;也可以使用 Looker API(例如 Get Query 方法)检索 Query.client_id。
/embed/query-visualization/Query.client_id
用户定义的信息中心 https://instance_name.looker.com/dashboards/1

包含任何会隐藏过滤条件值的过滤条件值,即信息中心网址中的 hide_filter 参数。
LookML 信息中心 https://instance_name.looker.com/dashboards/my_model::my_dashboard /embed/dashboards/my_model::my_dashboard
对话式分析 对于对话页面:https://instance_name.looker.com/conversations

对于代理页面:https://instance_name.looker.com/agents

对于特定对话:https://instance_name.looker.com/conversations/conversation_id

如需了解详情,请参阅嵌入式对话分析文档页面。
/embed/conversations

/embed/agents

/embed/conversations/c9f370ac830b4669aeb494396422004c

权限

权限集用于定义用户或群组可以执行的操作。权限可以通过以下两种方式之一进行应用:

  • 特定于模型:此类权限仅适用于属于同一角色的模型集。
  • 实例级:此类权限适用于整个 Looker 实例。具有实例级权限的嵌入式用户可以在整个 Looker 实例中执行某些功能,但无法访问基于其角色模型集中未包含的模型的内容。

确定您希望用户拥有的权限。下表列出了所有可用于已签名嵌入的权限。以下列表中未列出的权限不支持签名嵌入:

权限 取决于 类型 定义
access_data 无 特定于模型 允许用户访问数据(查看 Look、信息中心或探索时需要此权限)
see_lookml_dashboards access_data 特定于模型 允许用户查看 LookML 信息中心。即使用户对信息中心所在的文件夹拥有查看权限,也需要此权限。
see_looks access_data 特定于模型 允许用户查看 Look
see_user_dashboards see_looks 特定于模型 允许用户查看用户定义的信息中心,并从嵌入式界面浏览文件夹
explore see_looks 特定于模型 允许用户查看“探索”页面
create_table_calculations explore 实例级 需要在探索中创建表计算
create_custom_fields explore 实例级 需要在探索中创建自定义字段
can_create_forecast explore 实例级 允许用户在可视化图表中创建或修改预测。
save_content see_looks 实例级 允许用户对 Look 和信息中心进行更改并保存
send_outgoing_webhook see_looks 特定于模型 允许用户将 Looker 内容交付安排到任意 webhook
send_to_s3 see_looks 特定于模型 允许用户将 Looker 内容交付安排到 Amazon S3 存储桶
send_to_sftp see_looks 特定于模型 允许用户安排将 Looker 内容递送到 SFTP 服务器
schedule_look_emails see_looks 特定于模型 允许用户将 Looker 内容的传送安排到自己的电子邮件地址(如果设置了名为“email”的用户属性)或电子邮件网域许可名单设置的限制范围内的电子邮件地址。允许具有 create_alerts 权限的用户向 电子邮件网域许可名单设置的限制范围内的电子邮件地址发送提醒通知。
schedule_external_look_emails schedule_look_emails 特定于模型 允许用户安排将 Looker 内容递送到任何电子邮件网域。允许具有 create_alerts 权限的用户向任何电子邮件网域发送提醒通知。
send_to_integration see_looks 特定于模型 让用户可以通过 Looker Action Hub 将 Looker 内容传递到与 Looker 集成的第三方服务。此权限与数据操作无关。
schedule_without_limit see_looks 特定于模型 添加于 26.4 如果与至少一项允许用户交付 Looker 内容的其他权限结合使用,此权限可让用户交付发送所有数据行的 Look 或探索。此权限可让 Looker 调度程序中的 Look 和探索显示所有结果选项。
create_alerts see_looks 实例级 允许用户在信息中心图块上创建提醒,以便在达到或超过指定条件时收到通知。用户可以修改、复制和删除自己的提醒以及其他用户的公开提醒。如果用户的 Slack 工作区未连接到 Looker 实例,则该用户将无法创建向 Slack 发送通知的提醒。
download_with_limit see_looks 实例级 允许用户下载应用了限制的查询结果
download_without_limit see_looks 实例级 允许用户下载查询结果,且不应用任何限制
see_sql see_looks 特定于模型 允许用户查看查询的 SQL 以及运行查询时出现的任何 SQL 错误
clear_cache_refresh access_data 特定于模型 用户可以清除缓存并刷新嵌入式信息中心、旧版信息中心、信息中心功能块、Look 和 Explore。
see_drill_overlay access_data 特定于模型 让用户无需前往完整的“探索”页面即可进行深入分析。
manage_spaces 无 实例级 启用内容浏览器,以便用户可以创建、复制、移动和删除文件夹。用户还需要拥有相应文件夹的管理访问权限、编辑内容访问权限,或者,如果用户要创建新文件夹,则需要拥有父文件夹的相应权限。
embed_browse_spaces 无 实例级 启用内容浏览器,以便用户可以从嵌入式内容中浏览文件夹。获得 embed_browse_spaces 权限的任何嵌入用户都可以访问个人嵌入文件夹和组织的共享文件夹(如果有)。

建议拥有 save_content 权限的用户也拥有 embed_browse_spaces 权限,以便用户在选择内容保存位置时可以浏览文件夹。

如需查看文件夹中的内容,用户还需要拥有 see_looks、see_user_dashboards 和 see_lookml_dashboards 权限。

如果嵌入用户想要将信息中心或 Look 标记为收藏,则需要 embed_browse_spaces 权限,因为将内容标记为收藏需要访问收藏夹。
embed_save_shared_space 无 实例级 允许同时拥有 save_content 权限的用户从保存对话框中导航到组织的共享文件夹(如果有)。如果用户拥有 save_content 权限但没有 embed_save_shared_space 权限,则只能选择将内容保存到其个人嵌入文件夹。

embed_save_shared_space 权限不会替换内容访问权限。例如,如需让用户能够将文件保存到共享文件夹,他们仍需拥有对该文件夹的管理访问权限、编辑权限。此外,如果用户拥有 save_content 权限以及共享文件夹的管理访问权限、修改访问权限,即使没有 embed_save_shared_space 权限,只要他们有其他方式可导航到共享文件夹(例如通过嵌入式信息中心的从此处探索选项),仍可将内容保存到该文件夹中。
gemini_in_looker 无 特定于模型 此权限是 Gemini 默认角色中包含的唯一权限。

此权限可让用户执行与管理面板中的 Gemini in Looker 页面上启用的任何 Gemini in Looker 功能相关的任务。某些任务可能需要额外的权限。
chat_with_agent gemini_in_looker 特定于模型 添加于 25.18 对话式分析用户可以与基于最多五个 Looker 探索的数据的数据智能体或信息中心数据智能体对话。您需要获得其他权限才能与信息中心数据代理对话。
chat_with_explore chat_with_agent 特定于模型 添加了 25.18 对话式分析用户在拥有其他必需权限时,可以与 Looker 探索进行对话。
save_agents chat_with_explore 特定于模型 添加于 25.18 对话分析用户可以在信息中心或探索中创建、修改、删除和共享数据代理。如需修改、删除或共享其他用户创建的数据智能体,用户必须获得相应角色,该角色包含智能体所用每个模型的此权限,以及其他必需的权限和对智能体的管理访问权限、修改访问权限。
admin_agents gemini_in_looker 特定于模型 添加于 25.18 用户可以创建、修改、共享和删除数据代理,以便与 Conversational Analytics API 和嵌入式对话分析搭配使用。用户创建数据代理后,系统会自动授予其管理访问权限、修改数据代理访问权限。获得此权限后,用户无需获得数据智能体的内容访问权限,即可修改、删除或共享其他用户创建的数据智能体。

模型访问权限

确定用户应有权访问哪些 LookML 模型。这将是模型名称列表。

用户属性

确定用户应具备哪些用户属性(如果有)。您需要 Looker 中的用户属性名称,以及用户应具有的相应属性值。

群组

确定用户应属于哪些群组(如果有)。您需要的是群组 ID,而不是群组名称。将已签名的嵌入式用户添加到 Looker 群组后,您就可以管理该用户对 Looker 文件夹的访问权限。已签名的嵌入式用户将有权访问与其 Looker 群组的成员共享的任何文件夹。

您还可以使用 external_group_id 参数来创建常规 Looker 群组之外的群组。在这种情况下,具有相同 external_group_id 的已签名嵌入用户将有权访问外部群组独有的共享文件夹“Group”。

嵌入式角色

permissions 和 models 参数用于为嵌入用户创建角色。此角色在 Looker 的管理部分中的用户页面上显示为“嵌入式角色”。如果嵌入网址中同时指定了 permissions、models 和 group_ids 参数,则嵌入的角色会添加到 group_ids 参数中列出的群组已分配的任何角色中。这与标准角色相同,因为 Looker 中的所有角色都是累加的。

例如,假设您在 Looker 中有一个现有的群组,其群组 ID 为 1,并且该群组已拥有名为 model_one 的模型的 explore 权限,而您创建了一个嵌入网址,其中包含以下参数:

  • group_ids = ["1"]
  • permissions = ["access_data","see_looks"]
  • models = ["model_two"]

在这种情况下,嵌入用户将继承在 model_one 上查看和探索数据的能力,并且使用上述参数创建的嵌入角色还将授予在 model_two 上查看数据的能力。

创建嵌入网址

签名嵌入网址的格式如下:

https://HOST/login/embed/EMBED URL?PARAMETERS&signature=SIGNATURE

主机

主机是指 Looker 实例的托管位置。例如 analytics.mycompany.com。如果您尚未启用端口转发,请务必添加端口号,例如 analytics.mycompany.com:9999。

嵌入网址

嵌入网址之前已确定。其格式如下:

  • /embed/looks/4
  • /embed/explore/my_model/my_explore
  • /embed/query-visualization/Query.client_id
  • /embed/dashboards/1 或 /embed/dashboards-legacy/1
  • /embed/dashboards/my_model::my_dashboard 或 /embed/dashboards-legacy/my_model::my_dashboard

这意味着,最终到达网址中会显示 /embed//embed/ 这一模式;这是正确的。

如果您使用的是嵌入式 JavaScript 事件,请务必将 embed_domain 参数(使用 iframe 的网域)添加到嵌入网址的末尾,如下所示:

/embed/looks/4
⇨
/embed/looks/4?embed_domain=https://mywebsite.com

embed_domain 参数在网址编码之前添加到嵌入网址中。如果您的嵌入网址已包含内容查询参数(例如过滤条件值),请使用和号 (&) 附加 embed_domain 参数:

/embed/looks/4?filter_name=value
⇨
/embed/looks/4?filter_name=value&embed_domain=https://mywebsite.com

如果您使用的是 Embed SDK,请务必添加 embed_domain 参数,并在嵌入网址的末尾添加 sdk=2,如下所示:

/embed/looks/4
⇨
/embed/looks/4?embed_domain=https://mywebsite.com&sdk=2

借助 sdk=2 参数,Looker 可以识别 SDK 是否存在,并利用 SDK 提供的其他功能。由于此参数是签名网址的一部分,因此 SDK 无法自行添加。

参数

以下网址参数用于指定签名嵌入所需的必要信息:

参数 默认值 说明 数据类型 示例
nonce 必须提供值 您喜欢的任何随机字符串,但在一小时内不得重复,且长度必须少于 255 个字符。

这样可防止攻击者重新提交合法用户的网址,以收集他们不应获取的信息。
JSON 字符串 "22b1ee700ef3dc2f500fb7"
time 必须提供值 当前时间(以 UNIX 时间戳表示)。 整数 1407876784
session_length 必须提供值 用户应在 Looker 中保持登录状态的秒数,介于 0 到 2,592,000 秒(30 天)之间。 整数 86400
external_user_id 必须提供值 嵌入 Looker 的应用中每个用户的标识符。Looker 使用 external_user_id 来区分已登录的嵌入式用户,因此每位用户都必须拥有分配给自己的唯一 ID。

您可以为用户创建任意字符串作为 external_user_id,只要该字符串对相应用户而言是唯一的即可。每个 ID 都与一组权限、用户属性和模型相关联。单个浏览器一次只能支持一个 external_user_id(即用户会话)。在会话期间,无法更改用户的权限或用户属性。

出于安全考虑,请确保您没有在不同的嵌入会话中为不同的互动用户使用相同的 external_user_id,并且没有为具有不同权限、用户属性值或模型访问权限的单个用户使用相同的 external_user_id。

为多个用户或同一用户(具有多种权限、用户属性或模型集)使用同一 external_user_id 可能会导致原本无权访问数据的用户看到相应数据。
JSON 字符串 "user-4"
permissions 必须提供值 用户应拥有的权限列表。

如需查看允许的权限列表,请参阅本页面的权限部分。
字符串数组 [

  "access_data",

  "see_looks"

]
models 必须提供值 用户应有权访问的模型名称列表。 字符串数组 [

  "model_one",

  "model_two"

]
group_ids [] 用户应加入的 Looker 群组的列表(如果有)。使用群组 ID 而不是群组名称。 字符串数组 ["4", "3"]
external_group_id "" 用户在嵌入 Looker 的应用中所属群组的唯一标识符。

有权保存内容且共享外部群组 ID 的用户可以在名为“Group”的共享 Looker 文件夹中保存和修改内容。external_group_id 参数是创建嵌入用户的外部群组的唯一可用方法。无法在 Looker 界面中配置外部嵌入用户群组。

external_group_id 的长度不应超过 81 个字符。系统会为该群组创建一个对应的文件夹,文件夹名称最多可包含 100 个字符。文件夹名称以“嵌入共享群组”为前缀,因此 external_group_id 的长度限制为 81 个字符,以确保总长度不超过 100 个字符。
JSON 字符串 "Accounting"
user_attributes {} 用户应具备的用户属性的列表(如果有)。包含用户属性名称的列表,后跟用户属性值。

如果您的 LookML 模型已本地化,您可以在嵌入网址中使用 locale 用户属性来指定嵌入的语言。例如,添加 user_attributes { "locale" : "fr_FR" } 参数会导致嵌入内容加载法语作为其语言。
字符串的哈希 {

  "vendor_id" : "17",

  "company" : "xactness"

}
access_filters 必须提供值 在 Looker 3.10 中,此参数已被移除,但网址中仍必须包含此参数。将 access_filters 与空占位符搭配使用,例如 access_filters={}。 空白占位符 {}
first_name "" 用户的名字。如果留空,first_name 将保留上次请求中的值,或者如果从未设置过名字,则为“嵌入”。 JSON 字符串 "Alice"
last_name "" 用户的姓氏。如果留空,last_name 将保留上次请求中的值,或者如果从未设置过姓氏,则为“Embed”。 JSON 字符串 "Jones"
user_timezone "" 如果您已启用用户自选时区,则设置嵌入式 Look 或信息中心内时区下拉菜单中查看者时区选项的值。此参数不会直接更改显示内容的时区;用户需要从下拉菜单中选择时区。

如需查看有效值,请参阅已签名的嵌入时区参考文档页面。

聊天团队提示:如果您希望嵌入式内容默认采用观看者的时区,请使用以下方法之一:

  • 向 嵌入网址添加参数 ?query_timezone=user_timezone。例如:

    /embed/dashboards/1?query_timezone=user_timezone
  • 保存嵌入式信息中心或 Look,并将默认时区设置为查看者时区,这样一来,嵌入式用户和非嵌入式用户都会默认使用用户的时区。
  • JSON 字符串或 null "US/Pacific"

    - 或 -

    null
    force_logout_login 必须提供值 如果普通 Looker 用户已登录 Looker,并且查看已签名的嵌入式项,您可以选择是否:

    1) 他们应使用当前凭据查看相应商品

    或

    2) 用户应退出账号,然后使用已签名的嵌入凭据重新登录。
    布尔值(true 或 false) true
    ca_chat true 如果您已启用对话式分析功能和启用信息中心代理功能,则此属性用于设置信息中心代理对话窗格是否对嵌入用户可见。如果值为 true,则拥有与信息中心代理互动的相应权限的用户可以看见 Gemini Spark。仅适用于嵌入式信息中心。 布尔值(true 或 false) true

    签名

    Looker 会使用签名来验证嵌入网址中是否使用了正确的嵌入密钥来生成签名,以及嵌入网址中的参数是否未发生变化。如果嵌入密钥或网址参数不同或已更改,签名将不匹配,并且身份验证将被拒绝。

    因此,嵌入网址中的签名可提供加密强度高的证明,表明嵌入网址在传输过程中未被修改,并且是由拥有嵌入密钥的可信方创建的。

    如需生成签名,您需要按以下步骤操作。

    1. 按以下顺序收集参数值:
      • 主机,后跟 login/embed/(例如,analytics.mycompany.com/login/embed/)
      • 嵌入网址
      • Nonce
      • 当前时间
      • 会话时长
      • 外部用户 ID
      • 权限
      • 模型
      • 群组 ID
      • 外部群组 ID
      • 用户属性
      • 访问过滤条件(需要一个空占位符)
      • 对话式分析信息中心数据智能体可见性
    2. 将除“主机”和“嵌入网址”以外的所有值格式设置为 JSON
    3. 串联值并换行 (\n)
    4. 使用 Looker 嵌入密钥对串联的字符串进行 HMAC-SHA1 签名

    编码

    最后一步是对网址进行网址编码。

    在对网址进行编码之前,使用所有可能参数的格式正确的嵌入网址可能如下所示:

    https://analytics.mycompany.com/login/embed//embed/dashboards/1?
    nonce="22b1ee700ef3dc2f500fb7"&
    time=1407876784&
    session_length=86400&
    external_user_id="user-4"&
    permissions=["access_data","see_user_dashboards","see_looks"]&
    models=["model_one","model_two"]&
    group_ids=[4,3]&
    external_group_id="Allegra K"&
    user_attributes={"vendor_id":"17","company":"xactness"}&
    access_filters={}&
    ca_chat=false&
    first_name="Alice"&
    last_name="Jones"&
    user_timezone="US/Pacific"&
    force_logout_login=true&
    signature=123456789ABCDEFGHIJKL
    

    如前所述,网址中显示 /embed//embed/ 是正常的。

    编码后,网址应如下所示:

    https://analytics.mycompany.com/login/embed/%2embed%2Fdashboards%2F1?
    nonce=%2222b1ee700ef3dc2f500fb7&%22&
    time=1407876784&
    session_length=86400&
    external_user_id=%22user-4%22&
    permissions=%5B%22access_data%22%2C%22see_user_dashboards%22%2C%22see_looks%22%5D&
    models=%5B%22model_one%22%2C%22model_two%22%5D&
    group_ids=%5B4%2C3%5D&
    external_group_id=%22Allegra%20K%22&
    user_attributes=%7B%22vendor_id%22%3A%2217%22%2C%22company%22%3A%22xactness%22%7D&
    access_filters%7B%7D%26%0A
    ca_chat=false&
    first_name=%22Alice%22&
    last_name=%22Jones%22&
    user_timezone=%22US%2FPacific%22&
    force_logout_login=true&
    signature=123456789ABCDEFGHIJKL
    

    使用“创建已签名的嵌入网址”API 端点

    Looker API 包含 Create Signed Embed Url 端点,该端点接受一组签名嵌入参数(包括要嵌入的内容的网址),并返回一个完整的、经过编码的、签名网址。

    如需从 Web 服务器使用此 API 端点,Web 服务器必须能够以管理员权限通过身份验证来访问 Looker API。Web 服务器网域还必须列在嵌入网域许可名单中。

    您还可以使用 API Explorer 生成使用此端点的签名网址。您可以从 Looker Marketplace 在 Looker 实例上安装 API Explorer。生成签名网址后,必须准确复制该网址,并且只能使用一次,否则会失败。API Explorer 还可用于生成签名网址,并将其与手动创建的签名网址进行比较,以便进行问题排查。

    如需详细了解 Looker API,请参阅开始使用 Looker API 文档页面。

    测试嵌入网址

    如需测试最终到达网址,请将其粘贴到 Looker 的管理部分中嵌入页面的嵌入 URI 验证器中。虽然此选项无法告知您设想的数据和权限是否已正确设置,但可以验证您的身份验证是否正常运行。