Freigeben über

Verwalten von Notizbuchartefakten mit NotebookUtils

Verwenden Sie notebookutils.notebook, um Notizbuchelemente in Microsoft Fabric programmgesteuert zu verwalten. Sie können Notizbuchartefakte erstellen, abrufen, aktualisieren, löschen und auflisten, um Bereitstellungs-, Lebenszyklusverwaltungs- und CI/CD-Workflows zu automatisieren.

Hinweis

Diese APIs werden nur in Fabric-Notizbüchern unterstützt, nicht in Azure Synapse. Sie müssen über entsprechende Berechtigungen im Zielarbeitsbereich für jeden Vorgang verfügen.

In der folgenden Tabelle sind die verfügbaren Notizbuchverwaltungsmethoden aufgeführt:

Methode Signature Beschreibung
create create(name, description, content, defaultLakehouse, defaultLakehouseWorkspace, workspaceId): Artifact Erstellt ein neues Notizbuch.
get get(name, workspaceId): Artifact Ruft ein Notizbuch anhand des Namens oder der ID ab.
getDefinition getDefinition(name, workspaceId, format): String Ruft die Notizbuchdefinition (Inhalt) ab.
update update(name, newName, description, workspaceId): Artifact Aktualisiert die Notizbuchmetadaten.
updateDefinition updateDefinition(name, content, defaultLakehouse, defaultLakehouseWorkspace, workspaceId, environmentId, environmentWorkspaceId): bool Aktualisiert die Notebook-Definition und das Lakehouse.
delete delete(name, workspaceId): Boolean Löscht ein Notebook
list list(workspaceId, maxResults): Array[Artifact] Listet alle Notizbücher in einem Arbeitsbereich auf.

Erstellen eines Notizbuchs

Verwenden Sie notebookutils.notebook.create(), um ein neues Notizbuch-Objekt im aktuellen Arbeitsbereich oder einem angegebenen Arbeitsbereich zu erstellen.

Hinweis

Workflowbeispiele in diesem Artikel, in denen Dateien gelesen oder geschrieben .ipynb werden, verwenden Python für Dateiein-/-ausgabe. Die Kern-APIs notebookutils.notebook sind in Python, PySpark, Scala und R verfügbar, sofern nicht anders angegeben.

Parameter

Parameter Typ Erforderlich Beschreibung
name String Ja Anzeigename für das neue Notizbuch. Muss innerhalb des Arbeitsbereichs eindeutig sein.
description String No Beschreibung des Notizbuchs. Standardmäßig leer.
content Zeichenfolge, Bytes oder Diktat Ja Notizbuchinhalt im gültigen .ipynb JSON-Format. Kann auch unformatierte Bytes oder ein Diktatobjekt sein. Darf nicht leer sein.
defaultLakehouse String No Name oder ID des Standard-Lakehouses, das angehängt werden soll.
defaultLakehouseWorkspace String No ID des Arbeitsbereichs des Standard-Lakehouse. Lassen Sie für den aktuellen Arbeitsbereich leer.
workspaceId String No Zielarbeitsbereichs-ID. Lassen Sie für den aktuellen Arbeitsbereich leer.

Von Bedeutung

Der content Parameter darf nicht leer sein. Sie müssen beim Erstellen eines Notizbuchs gültige .ipynb Formatinhalte bereitstellen. Stellen Sie mindestens eine gültige leere Notizbuchstruktur bereit:

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

Erstellen eines Notizbuchs aus einer Vorlage

# 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})")

Erstellen eines Notizbuchs mit einem Standardseehaus

# 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}")

Zurückgegebener Wert

Die create() Methode gibt ein Artifact Objekt mit den folgenden Eigenschaften zurück:

  • displayName: Der Anzeigename des Notizbuchs.
  • id: Der eindeutige Bezeichner des erstellten Notizbuchs.
  • description: Die Beschreibung des Notizbuchs.

Erstellen eines Notizbuchs in einem anderen Arbeitsbereich

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

Erstellen mehrerer Notizbücher aus einer Vorlage

# 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")

Tipp

