使用 RLS 內嵌報表

適用於： 應用程式擁有數據 用戶擁有數據

本文說明如何將使用 RLS 的 Power BI 內容內嵌至標準 Power BI 應用程式擁有數據應用程式。

必要條件

如需如何設定 RLS 的詳細說明，請參閱 Power BI 的數據列層級安全性 （RLS）。

當您 定義 RLS 角色時，請記住您使用的 DAX 運算式會判斷 RLS 模型是否為靜態或動態。

使用靜態和動態安全性的時機

靜態安全性 會使用 DAX 篩選器中的固定值來定義每個角色。 在涉及許多使用者或組織時，實作簡單但難以維護。

靜態安全性最適合為一或幾個大型客戶提供服務的ISV，而每個部門都需要存取不同的數據。

動態安全性 會使用 DAX 函式 （username() 或 userprincipalname()） 來定義角色。 動態安全性提供更大的彈性，可讓您使用較少的角色和較少的維護來管理您的數據。

靜態安全性

使用靜態角色時，您會在產生內嵌令牌時將角色傳遞至Power BI，而用戶會根據該角色看到數據。 若要建立靜態安全性角色，請在 DAX 篩選器中輸入固定值。

例如，您可以將美國東部的角色定義為[Region] = "East"

假設 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()

假設您想要為使用者jane@contoso.com提供法國數據的存取權。 當您產生的jane@contoso.com內嵌令牌時，您會將 String France 當做 CountryDynamic 角色中的使用者名稱傳遞。 您的數據會根據 [CountryRegionCode] = France 進行篩選。

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

在此案例中使用動態安全性時，您只需要所有區域的一個角色。 區域名稱會當做有效的身分識別使用。

產生內嵌令牌

當您準備好將報表內嵌至應用程式時，您需要 產生內嵌令牌。 若要使用內嵌令牌 API 產生令牌，請將下列資訊傳遞至 API。

• username （必要） – 如果角色是動態的，則會 使用使用者名稱 字串作為篩選條件。 針對靜態角色，用戶 名稱 不會影響 RLS，而且完全可以是任何字串。 只能列出單一用戶名稱。
• roles （必要） - 套用數據列層級安全性規則時所使用的角色。。 如果傳遞多個角色，則應以字串數位的形式傳遞這些角色。
• dataset （必要） - 適用於您要內嵌之項目的數據集。

您現在可以將報表內嵌至您的應用程式。 報表會根據套用的 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;
    }

考量與限制

• 視您的設定而定，您可能需要採取數個步驟，才能產生內嵌令牌。 如需不同案例的相關信息，請參閱 內嵌使用安全性功能的報表。
• 產生內嵌令牌的用戶必須是兩個 工作區中的成員 或 系統管理員 （數據集工作區和報表工作區）。
• 產生內嵌令牌時，您必須提供使用者名稱和角色。 如果沒有，則會發生下列其中一個事件，視令牌是由服務主體或主要用戶產生而定：
  • 對於服務主體，令牌產生會失敗。
  • 對於主要使用者，令牌產生會成功，但不會篩選數據（會傳回所有數據）。

相關內容

• RLS 指引
• 產生內嵌令牌

其他問題嗎？ 請嘗試 Power BI 社群。