Spravujte položky zápisníku pomocí NotebookUtils

Použijte notebookutils.notebook k programové správě položek poznámkového bloku v Microsoft Fabric. Můžete vytvářet, načítat, aktualizovat, mazat a zařadit položky zápisníku, abyste automatizovali nasazení, správu životního cyklu a CI/CD workflow.

Poznámka:

Tato rozhraní API se podporují jenom v poznámkových blocích Fabric, ne v Azure Synapse. Pro každou operaci musíte mít příslušná oprávnění v cílovém pracovním prostoru.

V následující tabulce jsou uvedené dostupné metody správy poznámkových bloků:

Metoda	Signature	Description
create	create(name, description, content, defaultLakehouse, defaultLakehouseWorkspace, workspaceId): Artifact	Vytvoří nový poznámkový blok.
get	get(name, workspaceId): Artifact	Načte poznámkový blok podle názvu nebo ID.
getDefinition	getDefinition(name, workspaceId, format): String	Načte obsah definice poznámkového bloku.
update	update(name, newName, description, workspaceId): Artifact	Aktualizuje metadata poznámkového bloku.
updateDefinition	updateDefinition(name, content, defaultLakehouse, defaultLakehouseWorkspace, workspaceId, environmentId, environmentWorkspaceId): bool	Aktualizuje definici poznámkového bloku a jezero.
delete	delete(name, workspaceId): Boolean	Odstraní poznámkový blok.
list	list(workspaceId, maxResults): Array[Artifact]	Zobrazí seznam všech poznámkových bloků v pracovním prostoru.

Vytvořte poznámkový blok

Použijte notebookutils.notebook.create() k vytvoření nové položky v notebooku v aktuálním pracovním prostoru nebo v určeném pracovním prostoru.

Poznámka:

Příklady pracovních postupů v tomto článku, které čtou nebo zapisuje .ipynb soubory, používají Python pro vstupně-výstupní operace souborů. notebookutils.notebook Základní rozhraní API jsou k dispozici v Pythonu, PySpark, Scala a R, pokud není uvedeno jinak.

Parametry

Parameter	Typ	Povinné	Description
name	String	Ano	Zobrazovaný název nového poznámkového bloku Musí být v rámci pracovního prostoru jedinečný.
description	String	Ne	Popis poznámkového bloku Výchozí hodnota je prázdná.
content	Řetězec, bajty nebo slovník	Ano	Obsah poznámkového bloku v platném .ipynb formátu JSON Může se jednat také o nezpracované bajty nebo objekt diktování. Nemůže být prázdný.
defaultLakehouse	String	Ne	Název nebo ID výchozího jezera, který se má připojit.
defaultLakehouseWorkspace	String	Ne	ID pracovního prostoru výchozího lakehouse. Ponechte pro aktuální pracovní prostor prázdný.
workspaceId	String	Ne	ID cílového pracovního prostoru. Ponechte pro aktuální pracovní prostor prázdný.

Důležité

Parametr content nemůže být prázdný. Při vytváření poznámkového bloku musíte zadat platný .ipynb obsah formátu. Minimálně zadejte platnou prázdnou strukturu poznámkového bloku:

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

Vytvoření poznámkového bloku ze šablony

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

Vytvoření notebooku s výchozí konfigurací lakehouse

Python

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

Scala

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

val notebook = notebookutils.notebook.create(
    "DataAnalysis",
    "Analysis notebook with lakehouse access",
    minimalContent,
    "MyLakehouse",
    "",
    ""
)

println(s"Created notebook with lakehouse: ${notebook.displayName}")

R

minimal_content <- '{
    "cells": [],
    "metadata": {},
    "nbformat": 4,
    "nbformat_minor": 5
}'

notebook <- notebookutils.notebook.create(
    "DataAnalysis",
    "Analysis notebook with lakehouse access",
    minimal_content,
    "MyLakehouse",
    "",
    ""
)

print(paste("Created notebook with lakehouse:", notebook$displayName))

Návratová hodnota

Metoda create() vrátí Artifact objekt s následujícími vlastnostmi:

• displayName: Název displeje notebooku.
• id: Jedinečný identifikátor vytvořeného poznámkového bloku.
• description: Popis poznámkového bloku.

Vytvoření poznámkového bloku v jiném pracovním prostoru

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

Vytvoření více poznámkových bloků ze šablony

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

Návod

Zadejte smysluplné názvy a popisy poznámkových bloků, abyste je snadněji našli. Použijte konzistentní zásady vytváření názvů, například <Project>_<Purpose>_<Region> pro automatizovaná nasazení.