Stellen Sie aussagekräftige Namen und Beschreibungen für Ihre Notizbücher bereit, damit sie leichter zu finden sind. Verwenden Sie eine konsistente Benennungskonvention wie z.B. <Project>_<Purpose>_<Region> für automatisierte Bereitstellungen.

Ein Notizbuch holen

Verwenden Sie notebookutils.notebook.get(), um Notizbuchmetadaten anhand des Namens oder der ID abzurufen. Es gibt ein Artifact Objekt mit Eigenschaften wie displayName, id und description.

Parameter

Parameter Typ Erforderlich Beschreibung
name String Ja Name oder ID des abzurufenden Notizbuchs.
workspaceId String No Arbeitsbereichs-ID. Lassen Sie für den aktuellen Arbeitsbereich leer.

Abrufen eines Notizbuchs aus dem aktuellen Arbeitsbereich

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

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

Abrufen eines Notizbuchs aus einem anderen Arbeitsbereich

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

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

Zurückgegebener Wert

Die get() Methode gibt ein Artifact Objekt mit den folgenden Eigenschaften zurück:

  • displayName: Der Anzeigename des Notizbuchs.
  • id: Der eindeutige Bezeichner.
  • description: Die Beschreibung des Notizbuchs.

Tipp

Verwenden Sie get() vor aktualisierungs- oder Löschvorgängen, um zu überprüfen, ob das Zielnotizbuch vorhanden ist. Sie können es auch verwenden, um zu überprüfen, ob ein Notizbuchname bereits verwendet wird, bevor Sie eine neue erstellen.

Abrufen einer Notizbuchdefinition

Verwenden Sie notebookutils.notebook.getDefinition(), um den vollständigen Notizbuchinhalt im .ipynb-Format abzurufen. Verwenden Sie sie für Sicherung, Migration, Versionssteuerung oder Inhaltsanalyse.

Parameter

Parameter Typ Erforderlich Beschreibung
name String Ja Name oder ID des Notizbuchs.
workspaceId String No Arbeitsbereichs-ID. Lassen Sie für den aktuellen Arbeitsbereich leer.
format String No Ausgabeformat. Wird standardmäßig auf "ipynb" festgelegt.

Abrufen und Speichern einer Notizbuchdefinition

# 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")

Abrufen einer Notizbuchdefinition aus einem anderen Arbeitsbereich

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

Zurückgegebener Wert

Die getDefinition() Methode gibt eine Zeichenfolge zurück, die den Notizbuchinhalt im .ipynb JSON-Format enthält.

Alle Notizbücher zur Sicherung exportieren

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()

Aktualisieren eines Notizbuchs

Verwenden Sie notebookutils.notebook.update(), um Notizbuchmetadaten wie den Anzeigenamen und die Beschreibung zu ändern. Es ändert keine Notizbuchinhalts- oder Lakehouse-Konfiguration.

Parameter

Parameter Typ Erforderlich Beschreibung
name String Ja Aktueller Name oder ID des Notizbuchs.
newName String Ja Neuer Anzeigename für das Notizbuch.
description String No Aktualisierte Beschreibung.
workspaceId String No Arbeitsbereichs-ID. Lassen Sie für den aktuellen Arbeitsbereich leer.

Umbenennen eines Notebooks

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

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

Zurückgegebener Wert

Die update() Methode gibt ein Artifact Objekt mit den aktualisierten Eigenschaften zurück.

Aktualisieren einer Notizbuchdefinition

Verwenden Sie notebookutils.notebook.updateDefinition(), um Notizbuchinhalte, das Standardlakehouse oder beides zu ändern. Verwenden Sie sie, wenn Sie die Notizbuchdefinition anstelle der Metadaten ändern müssen.

Parameter

