Partager via

Gérer les artefacts des notebooks avec NotebookUtils

Utilisez notebookutils.notebook pour gérer les éléments de notebook de manière programmatique dans Microsoft Fabric. Vous pouvez créer, récupérer, mettre à jour, supprimer et répertorier des artefacts de notebook pour automatiser le déploiement, la gestion du cycle de vie et les flux de travail CI/CD.

Note

Ces API sont prises en charge uniquement dans les notebooks Fabric, et non dans Azure Synapse. Vous devez disposer des autorisations appropriées dans l’espace de travail cible pour chaque opération.

Le tableau suivant répertorie les méthodes de gestion de notebook disponibles :

Méthode Signature Description
create create(name, description, content, defaultLakehouse, defaultLakehouseWorkspace, workspaceId): Artifact Crée un bloc-notes.
get get(name, workspaceId): Artifact Récupère un bloc-notes par nom ou identifiant.
getDefinition getDefinition(name, workspaceId, format): String Récupère la définition du bloc-notes (contenu).
update update(name, newName, description, workspaceId): Artifact Met à jour les métadonnées du bloc-notes.
updateDefinition updateDefinition(name, content, defaultLakehouse, defaultLakehouseWorkspace, workspaceId, environmentId, environmentWorkspaceId): bool Met à jour la définition du notebook ainsi que celle du lakehouse.
delete delete(name, workspaceId): Boolean Supprime un carnet.
list list(workspaceId, maxResults): Array[Artifact] Répertorie tous les blocs-notes d’un espace de travail.

Créer un carnet de notes

Utilisez notebookutils.notebook.create() pour créer un élément de notebook dans l’espace de travail actuel ou dans un espace de travail spécifié.

Note

Exemples de workflows dans cet article qui lisent ou écrivent des fichiers .ipynb utilisent Python pour les entrées/sorties de fichiers. Les API principales notebookutils.notebook sont disponibles dans Python, PySpark, Scala et R, sauf indication contraire.

Paramètres

Paramètre Catégorie Obligatoire Description
name Chaîne Oui Nom d'affichage du nouveau bloc-notes. Doit être unique dans l’espace de travail.
description Chaîne Non Description du bloc-notes. La valeur par défaut est vide.
content Chaîne, octets ou dictionnaire Oui Contenu du bloc-notes au format JSON valide .ipynb . Il peut également s’agir d’octets bruts ou d’un objet dicté. Impossible d’être vide.
defaultLakehouse Chaîne Non Nom ou ID de la lakehouse par défaut à attacher.
defaultLakehouseWorkspace Chaîne Non ID d’espace de travail de la lakehouse par défaut. Laissez vide pour l’espace de travail actuel.
workspaceId Chaîne Non ID de l’espace de travail cible. Laissez ce champ vide pour l'espace de travail actuel.

Important

Le content paramètre ne peut pas être vide. Vous devez fournir du contenu de format valide .ipynb lorsque vous créez un bloc-notes. Au minimum, fournissez une structure de notebook vide valide :

{
  "cells": [],
  "metadata": {},
  "nbformat": 4,
  "nbformat_minor": 5
}

Créer un bloc-notes à partir d’un modèle

# Read notebook template from a file
with open("/path/to/template.ipynb", "r") as f:
    notebook_content = f.read()

# Create the notebook
notebook = notebookutils.notebook.create(
    name="ProcessingNotebook",
    description="Data processing notebook from template",
    content=notebook_content
)

print(f"Created notebook: {notebook.displayName} (ID: {notebook.id})")

Créer un notebook avec un lakehouse par défaut

# Minimum valid notebook content - content cannot be empty
minimal_content = '''{
    "cells": [],
    "metadata": {},
    "nbformat": 4,
    "nbformat_minor": 5
}'''

# Create notebook with default lakehouse configuration
notebook = notebookutils.notebook.create(
    name="DataAnalysis",
    description="Analysis notebook with lakehouse access",
    content=minimal_content,
    defaultLakehouse="MyLakehouse",
    defaultLakehouseWorkspace=""  # Current workspace
)

print(f"Created notebook with lakehouse: {notebook.displayName}")

Valeur renvoyée

La create() méthode retourne un Artifact objet avec les propriétés suivantes :

  • displayName: nom d'affichage du bloc-notes.
  • id: identificateur unique du bloc-notes créé.
  • description: description du bloc-notes.

Créer un bloc-notes dans un autre espace de travail

with open("/path/to/notebook.ipynb", "r") as f:
    content = f.read()

notebook = notebookutils.notebook.create(
    name="SharedNotebook",
    description="Notebook for the shared workspace",
    content=content,
    workspaceId="bbbbbbbb-2222-3333-4444-cccccccccccc"
)