Pořiďte si zápisník

Použijte notebookutils.notebook.get() k načtení metadat poznámkového bloku podle názvu nebo ID. Vrátí Artifact objekt s vlastnostmi, jako jsou displayName, id a description.

Parametry

Parameter	Typ	Povinné	Description
name	String	Ano	Název nebo ID poznámkového bloku, který chcete načíst.
workspaceId	String	Ne	ID pracovního prostoru. Ponechte pro aktuální pracovní prostor prázdný.

Získejte poznámkový blok z aktuálního pracovního prostoru

Python

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

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

Scala

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

println(s"Notebook Name: ${notebook.displayName}")
println(s"Notebook ID: ${notebook.id}")
println(s"Description: ${notebook.description}")

R

notebook <- notebookutils.notebook.get("MyNotebook")

print(paste("Notebook Name:", notebook$displayName))
print(paste("Notebook ID:", notebook$id))
print(paste("Description:", notebook$description))

Získejte poznámkový blok z jiného pracovního prostoru

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

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

Návratová hodnota

Metoda get() vrátí Artifact objekt s následujícími vlastnostmi:

• displayName: Název displeje notebooku.
• id: Jedinečný identifikátor.
• description: Popis poznámkového bloku.

Návod

Před operacemi get() aktualizace nebo odstranění ověřte, že cílový poznámkový blok existuje. Můžete ho také použít ke kontrole, jestli se název poznámkového bloku už používá, než vytvoříte nový.

Získání definice poznámkového bloku

Použijte notebookutils.notebook.getDefinition() k načtení celého obsahu poznámkového bloku ve .ipynb formátu. Můžete ho použít pro zálohování, migraci, správu verzí nebo analýzu obsahu.

Parametry

Parameter	Typ	Povinné	Description
name	String	Ano	Název nebo ID poznámkového bloku
workspaceId	String	Ne	ID pracovního prostoru. Ponechte pro aktuální pracovní prostor prázdný.
format	String	Ne	Výstupní formát Výchozí hodnota je "ipynb".

Načtení a uložení definice poznámkového bloku

Python

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

Scala

// Retrieve notebook definition in Scala
val content = notebookutils.notebook.getDefinition("MyNotebook")

println(s"Retrieved notebook content (${content.length} characters)")

R

content <- notebookutils.notebook.getDefinition("MyNotebook")

print(paste("Retrieved notebook content (", nchar(content), " characters)", sep = ""))

Získání definice poznámkového bloku z jiného pracovního prostoru

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

Návratová hodnota

Metoda getDefinition() vrátí řetězec obsahující obsah poznámkového bloku ve .ipynb formátu JSON.

Export všech poznámkových bloků pro zálohování

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

Aktualizace poznámkového bloku

Slouží notebookutils.notebook.update() ke změně metadat poznámkového bloku, například zobrazovaného názvu a popisu. Neupravuje obsah poznámkového bloku ani konfiguraci lakehouse.

Parametry

Parameter	Typ	Povinné	Description
name	String	Ano	Aktuální název nebo ID poznámkového bloku
newName	String	Ano	Nový zobrazovaný název poznámkového bloku
description	String	Ne	Aktualizovaný popis
workspaceId	String	Ne	ID pracovního prostoru. Ponechte pro aktuální pracovní prostor prázdný.

Přejmenování poznámkového bloku

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

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

Návratová hodnota

Metoda update() vrátí Artifact objekt s aktualizovanými vlastnostmi.

Aktualizovat definici poznámkového bloku

Pomocí notebookutils.notebook.updateDefinition() můžete upravit obsah poznámkového bloku, výchozího Lakehouse nebo obojí. Použijte ho, když potřebujete změnit definici poznámkového bloku, a ne její metadata.

Parametry

Parameter	Typ	Povinné	Description
name	String	Ano	Název nebo ID poznámkového bloku, který chcete aktualizovat.
content	String	Ne	Nový obsah poznámkového bloku ve .ipynb formátu
defaultLakehouse	String	Ne	Nový výchozí název jezera.
defaultLakehouseWorkspace	String	Ne	ID pracovního prostoru nového výchozího lakehouse. Ponechte pro aktuální pracovní prostor prázdný.
workspaceId	String	Ne	ID pracovního prostoru. Ponechte pro aktuální pracovní prostor prázdný.
environmentId	String	Ne	ID prostředí, které se připojí k poznámkovému bloku
environmentWorkspaceId	String	Ne	ID prostředí pracovního prostoru. Ponechte pro aktuální pracovní prostor prázdný.

