搭配 Power BI 內嵌內容使用資料列層級安全性Use row-level security with Power BI embedded content

資料列層級安全性 (RLS) 可用來限制使用者存取儀表板、圖格、報告和資料集內的資料。Row level security (RLS) can be used to restrict user access to data within dashboards, tiles, reports, and datasets. 多位不同的使用者可在看見不同的資料時使用這些相同的成品。Multiple, different users can work with those same artifacts all while seeing different data. 內嵌支援 RLS。Embedding supports RLS.

如果您要為非 Power BI 使用者內嵌 (應用程式擁有資料),這通常是 ISV 案例,則本文很適合您!If you're embedding for non-Power BI users (app owns data), which is typically an ISV scenario, then this article is for you! 您必須設定代表使用者和角色的內嵌權杖。You will need to configure the embed token to account for the user and role. 請繼續閱讀以了解如何執行這項操作。Read on to learn how to do this.

如果您要內嵌至組織內的 Power BI 使用者 (使用者擁有資料),RLS 的運作方式會像是直接在 Power BI 服務中運作一樣。If you are embedding to Power BI users (user owns data), within your organization, RLS works the same as it does within the Power BI service directly. 您不需要在應用程式中執行其他動作。There is nothing more you need to do in your application. 如需詳細資訊,請參閱 Power BI 的資料列層級安全性 (RLS)For more information see, Row-Level security (RLS) with Power BI.


若要利用 RLS,請務必了解三個主要概念:使用者、角色和規則。To take advantage of RLS, it’s important you understand three main concepts; Users, Roles, and Rules. 讓我們分別探討:Let’s take a closer look at each:

使用者– 檢視成品 (儀表板、圖格、報告或資料集) 的終端使用者。Users – End-users viewing the artifact (dashboard, tile, report, or dataset). 在 Power BI Embedded 中,使用者是由內嵌權杖中的使用者名稱屬性所識別。In Power BI Embedded, users are identified by the username property in an embed token.

角色 – 使用者會有隸屬的角色。Roles – Users belong to roles. 角色是規則的容器,可以命名為「銷售經理」或「銷售代表」等。您會在 Power BI Desktop 中建立角色。A role is a container for rules and can be named something like Sales Manager or Sales Rep. You create roles within Power BI Desktop. 如需詳細資訊,請參閱 Power BI Desktop 的資料列層級安全性 (RLS)For more information, see Row-level security (RLS) with Power BI Desktop.

規則 – 角色擁有規則,而這些規則是將套用至資料的實際篩選。Rules – Roles have rules, and those rules are the actual filters that are going to be applied to the data. 可能是簡單的「國家/地區 = 美國」,也可能更動態。This could be as simple as “Country = USA” or something much more dynamic. 在本文的其餘部分,我們將提供撰寫 RLS 後再於內嵌應用程式中取用的範例。For the rest of this article, we’ll provide an example of authoring RLS, and then consuming that within an embedded application. 我們的範例使用零售分析範例 PBIX 檔案。Our example uses the Retail Analysis Sample PBIX file.


使用 Power BI Desktop 新增角色Adding roles with Power BI Desktop

我們的零售分析範例顯示所有零售連鎖商店的銷售額。Our Retail Analysis sample shows sales for all the stores in a retail chain. 若沒有 RLS,不論是哪位區域經理登入及檢視報表,都會看到相同的資料。Without RLS, no matter which district manager signs in and views the report, they’ll see the same data. 高階管理階層決定每位區域經理只能看到其所管理的商店銷售額;若要這樣做,我們可以使用 RLS。Senior management has determined each district manager should only see the sales for the stores they manage, and to do this, we can use RLS.

RLS 是在 Power BI Desktop 中撰寫。RLS is authored in Power BI Desktop. 我們可以在資料集和報表處於開啟狀態時,切換至圖表檢視來查看下列結構描述:When the dataset and report are opened, we can switch to diagram view to see the schema:

Power BI Desktop 中的圖表檢視

