Uso de livy API para enviar y ejecutar trabajos de sesión de Spark con credenciales de usuario

2025-05-08

Se aplica a:✅ Ingeniería de datos y ciencia de datos en Microsoft Fabric

Empiece a trabajar con Livy API for Fabric Data Engineering mediante la creación de una instancia de Lakehouse; autenticación con un token de Microsoft Entra; detectar el punto de conexión de Livy API; enviar trabajos por lotes o de sesión desde un cliente remoto al proceso de Fabric Spark; y supervise los resultados.

Importante

Esta característica se encuentra en versión preliminar.

Requisitos previos

Capacidad de Fabric Premium o prueba con una instancia de LakeHouse
Habilitación de Configuración de administrador de inquilinos para Livy API (versión preliminar)
Un cliente remoto, como Visual Studio Code con compatibilidad con cuadernos de Jupyter Notebook, PySpark y Biblioteca de autenticación de Microsoft (MSAL) para Python
Un token de aplicación de Microsoft Entra. Registro de una aplicación en la plataforma de identidad de Microsoft
O un token de SPN de Microsoft Entra. Adición y administración de credenciales de aplicación en el identificador de Microsoft Entra

Elección de un cliente de API de REST

Puede usar varios lenguajes de programación o clientes de GUI para interactuar con los puntos de conexión de la API de REST. En este artículo, se usa Visual Studio Code. Visual Studio Code debe configurarse con Cuadernos de Jupyter Notebook, PySpark y la Biblioteca de autenticación de Microsoft (MSAL) para Python

Autorización de las solicitudes de la API de Livy con un token de SPN de Entra

Para trabajar con las API de Fabric, incluida la API de Livy, primero debe crear una aplicación de Microsoft Entra y crear un secreto y usar ese secreto en el código. La aplicación debe registrarse y configurarse adecuadamente para realizar llamadas API en Fabric. Para obtener más información, consulte Incorporación y administración de credenciales de aplicación en Microsoft Entra ID.

Después de crear el registro de la aplicación, cree un secreto de cliente.

Al crear el secreto de cliente, asegúrese de copiar el valor. Lo necesitarás más adelante en el código y el secreto no se podrá ver de nuevo. También necesitará el id. de aplicación (cliente) y el directorio (id. de inquilino) además del secreto en el código.
A continuación, es necesario agregar el secreto de cliente a nuestro área de trabajo.
Busque el secreto de cliente entra y agregue ese secreto al área de trabajo y asegúrese de que el secreto recién agregado tiene permisos de administrador.

Cómo autorizar las solicitudes de la API de Livy con un token de aplicación Entra

Para trabajar con las API de Fabric, incluida la API de Livy, primero debe crear una aplicación de Microsoft Entra y obtener un token. La aplicación debe registrarse y configurarse adecuadamente para realizar llamadas API en Fabric. Para más información, consulte Registro de una aplicación con la plataforma de identidad de Microsoft.

Hay muchos permisos de ámbito de Microsoft Entra necesarios para ejecutar trabajos de Livy. En este ejemplo se usa código de Spark simple + acceso de almacenamiento + 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

Nota:

Durante la versión preliminar pública, estos ámbitos pueden cambiar a medida que agregamos algunos ámbitos más granulares. Cuando estos cambios de ámbito se producen, la aplicación Livy puede interrumpirse. Compruebe esta lista, ya que se actualizará con los ámbitos adicionales.

Algunos clientes quieren permisos más pormenorizados que la lista anterior. Puede quitar Item.ReadWrite.All y reemplazar por estos permisos de ámbito más granulares:

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

Al registrar la aplicación, necesitará tanto el identificador de aplicación (cliente) como el identificador de directorio (inquilino).

Captura de pantalla que muestra información general de la aplicación Livy API en el centro de administración de Microsoft Entra.

El usuario autenticado que llama a la API Livy debe ser un miembro del área de trabajo donde tanto la API como los elementos del origen de datos se encuentran con un rol colaborador. Para más información, consulte Conceder acceso a los usuarios a las áreas de trabajo.

Detección del punto de conexión de Fabric Livy API

Se requiere un artefacto de Lakehouse para acceder al endpoint (punto de conexión) de Livy. Una vez creado Lakehouse, el punto de conexión de Livy API se puede ubicar en el panel de configuración.

El punto de conexión de Livy API seguiría este patrón:

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

La dirección URL se anexa con <sesiones> o <lotes> en función de lo que elija.

Descarga los archivos Swagger de la Livy API

Los archivos Swagger completos para la API de Livy están disponibles aquí.

Enviar trabajos de la API de Livy

Ahora que se ha completado la configuración de Livy API, puede optar por enviar trabajos por lotes o de sesión.

Integración con entornos de Fabric

De forma predeterminada, esta sesión de Livy API se ejecuta en el grupo de inicio predeterminado para el área de trabajo. Como alternativa, puede usar entornos en Microsoft Fabric Crear, configurar y usar un entorno en Microsoft Fabric para personalizar el grupo de Spark que emplea la sesión de la API de Livy para estos trabajos de Spark.

Para usar un entorno de Fabric en una sesión de Livy Spark, basta con actualizar el json para incluir esta carga.

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

Para usar un entorno de Fabric en una sesión por lotes de Livy Spark, basta con actualizar la carga json como se muestra a continuación.

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
    }
}

Supervisión del historial de solicitudes

Puede usar el Centro de supervisión para ver los envíos anteriores de Livy API y depurar los errores de envío.