使用 Livy API 通过用户凭据提交和执行 Spark 会话作业

2025-05-06

适用于：✅Microsoft Fabric 中的数据工程和数据科学

通过创建 Lakehouse 开始使用 Livy API for Fabric 数据工程;使用 Microsoft Entra 令牌进行身份验证;发现 Livy API 终结点;将批处理作业或会话作业从远程客户端提交到 Fabric Spark 计算;并监视结果。

重要

此功能目前为预览版。

先决条件

具有湖屋的 Fabric 高级版或试用版容量
为 Livy API 启用租户管理员设置（预览版）
远程客户端，例如带有 Jupyter Notebooks 支持、PySpark 和适用于 Python 的 Microsoft 身份验证库 (MSAL) 的 Visual Studio Code
要么是 Microsoft Entra 应用令牌。将应用程序注册到 Microsoft 标识平台
或者Microsoft Entra SPN 令牌。在 Microsoft Entra ID 中添加和管理应用程序凭据

选择 REST API 客户端

可以使用各种编程语言或 GUI 客户端与 REST API 终结点交互。在本文中，我们使用 Visual Studio Code。 Visual Studio Code 需要使用 Jupyter Notebooks、PySpark 和适用于 Python 的 Microsoft 身份验证库 (MSAL) 进行配置

如何使用 Entra SPN 令牌授权 Livy API 请求

若要使用 Fabric API（包括 Livy API），首先需要创建Microsoft Entra 应用程序，并在代码中创建机密并使用该机密。应用程序需要充分注册和配置，以便对 Fabric 执行 API 调用。有关详细信息，请参阅 Microsoft Entra ID 中的“添加和管理应用程序凭据”

创建应用注册后，创建客户端密码。

创建客户端密码时，请确保复制该值。稍后在代码中需要此密钥，但此密钥将不再可见。除了代码中的机密外，还需要应用程序（客户端）ID 和目录（租户 ID）。
接下来，我们需要将客户端密码添加到工作区。
搜索 Entra 客户端密码，并将该机密添加到工作区，并确保新添加的机密具有管理员权限。

如何使用 Entra 应用令牌授权 Livy API 请求

若要使用包括 Livy API 在内的 Fabric API，首先需要创建一个 Microsoft Entra 应用程序并获取令牌。应用程序需要充分注册和配置，以便对 Fabric 执行 API 调用。有关详细信息，请参阅将应用程序注册到 Microsoft 标识平台。

执行 Livy 作业需要许多 Microsoft Entra 范围权限。此示例使用简单的 Spark 代码 + 存储访问 + SQL：

Code.AccessAzureDataExplorer.All
Code.AccessAzureDataLake.All
Code.AccessAzureKeyvault.All
Code.AccessFabric.All
Code.AccessStorage.All
Item.ReadWrite.All
Lakehouse.Execute.All
Workspace.ReadWrite.All

注意

在公共预览期间，随着我们添加一些更精细的范围，这些范围可能会发生变化。当这些范围更改发生时，Livy 应用可能会中断。请查看此列表，因为它将随着附加范围而更新。

有些客户想要比之前的列表更细粒度的权限。可以移除 Item.ReadWrite.All 并将其替换为以下更细粒度的范围权限：

Code.AccessAzureDataExplorer.All
Code.AccessAzureDataLake.All
Code.AccessAzureKeyvault.All
Code.AccessFabric.All
Code.AccessStorage.All
Lakehouse.Execute.All
Lakehouse.ReadWrite.All
Workspace.ReadWrite.All
Notebook.ReadWrite.All
SparkJobDefinition.ReadWrite.All
MLModel.ReadWrite.All
MLExperiment.ReadWrite.All
Dataset.ReadWrite.All

注册应用程序时，需要应用程序（客户端）ID 和目录（租户）ID。

在 Microsoft Entra 管理中心显示 Livy API 应用概述的屏幕截图。

调用 API 的经过身份验证的用户需要是 Livy API 和数据源项所在的工作区成员，并具有参与者角色。有关详细信息，请参阅授予用户对工作区的访问权限。

如何发现 Fabric Livy API 终结点

需要湖屋项目才能访问 Livy 终结点。创建湖屋后，可以在设置面板中找到 Livy API 终结点。

Livy API 终结点将遵循以下模式：

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

URL 附加有 <sessions> 或 <batches>，具体取决于选择的内容。

下载 Livy API Swagger 文件

Livy API 的完整 Swagger 文件可在此处获取。

提交 Livy API 作业

完成 Livy API 的设置后，可以选择提交批处理或会话作业。

与 Fabric 环境集成

默认情况下，此 Livy API 会话针对工作区的默认初学者池运行。或者，你可以使用 Fabric 环境。在 Microsoft Fabric 中创建、配置并使用环境来自定义由 Livy API 会话用于这些 Spark 作业的 Spark 池。

若要在 Livy Spark 会话中使用 Fabric 环境，只需更新 json 以包含此有效负载。

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

若要在 Livy Spark 批处理会话中使用 Fabric 环境，只需更新 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 提交，并调试任何提交错误。

通过