Condividi tramite

Gestire gli artefatti del notebook con NotebookUtils

Usare notebookutils.notebook per gestire gli elementi del notebook a livello di codice in Microsoft Fabric. È possibile creare, recuperare, aggiornare, eliminare ed elencare gli artefatti del notebook per automatizzare la distribuzione, la gestione del ciclo di vita e i flussi di lavoro CI/CD.

Annotazioni

Queste API sono supportate solo nei notebook di Fabric, non in Azure Synapse. È necessario disporre delle autorizzazioni appropriate nell'area di lavoro di destinazione per ogni operazione.

La tabella seguente elenca i metodi di gestione dei notebook disponibili:

metodo Firma Descrizione
create create(name, description, content, defaultLakehouse, defaultLakehouseWorkspace, workspaceId): Artifact Crea un nuovo notebook.
get get(name, workspaceId): Artifact Recupera un notebook in base al nome o all'ID.
getDefinition getDefinition(name, workspaceId, format): String Recupera la definizione del taccuino (contenuto).
update update(name, newName, description, workspaceId): Artifact Aggiorna i metadati del notebook.
updateDefinition updateDefinition(name, content, defaultLakehouse, defaultLakehouseWorkspace, workspaceId, environmentId, environmentWorkspaceId): bool Aggiorna la definizione del notebook e del lakehouse.
delete delete(name, workspaceId): Boolean Elimina un quaderno.
list list(workspaceId, maxResults): Array[Artifact] Elenca tutti i notebook in un'area di lavoro.

Crea un notebook

Usare notebookutils.notebook.create() per creare un nuovo elemento notebook nell'area di lavoro corrente o in un'area di lavoro specificata.

Annotazioni

Gli esempi di workflow in questo articolo che leggono o scrivono file .ipynb utilizzano Python per l'I/O dei file. Le API principali notebookutils.notebook sono disponibili in Python, PySpark, Scala e R, se non diversamente specificato.

Parametri

Parametro Tipo Obbligatorio Descrizione
name String Sì Nome visualizzato per il nuovo notebook. Deve essere univoco all'interno dell'area di lavoro.
description String No Descrizione del notebook. Di default è vuoto.
content Stringa, byte o dict Sì Contenuto del notebook in formato valido JSON .ipynb. Può anche essere byte non elaborati o un oggetto dict. Non può essere vuoto.
defaultLakehouse String No Nome o ID del lakehouse predefinito da collegare.
defaultLakehouseWorkspace String No ID area di lavoro del lakehouse predefinito. Lasciare vuoto l'area di lavoro corrente.
workspaceId String No ID area di lavoro di destinazione. Lasciare vuoto l'area di lavoro corrente.

Importante

Il content parametro non può essere vuoto. Quando si crea un notebook, è necessario fornire contenuto di formato valido .ipynb . Specificare almeno una struttura di notebook vuota valida:

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

Creare un notebook da un modello

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

Creare un notebook con un lakehouse preconfigurato

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

Valore restituito

Il create() metodo restituisce un Artifact oggetto con le proprietà seguenti:

  • displayName: nome visualizzato del notebook.
  • id: identificatore univoco del notebook creato.
  • description: descrizione del notebook.

Creare un notebook in un'altra area di lavoro

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

Creare più notebook da un modello

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

Suggerimento

Fornire nomi e descrizioni significativi per i notebook per semplificarne la ricerca. Utilizzare una convenzione di denominazione coerente come <Project>_<Purpose>_<Region> per le distribuzioni automatizzate.

Ottenere un notebook

Usare notebookutils.notebook.get() per recuperare i metadati del notebook in base al nome o all'ID. Restituisce un Artifact oggetto con proprietà come displayName, ide description.

Parametri

Parametro Tipo Obbligatorio Descrizione
name String Sì Nome o ID del notebook da recuperare.
workspaceId String No ID area di lavoro. Lasciare vuoto l'area di lavoro corrente.

Prendere il notebook dall'area di lavoro attuale

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

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

Prendere un notebook da un'altra area di lavoro

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

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

Valore restituito

Il get() metodo restituisce un Artifact oggetto con le proprietà seguenti:

  • displayName: nome visualizzato del notebook.
  • id: identificatore univoco.
  • description: descrizione del notebook.

Suggerimento

Usare get() prima delle operazioni di aggiornamento o eliminazione per verificare che il notebook di destinazione esista. È anche possibile usarlo per verificare se un nome del notebook è già in uso prima di crearne uno nuovo.

Ottieni una definizione di notebook

Usare notebookutils.notebook.getDefinition() per recuperare il contenuto completo del notebook in .ipynb formato . Usarlo per il backup, la migrazione, il controllo della versione o l'analisi del contenuto.

Parametri

Parametro Tipo Obbligatorio Descrizione
name String Sì Nome o ID del notebook.
workspaceId String No ID area di lavoro. Lasciare vuoto l'area di lavoro corrente.
format String No Formato dell'output. Il valore predefinito è "ipynb".

