產生內嵌權杖時的考量Considerations when generating an embed token

產生權杖是可讓您產生權杖以將 Power BI 項目內嵌於 Web 應用程式或入口網站的 REST API。Generate token is a REST API that lets you generate a token for embedding a Power BI item in a web app or a portal. 該權杖是用來針對 Power BI 服務授權您的要求。The token is used to authorize your request against the Power BI service.

產生權杖 API 會使用單一身分識別 (主要使用者或服務主體) 來為個別使用者產生權杖,視該使用者在應用程式中的認證 (有效身分識別) 而定。The generate token API uses a single identity (a master user or service principal) to generate a token for an individual user, depending on that user's credentials in the app (effective identity).

在成功驗證之後,便會授與相關資料的存取權。After successful authentication, access to the relevant data is granted.

注意

產生權杖僅適用於您為客戶進行內嵌 (也稱為「應用程式擁有資料」案例) 的情況。Generate token is only applicable when you're embedding for your customers (also known as the app owns data scenario).

您可以使用下列 API 來產生權杖:You can use the following APIs to generate a token:

工作區版本Workspace versions

Power BI 具有兩種工作區版本,「傳統」工作區,以及「新」工作區。Power BI has two workspace versions, a classic workspace, and a new workspace. 您可以在新工作區和傳統工作區的差異中深入了解這兩種工作區之間的差異。You can learn more about the differences between these workspaces in new and classic workspace differences.

建立內嵌權杖時,不同的工作區會有不同的考量,且需要不同的權限。When creating an embed token, different workspaces have different considerations and require different permissions.

