Microsoft Fabric 中的工作負載驗證指導方針概觀

本文提供在建置Microsoft網狀架構工作負載時如何使用驗證的指導方針。包含有關處理代幣和授權同意的資訊。

開始之前，請確定您已熟悉驗證概觀和驗證設定的概念。

資料平面與控制平面 API

數據平面 API 是工作負載後端公開的 API。工作負載前端可以直接呼叫它們。對於資料平面 API，工作負載後端可以決定要暴露哪些 API。
控制平面 API 是透過 Fabric 傳輸的 API。此程式會從呼叫 JavaScript API 的工作負載前端開始，並以網狀架構呼叫工作負載後端結束。這類 API 的一個例子是建立項目。

針對控制平面 API，工作負載必須遵循工作負載後端中定義的合約，並實作這些 API。

在 Microsoft Entra ID 中公開工作負載應用程式的 API 標籤

在 公開 API 索引標籤上，您需要新增控制平面 API 的權限範圍，以及資料平面 API 的權限範圍：

新增的控制平面 API 範圍應預先授權 Fabric Client for Workloads 應用程式，並附有應用程式 ID d2450708-699c-41e3-8077-b0c8341509aa。當 Fabric 呼叫工作負載後端時，該後端所收到的權杖中包含這些範圍。

您必須為控制平面 API 新增至少一個範圍，流程才能運作。
為資料平面 API 新增的權限範圍應以應用程式 ID 871c010f-5e61-4fb1-83ac-98610a7e9110 預先授權 Microsoft Power BI。它們包含在 JavaScript API 回傳的權杖acquireAccessToken中。

針對資料平面 API，你可以使用此分頁來管理工作負載所公開之各個 API 的細部權限。在理想情況下，您應該為工作負載後端公開的每個 API 新增一組範圍，並在從用戶端呼叫這些 API 時驗證收到的令牌是否包含這些範圍。例如：
- 工作負載會將兩個 API 公開給用戶端，ReadData 和 WriteData。
- 工作負載會揭示兩個數據平面範圍，data.read 和 data.write。
- 在 ReadData API 中，工作負載會先驗證權杖中是否包含 data.read 範圍，然後才繼續執行流程。同樣適用於 WriteData。

Microsoft Entra ID 中工作負載應用程式的 API 權限標籤

在 API 權限 標籤中，你需要新增所有工作負載需要交換權杖的範圍。必須新增的必要範圍是 Power BI 服務下的 Fabric.Extend。若沒有此範圍，對 Fabric 的要求可能會失敗。

使用代幣與同意

當您使用數據平面 API 時，工作負載前端必須取得令牌，才能呼叫工作負載後端。

以下章節說明工作負載前端應如何利用 JavaScript API 及代理（OBO）流程來取得工作負載及外部服務的令牌，並取得同意。

步驟 1：取得令牌

工作負載一開始會使用 JavaScript API 來要求令牌，而不需要提供任何參數。此呼叫可能會導致兩個案例：

使用者會看到一個同意視窗，列出工作負載所設定的所有靜態相依性（亦即在 API 權限 索引標籤上設定的項目）。如果使用者不屬於應用程式的主租使用者，且之前未授權此應用程式使用 Microsoft Graph，就會發生這種情況。
使用者看不到同意視窗。如果使用者已至少一次針對此應用程式同意 Microsoft Graph 的權限要求，或使用者屬於該應用程式的主租用戶，就會發生這種情況。

在這兩種情況下，工作負載都不應在乎使用者是否已對所有相依性給予完整同意（而且在現階段也無從得知）。收到的令牌擁有工作負載後端的受眾，並可直接從工作負載前端呼叫工作負載後端。

步驟 2：嘗試存取外部服務

工作負載可能需要存取需要驗證的服務。為了取得該存取，它需要執行 OBO 流程，將從客戶端或 Fabric 收到的令牌交換給其他服務。令牌交換可能因缺乏同意，或是工作負載試圖交換令牌的資源上設定了某種 Microsoft Entra 條件式存取政策而失敗。

為了解決這個問題，當前端與後端之間進行直接呼叫時，應由工作負載負責將錯誤傳遞給用戶端。工作負載也有責任在處理來自 Fabric 的呼叫時，使用工作負載通訊中所述的錯誤傳播機制，將錯誤傳播給客戶端。

在工作負載傳播錯誤之後，它可以呼叫 acquireAccessToken JavaScript API 來解決同意或條件式存取原則問題，然後重試作業。

如資料面 API 發生故障，請參閱多重驗證、條件性存取及累進同意處理。關於控制平面 API 失敗，請參見工作負載通訊。

範例案例