print(f"Created in remote workspace: {notebook.displayName}")

Créer plusieurs notebooks à partir d’un modèle

# Load template content (must be valid .ipynb)
with open("/path/to/template.ipynb", "r") as f:
    template_content = f.read()

regions = ["US", "EU", "Asia"]

created_notebooks = []
for region in regions:
    notebook = notebookutils.notebook.create(
        name=f"Process_{region}",
        description=f"Processing notebook for {region} region",
        content=template_content,
        defaultLakehouse=f"Lakehouse_{region}"
    )
    created_notebooks.append(notebook)
    print(f"Created: {notebook.displayName}")

print(f"\nCreated {len(created_notebooks)} notebooks")

Conseil / Astuce

Fournissez des noms et des descriptions explicites pour vos blocs-notes afin de faciliter leur recherche. Utilisez une convention d’affectation de noms cohérente, comme <Project>_<Purpose>_<Region> pour les déploiements automatisés.

Obtenir un bloc-notes

Permet notebookutils.notebook.get() de récupérer les métadonnées de bloc-notes par nom ou ID. Elle retourne un Artifact objet avec des propriétés telles que displayName, idet description.

Paramètres

Paramètre Catégorie Obligatoire Description
name Chaîne Oui Nom ou ID du bloc-notes à récupérer.
workspaceId Chaîne Non ID de l’espace de travail. Laisser vide pour l’espace de travail actuel.

Obtenir un bloc-notes à partir de l’espace de travail actuel

notebook = notebookutils.notebook.get("MyNotebook")

print(f"Notebook Name: {notebook.displayName}")
print(f"Notebook ID: {notebook.id}")
print(f"Description: {notebook.description}")

Obtenir un bloc-notes à partir d’un autre espace de travail

workspace_id = "bbbbbbbb-2222-3333-4444-cccccccccccc"
notebook = notebookutils.notebook.get("SharedNotebook", workspaceId=workspace_id)

print(f"Retrieved: {notebook.displayName} from workspace {workspace_id}")

Valeur renvoyée

La get() méthode retourne un Artifact objet avec les propriétés suivantes :

  • displayName: nom d'affichage du bloc-notes.
  • id: identificateur unique.
  • description: description du bloc-notes.

Conseil / Astuce

Utilisez get() avant les opérations de mise à jour ou de suppression pour vérifier que le notebook cible existe. Vous pouvez également l’utiliser pour vérifier si un nom de bloc-notes est déjà utilisé avant de en créer un nouveau.

Obtenez une définition de cahier

Utilisez notebookutils.notebook.getDefinition() pour récupérer le contenu complet du bloc-notes en format .ipynb. Utilisez-le pour la sauvegarde, la migration, le contrôle de version ou l’analyse du contenu.

Paramètres

Paramètre Catégorie Obligatoire Description
name Chaîne Oui Nom ou ID du bloc-notes.
workspaceId Chaîne Non ID de l’espace de travail. Laisser vide pour l’espace de travail actuel.
format Chaîne Non Format de sortie. La valeur par défaut est "ipynb".

Récupérer et enregistrer une définition de bloc-notes

# Retrieve notebook definition as .ipynb content
notebook_content = notebookutils.notebook.getDefinition("MyNotebook")

# Save to a file for backup
with open("/path/to/backup/MyNotebook.ipynb", "w") as f:
    f.write(notebook_content)

print("Notebook definition retrieved and saved")

Obtenir une définition de notebook à partir d’un autre espace de travail

workspace_id = "cccccccc-3333-4444-5555-dddddddddddd"
notebook_content = notebookutils.notebook.getDefinition(
    name="SharedNotebook",
    workspaceId=workspace_id,
    format="ipynb"
)

print(f"Retrieved definition from workspace {workspace_id}")

Valeur renvoyée

La getDefinition() méthode retourne une chaîne contenant le contenu du bloc-notes au .ipynb format JSON.

Exporter tous les notebooks pour la sauvegarde

import os
from datetime import datetime

def export_all_notebooks(backup_dir="/path/to/backups"):
    """Export all notebooks in the workspace for backup."""

    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
    export_dir = f"{backup_dir}/backup_{timestamp}"
    os.makedirs(export_dir, exist_ok=True)

    notebooks = notebookutils.notebook.list()
    print(f"Exporting {len(notebooks)} notebooks to {export_dir}")

    exported_count = 0
    for nb in notebooks:
        try:
            content = notebookutils.notebook.getDefinition(nb.displayName)
            filename = f"{export_dir}/{nb.displayName}.ipynb"
            with open(filename, "w") as f:
                f.write(content)
            exported_count += 1
            print(f"Exported: {nb.displayName}")
        except Exception as e:
            print(f"Failed to export {nb.displayName}: {e}")

    print(f"\nExported {exported_count} of {len(notebooks)} notebooks")
    return export_dir

