使用 Livy API 來提交和執行具有使用者認證的 Spark 工作階段作業

2025-05-05

適用於：✅Microsoft Fabric 中的資料工程和資料科學

藉由建立 Lakehouse 來開始使用 Livy API for Fabric Data Engineering;使用Microsoft Entra 令牌進行驗證;探索 Livy API 端點;將批次或會話作業從遠端用戶端提交至 Fabric Spark 計算;並監視結果。

這很重要

這項功能目前處於預覽階段。

必要條件

使用 LakeHouse 的 Fabric Premium 或試用版方案
啟用租戶管理員設定以使用 Livy API（預覽功能）
例如具備 Jupyter Notebook 支援的 Visual Studio Code、PySpark 和適用於 Python 的 Microsoft 驗證庫（MSAL）等遠端用戶端
Microsoft Entra 應用程式令牌之一。使用 Microsoft 身分識別平台來註冊應用程式
或Microsoft Entra SPN 令牌。在 Microsoft Entra 識別碼中新增和管理應用程式認證

選擇 REST API 用戶端

您可以使用各種程式設計語言或 GUI 用戶端來與 REST API 端點互動。在本文中，我們會使用 Visual Studio Code。 Visual Studio Code 必須使用適用於 Python 的 Jupyter Notebook、 PySpark 和 Microsoft 驗證連結庫（MSAL）進行設定

如何使用 Entra SPN 令牌授權 Livy API 要求

若要使用包括 Livy API 的 Fabric API，您必須先建立 Microsoft Entra 應用程式，並創建一個機密，然後在程式碼中使用該機密。您的應用程式必須經過適當註冊和設定，才能針對 Fabric 執行 API 呼叫。如需詳細資訊，請參閱在 Microsoft Entra ID 中新增和管理應用程式認證

建立應用程式註冊之後，請建立客戶端密碼。

當您建立客戶端密碼時，請務必複製值。您稍後在程式碼中會用到這個，並且無法再次查看這個秘密。除了程式代碼中的秘密之外，您還需要應用程式（用戶端）標識碼和目錄（租使用者識別元）。
接下來，我們需要將客戶端密碼新增至工作區。
搜尋 Entra 用戶端密碼，並將該秘密新增至工作區，並確定新新增的秘密具有管理員許可權。

如何使用 Entra 應用程式令牌授權 Livy API 請求

若要使用包含 Livy API 的網狀架構 API，您必須先建立Microsoft Entra 應用程式並取得令牌。您的應用程式必須經過適當註冊和設定，才能針對 Fabric 執行 API 呼叫。如需詳細資訊，請參閱使用 Microsoft 身分識別平台註冊應用程式。

有許多 Microsoft Entra 範圍許可權是執行 Livy 作業所需的。此範例使用簡單的 Spark 程式代碼 + 記憶體存取 + SQL：

Code.AccessAzureDataExplorer.All (存取Azure Data Explorer的全部資料)
Code.AccessAzureDataLake.All
Code.AccessAzureKeyvault.All（程式碼存取 Azure Keyvault 全部）
Code.AccessFabric.All
Code.AccessStorage.All
Item.ReadWrite.All
Lakehouse.Execute.All
Workspace.ReadWrite.All

注意

在公開預覽期間，這些範圍可能會隨著我們新增一些更細微的範圍而變更。當這些範圍變更發生時，您的 Livy 應用程式可能會中斷。請檢查此清單，因為它將會隨著新增範圍而更新。

某些客戶想要比先前清單更細微的許可權。您可以移除 Item.ReadWrite.All，並以這些更細微的範圍權限取代：

Code.AccessAzureDataExplorer.All (存取Azure Data Explorer的全部資料)
Code.AccessAzureDataLake.All
Code.AccessAzureKeyvault.All（程式碼存取 Azure Keyvault 全部）
Code.AccessFabric.All
Code.AccessStorage.All
Lakehouse.Execute.All
Lakehouse.ReadWrite.All
Workspace.ReadWrite.All
Notebook.ReadWrite.All
Spark工作定義.ReadWrite.All
MLModel.ReadWrite.All
MLExperiment.ReadWrite.All
Dataset.ReadWrite.All

當您註冊應用程式時，您需要應用程式（用戶端）識別碼和目錄（租用戶）標識碼。

顯示 Microsoft Entra 系統管理中心中 Livy API 應用程式概觀的螢幕快照。

呼叫 Livy API 的已驗證用戶必須是具有參與者角色的 API 和數據源專案所在的工作區成員。如需詳細資訊，請參閱讓使用者存取工作區。

如何找到 Fabric Livy API 的端點

需要 Lakehouse 工件才能存取 Livy 端點。建立 Lakehouse 之後，Livy API 端點就可以位於設定面板中。

Livy API 的端點會遵循下列模式：

https://api.fabric.microsoft.com/v1/workspaces/ < >ws_id/lakehouses/<lakehouse_id>/livyapi/versions/2023-12-01/

根據您的選擇，URL 會附加<會話>或<批次>。

下載 Livy API Swagger 檔案

您可以在這裡取得 Livy API 的完整 Swagger 檔案。

提交 Livy API 任務

現在 Livy API 的設定已完成，您可以選擇提交批次或會話作業。

與網狀架構環境整合

根據預設，此 Livy API 會話會針對工作區的預設起始集區執行。或者，您可以使用 Fabric 環境建立、設定及使用 Microsoft Fabric 中的環境，以自訂 Livy API 會話所使用的 Spark 作業的 Spark 集區。

若要在 Livy Spark 工作階段中使用網狀架構環境，只需更新 json 以包含此承載即可。

create_livy_session = requests.post(livy_base_url, headers = headers, json={
    "conf" : {
        "spark.fabric.environmentDetails" : "{\"id\" : \""EnvironmentID""}"}
    }
)

若要在 Livy Spark 批次工作階段中使用網狀架構環境，只需更新 json 承載，如下所示。

payload_data = {
"name":"livybatchdemo_with"+ newlakehouseName,
"file":"abfss://YourABFSPathToYourPayload.py", 
"conf": {
    "spark.targetLakehouse": "Fabric_LakehouseID",
    "spark.fabric.environmentDetails" : "{\"id\" : \""EnvironmentID"\"}"  # remove this line to use starter pools instead of an environment, replace "EnvironmentID" with your environment ID
    }
}

如何監視要求歷程記錄

您可以使用監視中樞來查看先前的 Livy API 提交，並偵錯任何提交錯誤。

共用方式為