通过

生成嵌入令牌

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

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

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

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

注释

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

保护数据

建议使用包含配置文件的工作区隔离，但如果想要使用 RLS 方法，请参阅本文结尾处的 RLS 部分。

令牌权限和安全性

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

访问级别

  • 若要授予用户查看或编辑权限，请使用 allowEdit 参数。

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

行级别安全性

使用行级安全性（RLS）时，您所使用的身份可以与用于生成令牌的服务主体或主用户的身份不同。 通过使用不同的标识，可以根据目标用户显示嵌入的信息。 例如，在应用程序中，可以要求用户登录，然后显示仅包含销售信息的报表（如果登录的用户是销售员工）。

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

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

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

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

    注释

    服务主体必须始终提供：

    • 具有 RLS 语义模型的任何项的标识
    • 定义了上下文标识（SSO）后有效的 RLS 标识（适用于 SSO 语义模型）

    Power BI 语义模型的 DirectQuery

    嵌入一个 Power BI 报表，此报表包含一个与另一个 Power BI 语义模型直接查询连接的语义模型：

    • 在 Power BI 门户中，将“XMLA 终结点”设置为“只读”或“读写”，如为 Premium 容量启用读写中所述。 每个容量只需执行此操作一次。

    • 创建 多资源嵌入令牌

      • 指定请求中的所有数据集 ID。
      • 在XmlaPermissions请求中将每个语义模型设置为只读。
      • 对于每个已启用单一登录（SSO）的数据源，请在DatasourceIdentity处提供数据源的身份标识块。

    在此方案中，所有语义模型都必须驻留在高级工作区上。 试用嵌入令牌不能用于嵌入此类型的报表。

    在令牌过期之前更新令牌

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

    仪表板和磁贴

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

    对于以下 API：

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

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

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

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

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

    注意事项和限制

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

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

    • 使用 Data Lake Storage（DLS）进行嵌入项时，需要使用生成令牌 API的 V2版本。

    • 无法为 “我的”工作区创建嵌入令牌。

    相关内容

    • Last updated on