backup_location = export_all_notebooks()

Mettre à jour un notebook

Permet notebookutils.notebook.update() de modifier les métadonnées du bloc-notes, telles que son nom d’affichage et sa description. Il ne modifie pas le contenu du bloc-notes ou la configuration lakehouse.

Paramètres

Paramètre Catégorie Obligatoire Description
name Chaîne Oui Nom ou ID actuel du bloc-notes.
newName Chaîne Oui Nouveau nom d'affichage pour le cahier.
description Chaîne Non Description mise à jour.
workspaceId Chaîne Non ID de l’espace de travail. Laisser vide pour l’espace de travail actuel.

Renommer un notebook

updated_notebook = notebookutils.notebook.update(
    name="OldNotebookName",
    newName="NewNotebookName",
    description="Updated description with more details"
)

print(f"Updated notebook: {updated_notebook.displayName}")

Valeur renvoyée

La update() méthode retourne un Artifact objet avec les propriétés mises à jour.

Mettre à jour une définition de carnet

Utilisez notebookutils.notebook.updateDefinition() pour modifier le contenu du bloc-notes, le « lakehouse » par défaut, ou les deux. Utilisez-le lorsque vous devez modifier la définition du bloc-notes plutôt que ses métadonnées.

Paramètres

Paramètre Catégorie Obligatoire Description
name Chaîne Oui Nom ou ID du bloc-notes à mettre à jour.
content Chaîne Non Nouveau contenu de bloc-notes au .ipynb format.
defaultLakehouse Chaîne Non Nouveau nom lakehouse par défaut.
defaultLakehouseWorkspace Chaîne Non ID d’espace de travail du nouveau lakehouse par défaut. Laisser vide pour l’espace de travail actuel.
workspaceId Chaîne Non ID de l’espace de travail. Laisser vide pour l’espace de travail actuel.
environmentId Chaîne Non ID d’environnement à attacher au carnet.
environmentWorkspaceId Chaîne Non ID de l’espace de travail de l’environnement. Laisser vide pour l’espace de travail actuel.

Note

Les paramètres environmentId et environmentWorkspaceId sont disponibles uniquement dans le runtime du notebook Spark. Les notebooks Python ne prennent pas en charge ces paramètres.

Mettre à jour le contenu du bloc-notes

# Load new content
with open("/path/to/updated_notebook.ipynb", "r") as f:
    new_content = f.read()

is_updated = notebookutils.notebook.updateDefinition(
    name="MyNotebook",
    content=new_content
)

print(f"Notebook definition updated: {is_updated}")

Modifier la lakehouse par défaut

is_updated = notebookutils.notebook.updateDefinition(
    name="MyNotebook",
    defaultLakehouse="NewLakehouse",
    defaultLakehouseWorkspace=""  # Current workspace
)

print(f"Default lakehouse updated: {is_updated}")

Mettre à jour le contenu et le lakehouse

with open("/path/to/new_version.ipynb", "r") as f:
    new_content = f.read()

is_updated = notebookutils.notebook.updateDefinition(
    name="MyNotebook",
    content=new_content,
    defaultLakehouse="ProductionLakehouse",
    defaultLakehouseWorkspace=""
)

print(f"Notebook fully updated: {is_updated}")

Valeur renvoyée

La updateDefinition() méthode retourne True si la mise à jour réussit ou False si elle échoue.

Conseil / Astuce

Utiliser update() pour les modifications de métadonnées (nom, description) et updateDefinition() pour les modifications de contenu et de lakehouse. Lorsque vous avez besoin d’une actualisation complète des métadonnées et du contenu, appelez les deux méthodes dans la séquence.

Supprimer un bloc-notes

Permet notebookutils.notebook.delete() de supprimer définitivement un bloc-notes d’un espace de travail. Elle retourne True si la suppression réussit ; sinon, elle retourne False.

Paramètres

Paramètre Catégorie Obligatoire Description
name Chaîne Oui Nom ou ID du bloc-notes à supprimer.
workspaceId Chaîne Non ID de l’espace de travail. Laisser vide pour l’espace de travail actuel.

Important

La suppression est permanente. Les blocs-notes supprimés ne peuvent pas être récupérés. Vérifiez toujours le nom du bloc-notes avant de le supprimer, et envisagez de sauvegarder d'abord sa définition avec getDefinition().

