使用 RLS 嵌入报表

  • 项目

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

本文介绍如何将使用 RLS 的 Power BI 内容嵌入标准 Power BI 应用拥有数据应用程序。

先决条件

有关如何设置 RLS 的详细说明，请参阅 Power BI 的行级别安全性 (RLS)。

当你定义 RLS 角色时，请记住所使用的 DAX 表达式将确定 RLS 模型是静态的还是动态的。

何时使用静态和动态安全性

静态安全性在 DAX 筛选器中使用固定值来定义每个角色。 在涉及许多用户或组织时，实施起来很简单，但很难维护。

静态安全性最适合为每个部门需要访问不同数据的一个或多个大客户提供服务的 ISV。

动态安全性使用 DAX 函数（username() 或 userprincipalname()）来定义角色。 动态安全性提供了更大的灵活性，你可以使用更少的角色和更少的维护来管理数据。

静态安全性

使用静态角色时，会在生成嵌入令牌时将角色传递给 Power BI，用户根据该角色看到数据。 要创建静态安全性角色，请在 DAX 筛选器中输入一个固定值。

例如，可以将“美国东部”的角色定义为 [Region] = "East"

显示如何定义静态 RLS 角色的屏幕截图。

假设 john@contoso.com 是你的应用的一个用户。 你想要让 John 从“美国东部”角色访问数据。 为了为 john@contoso.com 嵌入报表，可以使用“美国东部”角色生成嵌入令牌。 会针对 [Region] = "East" 筛选生成的数据。

注意

在生成嵌入令牌时，需要提供用户名，但用户名可以是任何字符串。 静态角色有一个固定的值，不依赖于用户名，因此，一旦 ISV 确定了用户的角色并将其传递给嵌入令牌，无论传递的是什么用户名，数据都会根据该角色进行筛选。

动态安全性

动态安全性使用 DAX 函数（username() 或 userprincipalname()）来定义角色。

在“用户拥有数据”场景下，RLS 模型根据特定用户的角色自动筛选数据。 使用应用拥有数据时，Power BI 不知道 ISV 客户的用户名，因此你可以使用 username() 函数动态地筛选数据。

使用 username() 函数在 Power BI Desktop 中创建角色。 例如，可以创建名为“CountryDynamic”的角色，并将其定义为 [CountryRegionCode] = username()

显示如何创建动态 RLS 角色的屏幕截图。

假设你想要为用户 jane@contoso.com 提供对 France 数据的访问权限。 当你为 jane@contoso.com 生成嵌入令牌时，将字符串“France”作为“CountryDynamic”角色中的用户名来传递。 你的数据会根据 [CountryRegionCode] = France 进行筛选。

{
    "accessLevel": "View",
    "identities": [
        {
            "username": "France",
            "roles": [ "CountryDynamic"],
            "datasets": [ "fe0a1aeb-f6a4-4b27-a2d3-b5df3bb28bdc" ]
        }
    ]
}

在此场景中使用动态安全性时，只需对所有区域使用一个角色。 区域名称被用作有效的标识。

生成嵌入令牌

当你准备好将报表嵌入应用时，需要生成嵌入令牌。 要使用嵌入令牌 API 生成令牌，请将以下信息传递给 API。

  • 用户名（必填）- 如果角色是动态的，则将用户名字符串用作筛选器。 对于静态角色，用户名不会影响 RLS，可以是任何字符串。 只能列出一个用户名。
  • 角色（必填）- 在应用行级别安全性规则时使用的角色。 如果传递多个角色，则这些角色应该作为字符串数组传递。
  • 数据集（必填）- 适用于要嵌入的项的数据集。

现在可以将报表嵌入到应用中了。 报表会根据所应用的 RLS 筛选数据。

public EmbedToken GetEmbedToken(Guid reportId, IList<Guid> datasetIds, [Optional] Guid targetWorkspaceId)
    {
        PowerBIClient pbiClient = this.GetPowerBIClient();

       // Defines the user identity and roles.
        var rlsIdentity = new EffectiveIdentity(
            username: "France",
            roles: new List<string>{ "CountryDynamic" },
            datasets: datasetIds.Select(id => id.ToString()).ToList());
        );
       
        // Create a request for getting an embed token for the rls identity defined above
        var tokenRequest = new GenerateTokenRequestV2(
            reports: new List<GenerateTokenRequestV2Report>() { new GenerateTokenRequestV2Report(reportId) },
            datasets: datasetIds.Select(datasetId => new GenerateTokenRequestV2Dataset(datasetId.ToString())).ToList(),
            targetWorkspaces: targetWorkspaceId != Guid.Empty ? new List<GenerateTokenRequestV2TargetWorkspace>() { new GenerateTokenRequestV2TargetWorkspace(targetWorkspaceId) } : null,
            identities: new List<EffectiveIdentity> { rlsIdentity }
        );

        // Generate an embed token
        var embedToken = pbiClient.EmbedToken.GenerateToken(tokenRequest);

        return embedToken;
    }

注意事项和限制

  • 根据具体设置，可能需要执行几个步骤才能生成嵌入令牌。 有关不同方案的信息，请参阅嵌入使用安全功能的报表。
  • 生成嵌入令牌的用户必须是两个工作区（数据集工作区和报表工作区）中的成员或管理员。
  • 生成嵌入令牌时，需要提供用户名和角色。 如果不提供，则会发生以下事件之一，具体取决于令牌是由服务主体生成还是由主用户生成的：
    • 对于服务主体，令牌生成会失败。
    • 对于主用户，令牌生成会成功，但不会对数据进行筛选（将返回所有数据）。

相关内容

有更多疑问？ 尝试参与 Power BI 社区。