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

  • Article

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.

Important

Cette fonctionnalité est en version préliminaire.

Remarque

L’authentification du principal de service est disponible pour l’API CURD Notebook. Il n’est pas pris en charge pour l’exécution de l’API notebook pour le moment.

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.

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

Action Description
Créer un élément Crée un notebook à 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 notebook.
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 notebook.
É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écuter le notebook avec le paramétrage.
Annuler l’instance de tâche d’élément Annuler l’exécution de la tâche du notebook.
Obtenir l’instance de la tâche d’élément Obtenir l’état de l’exécution du notebook.

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

Exemples d’utilisation de l’API REST du notebook

Utilisez les instructions suivantes pour tester des exemples d’utilisation pour des API publiques de notebook spécifiques et vérifier leurs résultats.

Remarque

Ces scénarios couvrent uniquement les exemples d’utilisation uniques des notebooks. Les exemples d’API courantes des éléments de structure ne sont pas abordés ici.

Prérequis

L’API Rest Fabric définit un point de terminaison unifié pour les opérations. Remplacez les valeurs temporaires {WORKSPACE_ID} et {ARTIFACT_ID} par les valeurs appropriées lorsque vous suivez les exemples de cet article.

Créer un notebook avec une définition

Créez un élément de notebook avec un fichier .ipynb existant :

Requête

POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/items

{
    "displayName":"Notebook1",
    "type":"Notebook",
    "definition" : {
        "format": "ipynb",
        "parts": [
            {
                "path": "artifact.content.ipynb",
                "payload": "eyJuYmZvcm1hdCI6NCwibmJmb3JtYXRfbWlub3IiOjUsImNlbGxzIjpbeyJjZWxsX3R5cGUiOiJjb2RlIiwic291cmNlIjpbIiMgV2VsY29tZSB0byB5b3VyIG5ldyBub3RlYm9va1xuIyBUeXBlIGhlcmUgaW4gdGhlIGNlbGwgZWRpdG9yIHRvIGFkZCBjb2RlIVxuIl0sImV4ZWN1dGlvbl9jb3VudCI6bnVsbCwib3V0cHV0cyI6W10sIm1ldGFkYXRhIjp7fX1dLCJtZXRhZGF0YSI6eyJsYW5ndWFnZV9pbmZvIjp7Im5hbWUiOiJweXRob24ifX19",
                "payloadType": "InlineBase64"
            }
        ]
    }
}

La charge utile dans la requête est une chaîne base64 convertie à partir de l’exemple de notebook suivant.

{
    "nbformat": 4,
    "nbformat_minor": 5,
    "cells": [
        {
            "cell_type": "code",
            "source": [
                "# Welcome to your new notebook\n# Type here in the cell editor to add code!\n"
            ],
            "execution_count": null,
            "outputs": [],
            "metadata": {}
        }
    ],
    "metadata": {
        "language_info": {
            "name": "python"
        },
        "dependencies": {
            "environment": {
                "environmentId": "6524967a-18dc-44ae-86d1-0ec903e7ca05",
                "workspaceId": "c31eddd2-26e6-4aa3-9abb-c223d3017004"
            },
            "lakehouse": {
                "default_lakehouse": "5b7cb89a-81fa-4d8f-87c9-3c5b30083bee",
                "default_lakehouse_name": "lakehouse_name",
                "default_lakehouse_workspace_id": "c31eddd2-26e6-4aa3-9abb-c223d3017004"
            }
        }
    }
}

Remarque

Vous pouvez modifier le notebook par défaut lakehouse ou l’environnement attaché en modifiant le contenu metadata.trident.lakehouse ou metadata.trident.environment du notebook.

Obtenir un notebook avec une définition

Utilisez l’API suivante pour obtenir le contenu du notebook. Fabric prend en charge la définition du format .ipynb dans la chaîne de requête pour obtenir un notebook .ipynb.

Requête

POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/items/{{ARTIFACT_ID}}/GetDefinition?format=ipynb

Response

Code d’état : 200

{
    "definition": {
        "parts": [
            {
                "path": "notebook-content.ipynb",
                "payload": "eyJuYmZvcm1hdCI6NCwibmJmb3JtYXRfbWlub3IiOjUsImNlbGxzIjpbeyJjZWxsX3R5cGUiOiJjb2RlIiwic291cmNlIjpbIiMgV2VsY29tZSB0byB5b3VyIG5ldyBub3RlYm9va1xuIyBUeXBlIGhlcmUgaW4gdGhlIGNlbGwgZWRpdG9yIHRvIGFkZCBjb2RlIVxuIl0sImV4ZWN1dGlvbl9jb3VudCI6bnVsbCwib3V0cHV0cyI6W10sIm1ldGFkYXRhIjp7fX1dLCJtZXRhZGF0YSI6eyJsYW5ndWFnZV9pbmZvIjp7Im5hbWUiOiJweXRob24ifX19",
                "payloadType": "InlineBase64"
            }
        ]
    }
}

Exécuter un notebook à la demande

Planifiez l’exécution de votre notebook avec l’API suivante. La tâche Spark commence à s’exécuter après une demande réussie.

Fabric prend en charge la transmission parameters dans le corps de la demande pour paramétrer l’exécution du notebook. Les valeurs sont consommées par la cellule de paramètre de notebook.

Vous pouvez également utiliser configuration pour personnaliser la session Spark d’exécution du notebook. configuration partage le même contrat avec la commande magic de configuration de session Spark.

Requête

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

{
    "executionData": {
        "parameters": {
            "parameterName": {
                "value": "new value",
                "type": "string"
            }
        },
        "configuration": {
            "conf": {
                "spark.conf1": "value"
            },
            "environment": {
                "id": "<environment_id>",
                "name": "<environment_name>"
            },
            "defaultLakehouse": {
                "name": "<lakehouse-name>",
                "id": "<lakehouse-id>",
                "workspaceId": "<(optional) workspace-id-that-contains-the-lakehouse>"
            },
            "useStarterPool": false,
            "useWorkspacePool": "<workspace-pool-name>"
        }
    }
}

Response

Code d’état : 202

Location: https://api.fabric.microsoft.com/v1/workspaces/4b218778-e7a5-4d73-8187-f10824047715/items/431e8d7b-4a95-4c02-8ccd-6faef5ba1bd7/jobs/instances/f2d65699-dd22-4889-980c-15226deb0e1b
Retry-After: 60

Avec location, vous pouvez utiliser Obtenir l’instance de tâche d’élément pour afficher l’état de la tâche ou annuler l’instance de tâche d’élément pour annuler l’exécution en cours du notebook.

Contenu connexe