產生內嵌令牌

  • 發行項

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

產生令牌 是 REST API，可讓您產生令牌，以在 Web 應用程式或入口網站中內嵌 Power BI 報表或語意模型。 它可以為單一專案或多個報表或語意模型產生令牌。 令牌是用來授權對 Power BI 服務 的要求。

產生的令牌 API 會使用單一身分識別（主要使用者或服務主體）為個別用戶產生令牌，視該應用程式中的用戶認證而定（有效身分識別）。

成功驗證之後，會授與相關數據的存取權。

注意

產生令牌 是較新的第 2 版 API，適用於報表和語意模型，以及單一或多個專案。 它優先於舊版第 1 版 API。 針對儀錶板和磚，請使用 V1 儀錶板 GenerateTokenInGroup 和 Tiles GenerateTokenInGroup。

保護您的數據

如果您要處理多個客戶的數據，有兩個主要方法來保護您的數據：工作區型隔離和數據列層級安全性型隔離。 您可以在服務主體設定檔和資料列層級安全性中找到它們之間的詳細比較。

建議您搭配配置檔使用以工作區為基礎的隔離，但如果您想要使用 RLS 方法，請檢閱 本文結尾的 RLS 區段 。

令牌許可權和安全性

在產生令牌 API 中 ，GenerateTokenRequest 區段描述令牌許可權。

存取層級

  • 使用allowEdit參數授與用戶檢視或編輯許可權。

  • 將工作區標識符新增至內嵌令牌，讓使用者在該工作區中建立新的報表（ SaveAs 或 CreateNew）。

低層級安全性

使用 數據列層級安全性 （RLS）時，您使用的身分識別可能會與您用來產生令牌的服務主體或主要使用者的身分識別不同。 藉由使用不同的身分識別，您可以根據目標用戶顯示內嵌資訊。 例如，在您的應用程式中，您可以要求使用者登入，然後在登入的使用者是銷售員工時，顯示只包含銷售資訊的報表。

如果您使用 RLS，有時可能會省略使用者的身分識別（ EffectiveIdentity 參數）。 當您不使用 EffectiveIdentity 參數時，令牌可以存取整個資料庫。 這個方法可用來將存取權授與管理員，例如管理員和管理員，他們有權檢視整個語意模型。 不過，您無法在每個案例中使用此方法。 下表列出不同的 RLS 類型，並顯示哪些驗證方法可以使用，而不需指定使用者的身分識別。

下表也會顯示適用於每個 RLS 類型的考慮和限制。

RLS 類型 我可以產生內嵌令牌而不指定有效的使用者標識碼嗎？ 考量與限制
雲端資料列層級安全性 （Cloud RLS） ✔ 主要使用者
✖ 服務主體
RDL （編頁報告） ✖ 主要使用者
✔ 服務主體		 您無法使用主要用戶來產生 RDL 的內嵌令牌。
Analysis Services （AS） 內部部署即時連線 ✔ 主要使用者
✖ 服務主體		 產生內嵌令牌的使用者也需要下列其中一個許可權：
  • 閘道管理員許可權
  • 資料源模擬許可權 （ReadOverrideEffectiveIdentity）
    		•
    Analysis Services （AS） Azure 實時連線 ✔ 主要使用者
    ✖ 服務主體    		 無法覆寫產生內嵌令牌的使用者身分識別。 自定義數據可用來實作動態 RLS 或安全篩選。

    注意： 服務主體必須提供其物件標識碼作為有效的身分識別（RLS 用戶名稱）。
    單一登入 （SSO） ✔ 主要使用者
    ✖ 服務主體    		 您可以使用有效身分識別物件中的身分識別 Blob 屬性來提供明確的 （SSO） 身分識別
    SSO 和雲端 RLS ✔ 主要使用者
    ✖ 服務主體    		 您必須提供下列專案：
  • 有效身分識別物件中身分識別 Blob 屬性中的明確 （SSO） 身分識別
  • 有效 （RLS） 身分識別 （使用者名稱）
    		•

    注意

    服務主體必須一律提供下列資訊：

    • 任何具有 RLS 語意模型之專案的身分識別。
    • 針對 SSO 語意模型，已定義關係型 （SSO） 身分識別的有效 RLS 身分識別。

    適用於 Power BI 語意模型的 DirectQuery

    若要內嵌具有與另一個 Power BI 語意模型直接查詢連線的語意模型 Power BI 報表，請執行下列動作：

    • 在 Power BI 入口網站中，將 XMLA 端點設定為 [只讀] 或 [讀取寫入]，如啟用 進階版 容量的讀寫中所述。 您只需要針對每個容量執行此動作一次。
    • 產生 多資源內嵌令牌
      • 在要求中指定所有數據集標識碼。
      • XmlaPermissions針對要求中的每個語意模型，將 設定為 [只讀]。
      • 針對每個已啟用單一登錄 （SSO） 的數據源，提供 中數據源的 DatasourceIdentity身分識別 Blob。

    在令牌到期之前更新令牌

    令牌隨附時間限制。 這表示在內嵌 Power BI 項目之後，您有有限的時間來與其互動。 若要讓使用者持續體驗， 請在令牌到期前更新（或重新整理）。

    儀錶板和磚

    產生 令牌 適用於報表和語意模型。 若要產生儀錶板或磚的內嵌令牌，請使用第 1 版儀錶板 GenerateTokenInGroup 或 Tiles GenerateTokenInGroup API。 這些 API 一次只產生一個專案的令牌。 您無法為多個項目產生令牌。

    針對下列 API：

    • 使用 accessLevel 參數來判斷使用者的存取層級。

      • 檢視 - 授與用戶檢視許可權。

      • 編輯 - 授與用戶檢視和編輯許可權（僅適用於產生報表的內嵌令牌時）。

      • 建立 - 授與使用者建立新報表的許可權（僅適用於產生用於建立報表的內嵌令牌時）。 若要建立報表，您也必須提供 datasetId 參數。

    • 使用allowSaveAs布林值，讓使用者將報表儲存為新的報表。 此設定預設會設定為 false ，而且只會在產生報表的內嵌令牌時套用。

    考量與限制

    • 基於安全性考慮，內嵌令牌的存留期會設定為用來呼叫 GenerateToken API 的 Microsoft Entra 令牌剩餘存留期。 因此，如果您使用相同的 Microsoft Entra 令牌來產生數個內嵌令牌，產生的內嵌令牌存留期會隨著每個呼叫而縮短。

    • 如果要內嵌的語意模型和項目位於兩個不同的工作區中， 服務主體 或 主要使用者 至少必須是兩個工作區的成員。

    • 您無法為 [我的工作區] 建立內嵌令牌。

    相關內容