Valeur renvoyée

La delete() méthode retourne True si la suppression réussit ou False si elle échoue.

Supprimer un bloc-notes

is_deleted = notebookutils.notebook.delete("ObsoleteNotebook")

if is_deleted:
    print("Notebook deleted successfully")
else:
    print("Failed to delete notebook")

Nettoyer en toute sécurité les blocs-notes par modèle

def cleanup_notebooks(name_pattern, dry_run=True):
    """Delete notebooks matching a name pattern."""

    notebooks = notebookutils.notebook.list()
    to_delete = [nb for nb in notebooks if name_pattern in nb.displayName]

    print(f"Found {len(to_delete)} notebooks matching '{name_pattern}':")
    for nb in to_delete:
        print(f"  - {nb.displayName}")

    if dry_run:
        print("\nDRY RUN - No notebooks deleted")
        return

    deleted_count = 0
    for nb in to_delete:
        if notebookutils.notebook.delete(nb.displayName):
            deleted_count += 1
            print(f"Deleted: {nb.displayName}")
        else:
            print(f"Failed to delete: {nb.displayName}")

    print(f"\nDeleted {deleted_count} of {len(to_delete)} notebooks")

# Always run with dry_run=True first to preview
cleanup_notebooks("temp_", dry_run=True)

Conseil / Astuce

Pour une suppression en bloc sécurisée, exécutez toujours avec dry_run=True d’abord pour afficher un aperçu des blocs-notes qui seront supprimés. Envisagez de renommer des blocs-notes avec un _TO_DELETE préfixe au lieu de les supprimer immédiatement. Vous pouvez donc les récupérer si nécessaire.

Répertorier les blocs-notes

Permet notebookutils.notebook.list() d’énumérer des blocs-notes dans un espace de travail. Elle retourne un tableau d’objets Artifact .

Paramètres

Paramètre Catégorie Obligatoire Description
workspaceId Chaîne Non ID de l’espace de travail. Laisser vide pour l’espace de travail actuel.
maxResults int Non Nombre maximal de résultats à renvoyer. Par défaut, la valeur est 1000.

Répertorier tous les blocs-notes dans l’espace de travail actif

notebooks = notebookutils.notebook.list()

print(f"Found {len(notebooks)} notebooks:")
for nb in notebooks:
    print(f"  - {nb.displayName} (ID: {nb.id})")

Répertorier les blocs-notes dans un autre espace de travail

workspace_id = "cccccccc-3333-4444-5555-dddddddddddd"
notebooks = notebookutils.notebook.list(workspaceId=workspace_id)

print(f"Found {len(notebooks)} notebooks in workspace {workspace_id}")

Valeur renvoyée

La list() méthode retourne un tableau d’objets Artifact . Chaque objet contient displayName, idet description les propriétés.

Filtrer les notebooks par motif de nom

all_notebooks = notebookutils.notebook.list()

# Filter for notebooks that start with a specific prefix
processing_notebooks = [nb for nb in all_notebooks if nb.displayName.startswith("Process_")]

print(f"Found {len(processing_notebooks)} processing notebooks:")
for nb in processing_notebooks:
    print(f"  - {nb.displayName}")

Cloner un notebook

Utilisez list() et getDefinition() ensemble pour cloner un notebook dans le même espace de travail ou un autre.

def clone_notebook(source_name, target_name, target_workspace=""):
    """Clone a notebook by retrieving its content and creating a copy."""

    source = notebookutils.notebook.get(source_name)
    content = notebookutils.notebook.getDefinition(source_name)

    cloned = notebookutils.notebook.create(
        name=target_name,
        description=f"Clone of {source_name}",
        content=content,
        workspaceId=target_workspace
    )

    print(f"Cloned {source_name} to {cloned.displayName}")
    return cloned

cloned_notebook = clone_notebook("TemplateNotebook", "NewInstance")

Migrer un bloc-notes vers un autre espace de travail

def migrate_notebook(name, target_workspace_id, new_name=None):
    """Migrate a notebook from the current workspace to another workspace."""

    content = notebookutils.notebook.getDefinition(name)
    target_name = new_name if new_name else name

    migrated = notebookutils.notebook.create(
        name=target_name,
        description=f"Migrated from {name}",
        content=content,
        workspaceId=target_workspace_id
    )

    print(f"Migrated {name} to workspace {target_workspace_id} as {target_name}")
    return migrated

target_ws = "dddddddd-4444-5555-6666-eeeeeeeeeeee"
migrated_nb = migrate_notebook("DataPipeline", target_ws, "DataPipeline_v2")

Contenu connexe

  • Last updated on