Utiliser l’API Livy pour envoyer et exécuter des travaux de session Spark avec des informations d’identification utilisateur

2025-05-05

S’applique à :✅ l'ingénierie des données et la science des données dans Microsoft Fabric

Commencez avec l'API Livy pour Fabric Data Engineering en créant un Lakehouse, en vous authentifiant avec un jeton Microsoft Entra, en découvrant le point de terminaison de l'API Livy, en soumettant des travaux par lots ou de session depuis un client distant vers le calcul Fabric Spark, et en surveillant les résultats.

Important

Cette fonctionnalité est en version préliminaire.

Prérequis

Capacité Fabric Premium ou d’essai avec un Lakehouse
Activer le Paramètre administrateur client pour l’API Livy (préversion)
Un client distant tel que Visual Studio Code avec prise en charge de Jupyter Notebooks, de PySpark et de la bibliothèque d’authentification Microsoft (MSAL) pour Python
Soit un jeton d’application Microsoft Entra. Inscrire une application avec la plateforme d’identités Microsoft
Ou un jeton Microsoft Entra SPN. Ajouter et gérer des informations d’identification d’application dans l’ID Microsoft Entra

Choix d’un client d’API REST

Vous pouvez utiliser différents langages de programmation ou clients GUI pour interagir avec les points de terminaison d’API REST. Dans cet article, nous utilisons Visual Studio Code. Visual Studio Code doit être configuré avec Jupyter Notebooks, PySpark et la bibliothèque d’authentification Microsoft (MSAL) pour Python

Comment autoriser les demandes d’API Livy avec un jeton SPN Entra

Pour utiliser des API Fabric, notamment l’API Livy, vous devez d’abord créer une application Microsoft Entra et créer un secret et utiliser ce secret dans votre code. Votre application doit être inscrite et configurée de manière appropriée pour effectuer des appels d’API à partir de Fabric. Pour plus d’informations, consultez Ajouter et gérer les informations d’identification d’application dans l’ID Microsoft Entra

Après avoir créé l’enregistrement de l’application, créez un secret client.

Lorsque vous créez le secret client, veillez à copier la valeur. Vous en avez besoin plus tard dans le code, et le secret ne peut pas être vu à nouveau. Vous aurez également besoin de l’ID d’application (client) et du répertoire (ID de locataire) en plus du secret dans votre code.
Ensuite, nous devons ajouter le client secret à notre espace de travail.
Recherchez la clé secrète client Entra et ajoutez ce secret à l’espace de travail, puis vérifiez que le secret nouvellement ajouté dispose des autorisations d’administrateur.

Comment autoriser les demandes d’API Livy avec un jeton d’application Entra

Pour utiliser des API Fabric, notamment l’API Livy, vous devez d’abord créer une application Microsoft Entra et obtenir un jeton. Votre application doit être inscrite et configurée de manière appropriée pour effectuer des appels d’API à partir de Fabric. Pour plus d’informations, consultez Inscrire une application auprès de la plateforme d’identités Microsoft.

De nombreuses autorisations d’étendue Microsoft Entra sont requises pour exécuter des travaux Livy. Cet exemple utilise du code Spark simple + accès au stockage + 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

Remarque

Pendant la préversion publique, ces étendues peuvent changer à mesure que nous ajoutons quelques étendues plus granulaires. Lorsque ces modifications d’étendue se produisent, votre application Livy peut s’interrompre. Vérifiez cette liste, car elle sera mise à jour avec les étendues supplémentaires.

Certains clients souhaitent des autorisations plus granulaires que dans la liste précédente. Vous pouvez supprimer Item.ReadWrite.All et remplacer par ces autorisations d’étendue plus granulaires :

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

Lorsque vous inscrivez votre application, vous aurez besoin de l’ID d’application (client) et de l’ID d’annuaire (locataire).

Capture d’écran montrant la vue d’ensemble de l’application API Livy dans le centre d’administration Microsoft Entra.

L’utilisateur authentifié appelant l’API Livy doit être membre de l’espace de travail où se trouvent à la fois l’API et les éléments de source de données avec un rôle Collaborateur. Pour plus d’informations, consultez Accorder aux utilisateurs l’accès aux espaces de travail.

Comment découvrir le point de terminaison de l’API Fabric Livy

Un artefact Lakehouse est requis pour accéder au point de terminaison Livy. Une fois le Lakehouse créé, le point de terminaison de l’API Livy peut se trouver dans le panneau des paramètres.

Le point de terminaison de l’API Livy suit ce modèle :

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

L’URL est ajoutée avec des <sessions> ou des <lots> en fonction de ce que vous choisissez.

Télécharger les fichiers Swagger de l’API Livy

Les fichiers swagger complets de l’API Livy sont disponibles ici.

Soumettre des travaux de l’API Livy

Maintenant que la configuration de l’API Livy est terminée, vous pouvez choisir d’envoyer des tâches de traitement par lots ou de session.

Intégration à des environnements Fabric

Par défaut, cette session d’API Livy s’exécute sur le pool de démarrage par défaut de l’espace de travail. Vous pouvez également utiliser les environnements Fabric Créer, configurer et utiliser un environnement dans Microsoft Fabric pour personnaliser le pool Spark utilisé par la session API Livy pour ces travaux Spark.

Pour utiliser un environnement Fabric dans une session Livy Spark, mettez simplement à jour le json pour inclure cette charge utile.

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

Pour utiliser un environnement Fabric dans une session batch Livy Spark, mettez simplement à jour la charge utile json, comme indiqué ci-dessous.

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

Comment surveiller l’historique des requêtes

Vous pouvez utiliser le hub de surveillance pour afficher vos soumissions précédentes de l’API Livy et déboguer les erreurs de soumission.