讓我們看看需要存取三個網狀架構 API 的工作負載：

列出工作區： GET https://api.fabric.microsoft.com/v1/workspaces
建立倉庫： POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/warehouses
寫入湖倉檔案：PUT https://onelake.dfs.fabric.microsoft.com/{filePath}?resource=file

為了能與這些 API 合作，工作負載後端需要交換以下範圍內的令牌：

列出工作區的方法為：https://analysis.windows.net/powerbi/api/Workspace.Read.All 或 https://analysis.windows.net/powerbi/api/Workspace.ReadWrite.All
若要建立倉儲：https://analysis.windows.net/powerbi/api/Warehouse.ReadWrite.All 或 https://analysis.windows.net/powerbi/api/Item.ReadWrite.All
若要寫入 Lakehouse 檔案： https://storage.azure.com/user_impersonation

附註

你可以在這篇參考文章中找到每個 Fabric API 所需的作用範圍。

前述的範圍需要在工作負載應用程式中依 API 權限設定。

讓我們看看工作負載可能遇到的案例範例。

範例 1

假設工作負載後端有一個數據平面 API，可取得使用者的工作區，並將其傳回用戶端：

工作負載前端會透過 JavaScript API 要求一個令牌。
工作負載前端會呼叫工作負載後端 API，取得使用者的工作空間，並在請求中附加權杖。
工作負載後端會 https://analysis.windows.net/powerbi/api/Workspace.Read.All驗證該令牌，並嘗試將其交換為所需的範圍（假設）。
工作負載無法交換指定資源的令牌，因為使用者未同意應用程式存取此資源（請參閱 AADSTS 錯誤碼）。
工作負載後端會將錯誤傳遞給工作負載前端，指定該資源需要同意。工作負載前端呼叫 acquireAccessToken JavaScript API，並提供additionalScopesToConsent：

workloadClient.auth.acquireAccessToken({additionalScopesToConsent: ["https://analysis.windows.net/powerbi/api/Workspace.Read.All"]})

或者，工作負載可以決定為其應用程式上設定的所有靜態相依關係徵求同意，因此會呼叫 JavaScript API 並提供promptFullConsent：

workloadClient.auth.acquireAccessToken({promptFullConsent: true})。

不論使用者是否同意某些相依性，此呼叫都會提示同意視窗。之後，工作負載前端可以重試作業。

附註

如果令牌交換在同意錯誤時仍然失敗，表示使用者未授與同意。工作負載需要處理這類情境；例如，通知使用者此 API 需要同意，否則將無法運作。

範例 2

假設工作負載後端需要透過 Create Item API 存取 OneLake（從 Fabric 呼叫工作負載）：

工作負載前端會呼叫建立項目 JavaScript API。
工作負載後端會從 Fabric 接收呼叫，並擷取委派的令牌並加以驗證。
工作負載嘗試交換權杖https://storage.azure.com/user_impersonation，但因為使用者設定的多重驗證租戶管理員需要存取 Azure 儲存體（參見 AADSTS 錯誤代碼）而失敗。
工作負載會使用 Workload communication 中所述的錯誤傳播機制，將錯誤以及 Microsoft Entra ID 在錯誤中傳回的宣告一併傳遞給用戶端。
工作負載前端會呼叫 acquireAccessToken JavaScript API，並將宣告提供為 claimsForConditionalAccessPolicy，其中 claims 是指從工作負載後端傳播過來的宣告。

workloadClient.auth.acquireAccessToken({claimsForConditionalAccessPolicy: claims})

之後，工作負載可以重試該操作。

請求同意時的處理錯誤

有時候使用者因為各種錯誤而無法授與同意。同意要求之後，系統會將回應傳回至重新導向 URI。在我們的範例中，此程式碼負責處理回應。（您可以在index.ts檔案中找到它。

const redirectUriPath = '/close'; 
const url = new URL(window.location.href); 
if (url.pathname?.startsWith(redirectUriPath)) { 
    // Handle errors, Please refer to https://learn.microsoft.com/entra/identity-platform/reference-error-codes 
    if (url?.hash?.includes("error")) { 
        // Handle missing service principal error 
        if (url.hash.includes("AADSTS650052")) { 
            printFormattedAADErrorMessage(url?.hash); 
        // handle user declined the consent error 
        } else  if (url.hash.includes("AADSTS65004")) { 
            printFormattedAADErrorMessage(url?.hash); 
        } 
    } 
    // Always close the window  
    window.close(); 
}

工作負載前端可以從 URL 擷取錯誤碼並據以處理。

附註

在這兩種情況（錯誤與成功）中，工作負載都必須立即關閉視窗，且不得有延遲。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-08-30