以下是此結構描述需要注意的一些事項:Here are a few things to notice with this schema:

  • 所有量值 (例如 [總銷售額]) 會儲存在 [銷售] 事實資料表中。All measures, like Total Sales, are stored in the Sales fact table.
  • 有四個額外的相關維度資料表:[項目]、[時間]、[商店] 和 [區域]。There are four additional related dimension tables: Item, Time, Store, and District.
  • 關聯線上的箭頭表示篩選可以從一個資料表流向另一個資料表的方向。The arrows on the relationship lines indicate which way filters can flow from one table to another. 例如,如果在 [時間[日期]] 上套用篩選,在目前的結構描述中,它只會進一步篩選 [銷售] 資料表中的值。For example, if a filter is placed on Time[Date], in the current schema it would only filter down values in the Sales table. 由於關聯線上的所有箭頭都指向而不是背離 [銷售] 資料表,因此其他資料表不會受此篩選的影響。No other tables would be affected by this filter since all the arrows on the relationship lines point to the sales table and not away.
  • [區域] 資料指出每個區域的經理:The District table indicates who the manager is for each district:

    [區域] 資料表中的資料列

根據此結構描述,如果我們將篩選套用至 [區域] 資料表中的 [區域經理] 資料行,而且該篩選符合檢視報表的使用者,則該篩選也會進一步篩選 [商店] 和 [銷售] 資料表,僅顯示該區域經理的資料。Based on this schema, if we apply a filter to the District Manager column in the District table, and if that filter matches the user viewing the report, that filter will also filter down the Store and Sales tables to only show data for that district manager.

其做法如下:Here's how:

  1. 在 [模型] 索引標籤上,選取 [管理角色]。On the Modeling tab, select Manage Roles.

    Power BI Desktop 中的 [模型] 索引標籤

  2. 建立稱為經理的新角色。Create a new role called Manager.


  3. 在 [區域] 資料表中,輸入下列 DAX 運算式:[區域經理] = USERNAME()In the District table, enter the following DAX expression: [District Manager] = USERNAME().

    RLS 規則的 DAX 陳述式

  4. 若要確認規則正常運作,請在 [模型] 索引標籤上,選取[以角色身分檢視],然後選取您剛建立的 [經理] 角色,以及 [其他使用者]。To make sure the rules are working, on the Modeling tab, select View as Roles, and then select both the Manager role you just created, along with Other user. 輸入 Andrew Ma 作為使用者。Enter Andrew Ma for the user.

    [以角色身分檢視] 對話方塊

    報表現在會顯示您以 Andrew Ma 登入的資料。The reports will now show data as if you were signed in as Andrew Ma.

套用篩選,我們在此套用的篩選會進一步篩選 [區域]、[商店] 和 [銷售] 資料表中的所有記錄。Applying the filter, the way we did here, will filter down all records in the District, Store, and Sales tables. 不過,由於 [銷售] 和 [時間]、[銷售] 和 [項目] 以及 [項目] 和 [時間] 資料表之間關聯性的篩選方向,因此不會進一步篩選。However, because of the filter direction on the relationships between Sales and Time, Sales and Item, and Item and Time tables will not be filtered down. 若要深入了解雙向交叉篩選,請下載 Bidirectional cross-filtering in SQL Server Analysis Services 2016 and Power BI Desktop (SQL Server Analysis Services 2016 和 Power BI Desktop 中的雙向交叉篩選) 技術白皮書。To learn more about bidirectional cross-filtering, download the Bidirectional cross-filtering in SQL Server Analysis Services 2016 and Power BI Desktop whitepaper.

將使用者和角色套用至內嵌權杖Applying user and role to an embed token

現在您已設定 Power BI Desktop 角色,您的應用程式需要一些調整才能利用這些角色。Now that you have your Power BI Desktop roles configured, there is some work needed in your application to take advantage of the roles.

使用者會由您的應用程式驗證和授權,而內嵌權杖可用來授權該使用者存取特定 Power BI Embedded 報表。Users are authenticated and authorized by your application and embed tokens are used to grant that user access to a specific Power BI Embedded report. Power BI Embedded 沒有關於您使用者身分識別的任何特定資訊。Power BI Embedded doesn’t have any specific information on who your user is. 您必須傳遞一些額外的內容作為身分識別形式內嵌權杖的一部分,RLS 才能運作。For RLS to work, you’ll need to pass some additional context as part of your embed token in the form of identities. 這可以藉由 GenerateToken API 來完成。This is done by way GenerateToken API.

