Gérer et exécuter des notebooks dans Fabric avec des API

L’API REST Microsoft Fabric fournit un point de terminaison de service pour les opérations de création, de lecture, de mise à jour et de suppression d’un élément Fabric. Cet article décrit les API REST de notebook disponibles et leur utilisation.

Avec les API de notebook, les ingénieurs de données et les scientifiques des données peuvent automatiser leurs propres pipelines et établir efficacement CI/CD. Ces API facilitent également la gestion et la manipulation des éléments de notebook Fabric par les utilisateurs, et l’intégration de notebooks à d’autres outils et systèmes. Les API permettent d'orchestrer les notebooks à partir de pipelines Fabric et d'ordonnanceurs externes, permettant une intégration fluide avec des flux de travail automatisés.

Ces actions de gestion des éléments sont disponibles pour les notebooks :

Action Description
Créer un élément Crée un bloc-notes à l’intérieur d’un espace de travail.
Update item (Mettre à jour un élément) Met à jour les métadonnées d’un notebook.
Mettre à jour la définition d’élément Met à jour le contenu d’un notebook.
Supprimer l’élément Supprime un carnet.
Obtenir un élément Obtient les métadonnées d’un notebook.
Obtenir la définition d’un élément Obtient le contenu d'un bloc-notes.
Élément de liste Répertorie tous les éléments d’un espace de travail.

Pour plus d’informations, consultez Éléments - API REST.

Les actions de planificateur de tâches suivantes sont disponibles pour les notebooks :

Action Description
Exécuter la tâche d’élément à la demande Exécutez un notebook à la demande avec prise en charge de la paramétrisation, de la configuration de la session (comme les paramètres Spark/compute), de la sélection de l'environnement, du runtime, et du choix du Fabric Lakehouse cible.
Annuler l’instance de tâche d’objet Annulez l’exécution d’un travail de bloc-notes.
Obtenir l’instance de la tâche d’élément Obtenez l’état de l’exécution du bloc-notes et récupérez la valeur de sortie retournée par l’exécution.

Pour plus d’informations, consultez Planificateur de tâches.

Remarque

L’authentification du principal de service est prise en charge pour l’API REST Items (opérations CRUD de notebook) et l’API du planificateur de travaux (exécution, surveillance et annulation). Cela permet d’automatiser sans assistance et de sécuriser les scénarios CI/CD. Ajoutez le principal de service dans l’espace de travail avec un rôle approprié (Administrateur, Membre ou Contributeur) pour gérer et exécuter des carnets.

Valeurs de sortie des exécutions de notebook

Les exécutions de notebooks exécutées via l’API Job Scheduler peuvent retourner une valeur de sortie que vous pouvez utiliser pour l’orchestration conditionnelle. La valeur de sortie apparaît dans le exitValue champ de la charge utile de réponse de l’instance de travail Get Item .

Un notebook peut définir sa valeur de sortie en appelant mssparkutils.notebook.exit("your-value") avant la fin de l’exécution. La valeur de sortie est une chaîne et peut encoder n’importe quel signal de résultat, par exemple, "success"ou "no_rows_processed"un résultat sérialisé JSON.

Les orchestrateurs externes, les pipelines Fabric et d’autres outils d’automatisation peuvent appeler l’instance de tâche Get Item une fois l’exécution terminée pour lire la valeur de sortie et prendre des décisions basées sur les résultats. Par exemple:

  1. Soumettez un travail d’élément sur demande avec des paramètres et des réglages d’exécution.
  2. Interroger l’instance de travail Get Item jusqu’à ce qu’elle status soit Completed (ou Failed).
  3. Lisez la réponse de exitValue afin de déterminer l’étape suivante de votre flux de travail.

Ce modèle permet l’orchestration conditionnelle et la signalisation en aval en fonction des résultats d’exécution du notebook.

Exemple de bout en bout

L’exemple suivant montre comment envoyer un bloc-notes et récupérer son état et sa valeur de sortie. Pour obtenir le schéma complet du corps de la requête, y compris les paramètres, la configuration de session et les champs de sélection Lakehouse, consultez la référence de l'API Tâche à la demande du Planificateur de Tâches.

Étape 1 : Envoyer une exécution

Utilisez le point de terminaison Run on demand Item Job pour démarrer une exécution de notebook :

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{notebookId}/jobs/instances?jobType=RunNotebook

La réponse retourne 202 Accepted avec un Location en-tête contenant l’URL de l’instance de travail que vous utilisez pour surveiller l’exécution.

Étape 2 : Récupérer l’état d’exécution et la valeur de sortie

Utilisez l’URL de l’en-tête Location pour vérifier l’état et lire la valeur de sortie une fois l’exécution terminée :

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{notebookId}/jobs/instances/{jobInstanceId}

Exemple de réponse (abrégé) :

{
  "id": "<jobInstanceId>",
  "itemId": "<notebookId>",
  "jobType": "RunNotebook",
  "invokeType": "OnDemand",
  "status": "Completed",
  "startTimeUtc": "2026-03-01T10:00:00Z",
  "endTimeUtc": "2026-03-01T10:05:00Z",
  "failureReason": null,
  "exitValue": "success"
}

Lisez exitValue pour déterminer le résultat et orientez votre logique d’automatisation en conséquence.

  • Last updated on