Poznámka:

Parametry environmentId a environmentWorkspaceId jsou k dispozici pouze v prostředí runtime poznámkového bloku Sparku. Poznámkové bloky Pythonu tyto parametry nepodporují.

Aktualizace obsahu poznámkového bloku

Python

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

Scala

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

val isUpdated = notebookutils.notebook.updateDefinition(
    "MyNotebook",
    newContent
)

println(s"Notebook definition updated: ${isUpdated}")

R

new_content <- '{
    "cells": [],
    "metadata": {},
    "nbformat": 4,
    "nbformat_minor": 5
}'

is_updated <- notebookutils.notebook.updateDefinition(
    "MyNotebook",
    new_content
)

print(paste("Notebook definition updated:", is_updated))

Změna výchozího lakehouse

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

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

Aktualizujte jak obsah, tak i 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}")

Návratová hodnota

Metoda updateDefinition() vrátí True , pokud aktualizace proběhne úspěšně nebo False pokud selže.

Návod

Použijte update() pro změny metadat (název, popis) a updateDefinition() pro změny obsahu a lakehouse. Pokud potřebujete úplnou aktualizaci metadat i obsahu, volejte obě metody postupně.

Odstranění poznámkového bloku

Slouží notebookutils.notebook.delete() k trvalému odebrání poznámkového bloku z pracovního prostoru. Vrátí True, pokud odstranění proběhne úspěšně; v opačném případě False.

Parametry

Parameter	Typ	Povinné	Description
name	String	Ano	Název nebo ID poznámkového bloku, který chcete odstranit.
workspaceId	String	Ne	ID pracovního prostoru. Ponechte pro aktuální pracovní prostor prázdný.

Důležité

Odstranění je trvalé. Odstraněné poznámkové bloky není možné obnovit. Před odstraněním vždy ověřte název poznámkového bloku a nejprve zvažte zálohování definice getDefinition() poznámkového bloku.

Návratová hodnota

Metoda delete() vrátí True , pokud odstranění proběhne úspěšně nebo False pokud selže.

Odstranění poznámkového bloku

Python

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

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

Scala

// Delete a notebook in Scala
val isDeleted = notebookutils.notebook.delete("ObsoleteNotebook")

if (isDeleted) println("Deleted") else println("Failed to delete")

R

is_deleted <- notebookutils.notebook.delete("ObsoleteNotebook")

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

Bezpečné vyčištění poznámkových bloků podle vzoru

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)

Návod

V případě bezpečného hromadného odstranění vždy nejprve spusťte dry_run=True, abyste si zobrazili náhled poznámkových bloků, které budou odstraněny. Místo okamžitého odstranění poznámkových bloků zvažte přejmenování poznámkových bloků s předponou _TO_DELETE , abyste je v případě potřeby mohli obnovit.

Seznam poznámkových bloků

** Použijte notebookutils.notebook.list() pro výčet poznámkových bloků v pracovním prostoru. Vrátí pole Artifact objektů.

Parametry

Parameter	Typ	Povinné	Description
workspaceId	String	Ne	ID pracovního prostoru. Ponechte pro aktuální pracovní prostor prázdný.
maxResults	int	Ne	Maximální počet výsledků, které se mají vrátit. Výchozí nastavení je 1000.

Seznam všech poznámkových bloků v aktuálním pracovním prostoru

Python

notebooks = notebookutils.notebook.list()

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

Scala

// List all notebooks in Scala
val notebooks = notebookutils.notebook.list()

println(s"Found ${notebooks.length} notebooks")
notebooks.foreach(nb => println(s"  - ${nb.displayName}"))

R

notebooks <- notebookutils.notebook.list()

print(paste("Found", length(notebooks), "notebooks:"))
for (nb in notebooks) {
    print(paste(" -", nb$displayName, "(ID:", nb$id, ")"))
}

Zobrazení poznámkových bloků v jiném pracovním prostoru

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

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

Návratová hodnota

Metoda list() vrátí pole Artifact objektů. Každý objekt obsahuje displayName, ida description vlastnosti.

Filtrování poznámkových bloků podle vzoru názvů

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

Klonujte poznámkový blok

Pomocí list() a getDefinition() společně naklonujte poznámkový blok v rámci stejného pracovního prostoru nebo do jiného pracovního prostoru.

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

Migrace poznámkového bloku do jiného pracovního prostoru

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

Související obsah

• NotebookUtils pro Fabric
• NotebookUtils spuštění poznámkového bloku