GenerateToken API 接受表示相關資料集的身分識別清單。The GenerateToken API accepts a list of identities with indication of the relevant datasets. 您必須傳遞下列項目作為身分識別的一部分,RLS 才能運作。For RLS to work, you will need to pass the following as part of the identity.

  • 使用者名稱 (必要項)– 這是套用 RLS 規則時可用來協助識別使用者的字串。username (mandatory) – This is a string that can be used to help identify the user when applying RLS rules. 只能列出單一使用者。Only a single user can be listed.
  • 角色 (必要項) – 含有套用資料列層級安全性規則時要選取之角色的字串。roles (mandatory) – A string containing the roles to select when applying Row Level Security rules. 如果傳遞多個角色,則應該以字串陣列形式來傳遞。If passing more than one role, they should be passed as a string array.
  • 資料集 (必要項) – 適用於您要內嵌之成品的資料集。dataset (mandatory) – The dataset that is applicable for the artifact you are embedding.

您可以在 PowerBIClient.Reports 上使用 GenerateTokenInGroup 方法來建立內嵌權杖。You can create the embed token by using the GenerateTokenInGroup method on PowerBIClient.Reports.

例如,您可以變更 PowerBIEmbedded_AppOwnsData 範例。For example, you could change the PowerBIEmbedded_AppOwnsData sample. Home\HomeController.cs line 76 and 77 無法從:Home\HomeController.cs line 76 and 77 could be updated from:

// Generate Embed Token.
var generateTokenRequestParameters = new GenerateTokenRequest(accessLevel: "view");

var tokenResponse = await client.Reports.GenerateTokenInGroupAsync(GroupId, report.Id, generateTokenRequestParameters);


var generateTokenRequestParameters = new GenerateTokenRequest("View", null, identities: new List<EffectiveIdentity> { new EffectiveIdentity(username: "username", roles: new List<string> { "roleA", "roleB" }, datasets: new List<string> { "datasetId" }) });

var tokenResponse = await client.Reports.GenerateTokenInGroupAsync("groupId", "reportId", generateTokenRequestParameters);

