共用方式為

產生內嵌權杖

  • 發行項

適用對象： 擁有資料的應用程式 擁有資料的使用者

產生權杖是 REST API，可讓您產生權杖以將 Power BI 報表或語意模型內嵌於 Web 應用程式或入口網站。 它可以針對單一項目或多個報表或語意模型產生權杖。 該權杖是用來針對 Power BI 服務授權您的要求。

產生權杖 API 會使用單一身分識別 (主要使用者或服務主體) 來為個別使用者產生權杖，視該使用者在應用程式中的認證 (有效身分識別) 而定。

在成功驗證之後，便會授與相關資料的存取權。

注意

產生權杖是較新的第 2 版 API，適用於報表和語意模型，以及單一或多個項目。 它比舊版的第 1 版 API 更受歡迎。 針對儀表板和磚，請使用 V1 儀表板 GenerateTokenInGroup 和 磚 GenerateTokenInGroup。

保護您的資料

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

建議您將工作區型隔離和設定檔搭配使用，但如果您想要使用 RLS 方法，請檢閱本文結尾的 RLS 章節。

權杖權限與安全性

在產生權杖 API 中，GenerateTokenRequest 區段會描述權杖權限。

存取層級

  • 使用 allowEdit 參數，授與使用者檢視或編輯權限。

  • 將工作區識別碼新增至內嵌權杖，讓使用者可在該工作區中建立新的報表 (SaveAs 或 CreateNew)。

低層級安全性

使用資料列層級安全性 (RLS)，您使用的身分識別可以與用於產生權杖的服務主體或主要使用者的身分識別不同。 使用不同的身分識別，您即可根據您的目標使用者顯示內嵌資訊。 例如，在您的應用程式中，您可以要求使用者登入，然後在登入的使用者是銷售員工時，顯示僅包含銷售資訊的報表。

如果您是使用 RLS，有時侯可以省略使用者的身分識別 (EffectiveIdentity 參數)。 當您不使用 EffectiveIdentity 參數時，權杖可以存取整個資料庫。 此方法可以用於授與存取權給管理員及主管等使用者，他們擁有檢視整個語意模型的權限。 不過，您無法在所有案例中使用此方法。 下表會列出不同的 RLS 類型，並顯示可以在不指定使用者身分識別的情況下使用哪一種驗證方法。

下表也會顯示適用於每一種 RLS 類型的考量與限制。

RLS 類型 我是否可以在不指定有效使用者識別碼的情況下產生內嵌權杖？ 考量與限制
雲端資料列層級安全性 (雲端 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 端點] 設定為 [唯讀] 或 [讀寫]，如啟用 Premium 容量的 read-write (部分機器翻譯) 中所述。 您只需要對每個容量執行一次。
    • 產生多資源內嵌權杖
      • 在要求中指定所有資料集識別碼。
      • 針對要求中的每個語意模型，將 XmlaPermissions 設定為 [唯讀]。
      • 針對每個已啟用單一登入 (SSO) 的資料來源，在 DatasourceIdentity 中提供資料來源的身分識別 Blob。

    在權杖到期之前更新權杖

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

    儀表板和磚

    產生權杖適用於報表和語意模型。 若要產生儀表板或磚的內嵌權杖，請使用版本 1 儀表板 GenerateTokenInGroup 或 磚 GenerateTokenInGroup API。 這些 API 一次只產生一個項目的權杖。 您無法產生多個項目的權杖。

    針對這些 API：

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

      • View - 授與使用者檢視權限。

      • Edit - 授與使用者檢視及編輯權限 (僅適用於為報表產生內嵌權杖)。

      • Create - 授與使用者建立新報表的權限 (僅適用於為建立報表產生內嵌權杖)。 針對報表建立，您也必須提供 datasetId 參數。

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

    考量與限制

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

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

    • 您無法為我的工作區建立內嵌權杖。

    相關內容