Parameter Typ Erforderlich Beschreibung
name String Ja Name oder ID des zu aktualisierenden Notizbuchs.
content String No Neuer Notizbuchinhalt im .ipynb Format.
defaultLakehouse String No Neuer Standardseehausname.
defaultLakehouseWorkspace String No ID des neuen Standard-Lakehouses im Arbeitsbereich. Lassen Sie für den aktuellen Arbeitsbereich leer.
workspaceId String No Arbeitsbereichs-ID. Lassen Sie für den aktuellen Arbeitsbereich leer.
environmentId String No Umgebungs-ID, die an das Notizbuch angefügt werden soll.
environmentWorkspaceId String No Arbeitsbereichs-ID der Umgebung. Lassen Sie für den aktuellen Arbeitsbereich leer.

Hinweis

Die environmentId- und environmentWorkspaceId-Parameter sind nur in der Spark-Notebook-Laufzeit verfügbar. Python-Notizbücher unterstützen diese Parameter nicht.

Aktualisieren von Notizbuchinhalten

# 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}")

Standard-Lakehouse ändern

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

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

Inhalte und Lakehouse aktualisieren

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

Zurückgegebener Wert

Die updateDefinition() Methode gibt zurück True , ob das Update erfolgreich ist oder False ein Fehler auftritt.

Tipp

Verwenden Sie update() für Metadatenänderungen (Name, Beschreibung) und updateDefinition() für Änderungen im Inhalt und am Lakehouse. Wenn Sie eine vollständige Aktualisierung von Metadaten und Inhalten benötigen, rufen Sie beide Methoden in Sequenz auf.

Löschen eines Notebooks

Verwenden Sie notebookutils.notebook.delete(), um ein Notizbuch dauerhaft aus einem Arbeitsbereich zu entfernen. Es wird zurückgegeben True , wenn der Löschvorgang erfolgreich ist; andernfalls wird er zurückgegeben False.

Parameter

Parameter Typ Erforderlich Beschreibung
name String Ja Name oder ID des zu löschenden Notizbuchs.
workspaceId String No Arbeitsbereichs-ID. Lassen Sie für den aktuellen Arbeitsbereich leer.

Von Bedeutung

Das Löschen ist dauerhaft. Gelöschte Notizbücher können nicht wiederhergestellt werden. Überprüfen Sie immer den Namen des Notizbuchs, bevor Sie es löschen, und erwägen Sie, zuerst die Notizbuchdefinition mit getDefinition() zu sichern.

Zurückgegebener Wert

Die delete() Methode gibt zurück True , ob der Löschvorgang erfolgreich ist oder False ein Fehler auftritt.

Löschen eines Notebooks

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

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

Sicheres Bereinigen von Notizbüchern nach Mustern

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)

Tipp

Führen Sie für ein sicheres Löschen in großen Mengen immer zuerst dry_run=True aus, um eine Vorschau der zu entfernenden Notizbücher anzuzeigen. Erwägen Sie, Notizbücher mit einem _TO_DELETE Präfix umzubenennen, anstatt sie sofort zu löschen, damit Sie sie bei Bedarf wiederherstellen können.

Notizbücher auflisten

Dient notebookutils.notebook.list() zum Aufzählen von Notizbüchern in einem Arbeitsbereich. Es gibt ein Array von Artifact Objekten zurück.

Parameter

Parameter Typ Erforderlich Beschreibung
workspaceId String No Arbeitsbereichs-ID. Lassen Sie für den aktuellen Arbeitsbereich leer.
maxResults Int No Maximale Anzahl der zurückzugebenden Ergebnisse. Standardmäßig steht es auf 1000.

Auflisten aller Notizbücher im aktuellen Arbeitsbereich

notebooks = notebookutils.notebook.list()

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

Notizbücher in einem anderen Arbeitsbereich auflisten

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

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

Zurückgegebener Wert

Die list() Methode gibt ein Array von Artifact Objekten zurück. Jedes Objekt enthält displayName, idund description Eigenschaften.

Filtern von Notizbüchern nach Namensmustern

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

Klonen eines Notizbuchs

Verwenden Sie list() und getDefinition() zusammen, um ein Notizbuch innerhalb des gleichen oder eines anderen Arbeitsbereichs zu klonen.

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")

Migrieren eines Notizbuchs zu einem anderen Arbeitsbereich

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")

Verwandte Inhalte

  • Last updated on