如果您呼叫 REST API,更新的 API 現在會接受名為身分識別的其他 JSON 陣列,其中包含使用者名稱、字串角色清單和字串資料集清單,例如:If you are calling the REST API, the updated API now accepts an additional JSON array, named identities, containing a user name, list of string roles and list of string datasets, e.g.:

    "accessLevel": "View",
    "identities": [
            "username": "EffectiveIdentity",
            "roles": [ "Role1", "Role2" ],
            "datasets": [ "fe0a1aeb-f6a4-4b27-a2d3-b5df3bb28bdc" ]

現在,結合所有項目,當有人登入您的應用程式檢視此成品時,他們只能看到依照資料列層級安全性的定義所允許檢視的資料。Now, with all the pieces together, when someone logs into your application to view this artifact, they’ll only be able to see the data that they are allowed to see, as defined by our row-level security.

使用 Analysis Services 即時連線Working with Analysis Services live connections

內部部署伺服器可以搭配 Analysis Services 即時連線使用資料列層級安全性。Row-level security can be used with Analysis Services live connections for on-premises servers. 使用這種類型的連線時,您應該了解幾個特定概念。There are a few specific concepts that you should understand when using this type of connection.

針對使用者名稱屬性提供的有效身分識別,必須為具備 Analysis Services 伺服器權限的 Windows 使用者。The effective identity that is provided for the username property must be a Windows user with permissions on the Analysis Services server.

內部部署資料閘道設定On-premises data gateway configuration

使用 Analysis Services 即時連線時,會用到內部部署資料閘道An On-premises data gateway is used when working with Analysis Services live connections. 使用所列的身分識別產生內嵌權杖時,主帳戶必須列為閘道的系統管理員。When generating an embed token, with an identity listed, the master account needs to be listed as an admin of the gateway. 如果未列出主帳戶,就不會將資料列層級安全性套用至資料屬性。If the master account is not listed, the row-level security will not be applied property to the data. 非閘道的系統管理員可以提供角色,但必須指定自己的使用者名稱以作為有效的身分識別。A non-admin of the gateway can provide roles, but must specify its own username for the effective identity.

使用角色Use of roles

您可以使用內嵌權杖中的身分識別來提供角色。Roles can be provded with the identity in an embed token. 如果未提供任何角色,則會使用所提供的使用者名稱來解析相關聯的角色。If no role is provided, the username that was provided will be used to resolve the associated roles.

使用 CustomData 功能Using the CustomData feature

CustomData 功能可讓您使用 CustomData 連接字串屬性傳遞任意文字 (字串),這是 AS 所要使用的值 (透過 CUSTOMDATA() 函數)。The CustomData feature allows passing free text (string) using the CustomData connection string property, a value to be used by AS (via the CUSTOMDATA() function). 您可以使用這項功能作為自訂資料取用的替代方式。You can use this as an alternative way to customize data consumption. 您可以在角色 DAX 查詢中使用,也可以在量值 DAX 查詢中不搭配任何角色使用。You can use it inside the role DAX query, and you can use it without any role in a measure DAX query. CustomData 功能是下列成品之權杖產生功能的一部分:儀表板、報表和磚。CustomData feature is part of our token generation functionality for the following artifacts: dashboard, report, and tile. 儀表板可以有多個 CustomData 身分識別 (每個磚/模型一個)。Dashboards can have multiple CustomData identities (one per tile/model).


CustomData 功能僅適用於位於 Azure Analysis Services 中的模型,而且僅適用於即時模式。The CustomData feature will only work for models that reside in Azure Analysis Services, and it only works in live mode. 不同於使用者和角色,您無法在 .pbix 檔案中設定自訂資料功能。Unlike users and roles, the custom data feature can't be set inside a .pbix file. 使用自訂資料功能產生權杖時,您必須具有使用者名稱。When generating a token with the custom data feature you must a have user name.

CustomData SDK 新增項目CustomData SDK Additions

權杖產生案例中的有效身分識別中已新增 CustomData 字串屬性。CustomData string property was added to our effective identity in the token generation scenario.

    [JsonProperty(PropertyName = "customData")]
    public string CustomData { get; set; }

您可以使用下列呼叫,透過自訂資料來建立身分識別:The identity can be created with custom data using the following call:

    public EffectiveIdentity(string username, IList<string> datasets, IList<string> roles = null, string customData = null);

CustomData SDK 用法CustomData SDK Usage

如果您呼叫 REST API,您可以在每個身分識別中新增自訂資料,例如:If you are calling the REST API, you can add custom data inside each identity, e.g.:

    "accessLevel": "View",
    "identities": [
            "username": "EffectiveIdentity",
            "roles": [ "Role1", "Role2" ],
            "customData": "MyCustomData",
            "datasets": [ "fe0a1aeb-f6a4-4b27-a2d3-b5df3bb28bdc" ]

考量與限制Considerations and limitations

  • 使用內嵌權杖時,在 Power BI 服務中將使用者指派給角色不會影響 RLS。Assignment of users to roles within the Power BI service does not affect RLS when using an embed token.
  • 雖然 Power BI 服務不會將 RLS 設定套用至系統管理員或具有編輯權限的成員,但當您使用內嵌權杖提供身分識別時,則會將它套用至資料。While the Power BI service will not apply RLS setting to admins or members with edit permissions, when you supply an identity with an embed token, it will be applied to the data.
  • 內部部署伺服器支援 Analysis Services 即時連線。Analysis Services live connections are supported for on-premises servers.
  • Azure Analysis Services 即時連線支援依角色篩選,而非動態依使用者名稱篩選。Azure Analysis Services live connections support filtering by roles, but not dynamic by username.
  • 如果基礎資料集不需要 RLS,GenerateToken 要求不得包含有效的身分識別。If the underlying dataset doesn’t require RLS, the GenerateToken request must not contain an effective identity.
  • 如果基礎資料集是雲端模型 (快取模型或 DirectQuery),有效的身分識別必須包含至少一個角色,否則不會發生角色指派。If the underlying dataset is a cloud model (cached model or DirectQuery), the effective identity must include at least one role, otherwise role assignment will not occur.
  • 身分識別清單可讓多個身分識別權杖用於儀表板內嵌。A list of identities enables multiple identity tokens for dashboard embedding. 對於所有其他成品,此清單包含單一身分識別。For all others artifacts, the list contains a single identity.

有其他問題嗎?More questions? 嘗試在 Power BI 社群提問Try asking the Power BI Community