生成嵌入令牌

  • 项目

适用范围：️ 应用拥有数据 用户拥有数据

生成令牌是一种 REST API，可生成用于在 Web 应用或门户中嵌入 Power BI 报表或语义模型的令牌。 它可以为单个项或多个报表或语义模型生成令牌。 该令牌用于授权对 Power BI 服务的请求。

生成令牌 API 使用单个标识（主用户或服务主体）为单个用户生成令牌，具体取决于该用户在应用中的凭据（有效标识）。

身份验证成功后，系统将授予对相关数据的访问权限。

注意

生成令牌是较新的版本 2 API，适用于报表和语义模型以及单个或多个项。 它优先于旧版本 1 API。 对于仪表板和磁贴，请使用 V1 仪表板 GenerateTokenInGroup 和 磁贴 GenerateTokenInGroup。

保护数据

若要处理多个客户的数据，请考虑以下两种保护数据的重要方法：基于工作区的隔离和基于行级别安全性的隔离。 可以在服务主体配置文件和行级别安全性中找到二者之间的详细对比。

建议将基于工作区的隔离与配置文件结合使用，但如果想使用 RLS 方法，请查看本文末尾的 RLS 部分。

令牌权限与安全

在生成令牌 API 中，GenerateTokenRequest 部分描述令牌权限。

访问级别

  • 使用 allowEdit 参数向用户授予查看或编辑权限。

  • 将工作区 ID 添加到嵌入令牌，以允许用户在该工作区中创建新报表（SaveAs 或 CreateNew）。

行级安全性

利用行级别安全性 (RLS)，你使用的标识可以与用来生成令牌的服务主体或主用户的标识不同。 使用不同的标识，可以根据目标用户显示嵌入的信息。 例如，在你的应用程序中，你可以要求用户登录，如果登录用户为销售人员，则显示只包含销售信息的报表。

如果你使用的是 RLS，有时可以不指定用户标识（EffectiveIdentity 参数）。 如果不使用 EffectiveIdentity 参数，令牌可以访问整个数据库。 此方法可用于向具有查看整个语义模型权限的管理员和经理等用户授予访问权限。 但是，不能在每个场景中都使用此方法。 下表列出了不同的 RLS 类型，并介绍了在不指定用户标识的情况下可以使用哪种身份验证方法。

该表还介绍了适用于每个 RLS 类型的注意事项和限制。

RLS 类型 能否在不指定有效用户 ID 的情况下生成嵌入令牌？ 注意事项和限制
云行级别安全性 (Cloud RLS) ✔ 主用户
✖ 服务主体
RDL（分页报表） ✖ 主用户
✔ 服务主体		 不能使用主用户为 RDL 生成嵌入令牌。
Analysis Services (AS) 本地实时连接 ✔ 主用户
✖ 服务主体		 生成嵌入令牌的用户还需具备以下权限之一：
  • 网关管理员权限
  • Datasource 模拟权限 (ReadOverrideEffectiveIdentity)
    		•
    Analysis Services (AS) Azure 实时连接 ✔ 主用户
    ✖ 服务主体    		 无法重写用于生成嵌入令牌的用户标识。 自定义数据可用于实现动态 RLS 或安全筛选。

    注意： 服务主体必须提供其对象 ID 作为有效标识（RLS 用户名）。
    单一登录 (SSO) ✔ 主用户
    ✖ 服务主体    		 可以使用有效标识对象中的标识 blob 属性提供显式 (SSO) 标识
    SSO 和云 RLS ✔ 主用户
    ✖ 服务主体    		 必须提供以下内容：
  • 有效标识对象的标识 blob 属性中的显式 (SSO) 标识
  • 有效 (RLS) 标识（用户名）
    		•

    注意

    服务主体必须始终提供以下信息：

    • 具有 RLS 语义模型的任何项的标识。
    • 对于 SSO 语义模型，定义了上下文 (SSO) 标识的有效 RLS 标识。

    Power BI 语义模型的 DirectQuery

    对于拥有将直接查询连接到另一个 Power BI 语义模型的语义模型的 Power BI 报表，要嵌入该报表，请执行以下操作：

    • 在 Power BI 门户中，将“XMLA 终结点”设置为“只读”或“读写”，如为 Premium 容量启用读写中所述。 针对每个容量只需执行一次。
    • 生成多资源嵌入令牌
      • 在请求中指定所有数据集 ID。
      • 对于请求中的每个语义模型，将XmlaPermissions设置为只读。
      • 对于已启用每个单一登录 (SSO) 的数据源，请为 DatasourceIdentity 中的数据源提供标识 Blob。

    在令牌过期之前续订令牌

    令牌具有时间限制。 这意味着，嵌入 Power BI 项后，与之交互的时间是有限的。 若要为用户提供持续体验，请在令牌过期之前续订（或刷新）令牌。

    仪表板和磁贴

    生成令牌适用于报表和语义模型。 若要为仪表板或磁贴生成嵌入令牌，请使用版本 1 仪表板 GenerateTokenInGroup 或 磁贴 GenerateTokenInGroup API。 这些 API 一次只为一个项生成令牌。 你不能为多个项生成一个令牌。

    对于这些 API：

    • 使用 accessLevel 参数确定用户的访问级别。

      • 查看 - 授予用户查看权限。

      • 编辑 - 授予用户查看和编辑权限（仅当为报表生成嵌入令牌时适用）。

      • 创建 - 授予用户创建新报表的权限（仅当为创建报表生成嵌入令牌时适用）。 对于报表创建，还必须提供 datasetId 参数。

    • 使用 allowSaveAs 布尔值可让用户将报表另存为新报表。 默认情况下，此设置会设置为 false，并且仅在为报表生成嵌入令牌时适用。

    注意事项和限制

    • 出于安全原因，嵌入令牌的生存期将设置为用于调用 GenerateToken API 的 Microsoft Entra 令牌的剩余生存期。 因此，如果你使用同一 Microsoft Entra 令牌生成几个嵌入令牌，则每次调用生成的嵌入令牌的生存期都会变短。

    • 如果要嵌入的语义模型和项位于两个不同的工作区，则服务主体或主用户必须至少是两个工作区的成员。

    • 不能为我的工作区创建嵌入令牌。

    相关内容