「傳統」工作區Classic workspace 「新」工作區New workspace
考量Considerations
  • 資料集和項目必須位於相同的工作區The dataset and the item must be in the same workspace
  • 無法使用服務主體Service principal cannot be used
  • 資料集和項目可以位於兩個不同的「新」工作區The dataset and the item can be in two different new workspaces
    工作區權限Workspace permissions 主要使用者必須是工作區的系統管理員The master user must be an admin of the workspace 服務主體或主要使用者至少必須是這兩個工作區的成員The service principal or master user must be at least a member of both workspaces

    注意

    • 您無法為我的工作區建立內嵌權杖。You cannot create an embed token for My workspace.
    • 「項目」指的是如儀表板、磚、Q&A 或報表的 Power BI 項目。The word item refers to a Power BI item such as a dashboard, tile, Q&A or report.

    保護您的資料Securing your data

    建立解決方案時,請考慮使用這兩種方法來保護您的資料:When creating your solution, consider these two approaches for securing your data:

    如果您要使用 RLS 方法,請檢閱此文章結尾的 RLS 考量與限制If you're going to use the RLS approach, review the RLS considerations and limitations at the end of this article.

    權杖權限Token permissions

    在產生權杖 API 中,GenerateTokenRequest 區段會描述權杖權限。In the generate token APIs, the GenerateTokenRequest section describes the token permissions.

    注意

    此區段中所列出的權杖權限並不適用於為多份報表產生權杖 API。The token permissions listed in this section are not applicable for the Generate token for multiple reports API.

    存取層級Access Level

    使用 accessLevel 參數來判斷使用者的存取層級。Use the accessLevel parameter to determine the user's access level.

    • View - 授與使用者檢視權限。View - Grant the user viewing permissions.

    • Edit - 授與使用者檢視及編輯權限 (僅適用於為報表產生內嵌權杖)。Edit - Grant the user viewing and editing permissions (only applies when generating an embed token for a report).

      如果您是使用 為多份報表產生權杖 API,請使用 allowEdit 參數來為使用者授與檢視及編輯權限。If you're using the Generate token for multiple reports API, use the allowEdit parameter to grant the user viewing and editing permissions.

    • Create - 授與使用者建立報表的權限 (僅適用於為建立報表產生內嵌權杖)。Create - Grant the user permissions to create a report (only applies when generating an embed token for creating a report).

      針對報表建立,您也必須提供 datasetId 參數。For report creation, you must also supply the datasetId parameter.

    儲存報表的複本Saving a copy of the report

    使用 allowSaveAs 布林值來讓使用者將報表儲存為新的報表。Use the allowSaveAs boolean to let users save the report as a new report. 根據預設,此設定值已設定為 falseThis setting is set to false by default.

    此參數僅適用於為報表產生內嵌權杖。This parameter is only applicable when generating an embed token for a report.

    資料列層級安全性Row Level Security

    透過使用資料列層級安全性 (RLS),您可以選擇使用與您用來產生權杖的服務主體或主要使用者身分識別不同的身分識別。With Row Level Security (RLS), you can choose to use a different identity than the identity of the service principal or master user you're generating the token with. 透過使用此選項,您可以根據您的目標使用者顯示內嵌資訊。Using this option, you can display embedded information according to the user you're targeting. 例如,在您的應用程式中,您可以要求使用者登入,然後在登入的使用者是銷售員工時,顯示僅包含銷售資訊的報表。For example, in your application you can ask users to sign in, and then display a report that only contains sales information if the signed in user is a sales employee.

    如果您是使用 RLS,在某些情況下,您可以省略使用者的身分識別 (EffectiveIdentity 參數)。If you're using RLS, you can in some cases leave out the user's identity (the EffectiveIdentity parameter). 這可讓權杖存取整個資料庫。This allows the token to have access to the entire database. 此方法可以用來為系統管理員及主管等使用者授與存取權,其將會具有檢視整個資料集的權限。This method can be used to grant access to users such as admins and managers, who have the permissions to view the entire dataset. 不過,您無法在所有案例中使用此方法。However, you cannot use this method in every scenario. 下表會列出不同的 RLS 類型,並顯示可以在不指定使用者身分識別的情況下使用哪一種驗證方法。The table below lists the different RLS types, and shows which authentication method can be used without specifying a user's identity.

    下表也會顯示適用於每一種 RLS 類型的考量與限制。The table also shows the considerations and limitation applicable to each RLS type.

    RLS 類型RLS type 我是否可以在不指定有效使用者識別碼的情況下產生內嵌權杖?Can I generate an embed token without specifying the effective user ID? 考量與限制Considerations and limitations
    雲端資料列層級安全性 (雲端 RLS)Cloud Row Level Security (Cloud RLS) ✔ 主要使用者✔ Master user
    ✖ 服務主體✖ Service principal
    RDL (編頁報表)RDL (paginated reports) ✖ 主要使用者✖ Master user
    ✔ 服務主體✔ Service principal
    您無法使用主要使用者來為 RDL 產生內嵌權杖。You cannot use a master user to generate an embed token for RDL.
    Analysis Services (AS) 內部部署即時連線Analysis Services (AS) on premises live connection ✔ 主要使用者✔ Master user
    ✖ 服務主體✖ Service principal
    產生內嵌權杖的使用者也需要下列其中一種權限:The user generating the embed token also needs one of the following permissions:
  • 閘道管理員權限Gateway admin permissions
  • 資料來源模擬權限 (ReadOverrideEffectiveIdentity)Datasource impersonate permission (ReadOverrideEffectiveIdentity)
  • Analysis Services (AS) Azure 即時連線Analysis Services (AS) Azure live connection ✔ 主要使用者✔ Master user
    ✖ 服務主體✖ Service principal
    無法覆寫產生內嵌權杖之使用者的身分識別。The identity of the user generating the embed token cannot be overridden. 可以使用自訂資料來實作動態 RLS 或安全篩選。Custom data can be used to implement dynamic RLS or secure filtering.

    注意: 服務主體必須提供其物件識別碼作為有效身分識別 (RLS 使用者名稱)。Note: Service principal must provide its object ID as the effective identity (RLS username).
    單一登入 (SSO)Single Sign On (SSO) ✔ 主要使用者✔ Master user
    ✖ 服務主體✖ Service principal
    可以使用有效身分識別物件中的身分識別 Blob 屬性來提供明確 (SSO) 身分識別An explicit (SSO) identity can be provided using the identity blob property in an effective identity object
    SSO 和雲端 RLSSSO and cloud RLS ✔ 主要使用者✔ Master user
    ✖ 服務主體✖ Service principal
    您必須提供下列項目:You must provide the following:
  • 有效身分識別物件的身分識別 Blob 屬性中的明確 (SSO) 身分識別Explicit (SSO) identity in the identity blob property property in an effective identity object
  • 有效 (RLS) 身分識別 (使用者名稱)Effective (RLS) identity (username)
  • 注意

    服務主體必須一律提供下列項目:Service principal must always provide the following:

    • 具有 RLS 資料集之任何項目的身分識別。An identity for any item with an RLS dataset.
    • 針對 SSO 資料集,需要已定義使用者名稱屬性的有效 RLS 身分識別。For an SSO dataset, an effective RLS identity with the username property defined.

    後續步驟Next steps