Recupera e salva la definizione di un notebook

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

Ottenere una definizione di notebook da un'altra area di lavoro

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

Valore restituito

Il getDefinition() metodo restituisce una stringa contenente il contenuto del notebook in .ipynb formato JSON.

Esportare tutti i notebook per il backup

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

Aggiornare un notebook

Usare notebookutils.notebook.update() per modificare i metadati del notebook, ad esempio il nome visualizzato e la descrizione. Non modifica il contenuto del notebook né la configurazione del lakehouse.

Parametri

Parametro Tipo Obbligatorio Descrizione
name String Sì Nome o ID corrente del notebook.
newName String Sì Nuovo nome di visualizzazione per il notebook.
description String No Descrizione aggiornata.
workspaceId String No ID area di lavoro. Lasciare vuoto l'area di lavoro corrente.

Rinominare un notebook

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

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

Valore restituito

Il update() metodo restituisce un Artifact oggetto con le proprietà aggiornate.

Aggiornare una definizione di notebook

Usare notebookutils.notebook.updateDefinition() per modificare il contenuto del notebook, il lakehouse predefinito o entrambi. Usarlo quando è necessario modificare la definizione del notebook anziché i relativi metadati.

Parametri

Parametro Tipo Obbligatorio Descrizione
name String Sì Nome o ID del notebook da aggiornare.
content String No Nuovo contenuto del notebook in .ipynb formato.
defaultLakehouse String No Nuovo nome predefinito del lakehouse.
defaultLakehouseWorkspace String No ID dell'area di lavoro del nuovo lakehouse predefinito. Lasciare vuoto l'area di lavoro corrente.
workspaceId String No ID area di lavoro. Lasciare vuoto l'area di lavoro corrente.
environmentId String No ID dell'ambiente da collegare al notebook.
environmentWorkspaceId String No ID dello spazio di lavoro dell'ambiente. Lasciare vuoto l'area di lavoro corrente.

Annotazioni

I parametri environmentId e environmentWorkspaceId sono disponibili solo durante l'esecuzione del runtime del notebook Spark. I notebook Python non supportano questi parametri.

Aggiornare il contenuto del notebook

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

Modificare il lakehouse predefinito

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

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

Aggiornare sia il contenuto che 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}")

Valore restituito

Il updateDefinition() metodo restituisce True se l'aggiornamento ha esito positivo o False se ha esito negativo.

Suggerimento

Usare update() per le modifiche ai metadati (nome, descrizione) e updateDefinition() per le modifiche al contenuto e al lakehouse. Quando è necessario un aggiornamento completo dei metadati e del contenuto, chiamare entrambi i metodi in sequenza.

Eliminare un quaderno

Usare notebookutils.notebook.delete() per rimuovere definitivamente un notebook da un'area di lavoro. Restituisce True se l'eliminazione ha esito positivo; in caso contrario, restituisce False.

Parametri

Parametro Tipo Obbligatorio Descrizione
name String Sì Nome o ID del notebook da eliminare.
workspaceId String No ID area di lavoro. Lasciare vuoto l'area di lavoro corrente.

Importante

L'eliminazione è permanente. Non è possibile recuperare i notebook eliminati. Verificare sempre il nome del notebook prima dell'eliminazione e considerare di eseguire il backup della definizione del notebook con getDefinition().

Valore restituito

Il delete() metodo restituisce True se l'eliminazione ha esito positivo o False se ha esito negativo.

Eliminare un quaderno

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

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

Pulire in modo sicuro i notebook in base al modello

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)

Suggerimento

Per un'eliminazione di massa sicura, eseguire sempre prima con dry_run=True per visualizzare in anteprima i notebook che verranno rimossi. Prendere in considerazione la ridenominazione dei notebook con un _TO_DELETE prefisso anziché eliminarli immediatamente, in modo da poterli ripristinare, se necessario.

Elenco dei notebook

Usare notebookutils.notebook.list() per enumerare i notebook in un'area di lavoro. Restituisce una matrice di Artifact oggetti.

Parametri

Parametro Tipo Obbligatorio Descrizione
workspaceId String No ID area di lavoro. Lasciare vuoto l'area di lavoro corrente.
maxResults Intero No Numero massimo di risultati da restituire. Impostazione predefinita è 1000.

Elencare tutti i notebook nell'area di lavoro corrente

notebooks = notebookutils.notebook.list()

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

Elencare i notebook in un'altra area di lavoro

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

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

Valore restituito

Il list() metodo restituisce una matrice di Artifact oggetti. Ogni oggetto contiene displayName, id e description proprietà.

Filtrare i notebook in base al modello di nome

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

Clonare un notebook

Usare list() e getDefinition() insieme per clonare un notebook all'interno della stessa area di lavoro o in un'altra area di lavoro.

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

Eseguire la migrazione di un notebook a un'altra area di lavoro

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

Contenuti correlati

  • Last updated on