Zdieľať cez

Spravujte artefakty zápisníka pomocou NotebookUtils

Použitie notebookutils.notebook na programovú správu zápisových položiek v Microsoft Fabric. Môžete vytvárať, načítavať, aktualizovať, mazať a zoznamovať artefakty zápisníkov, aby ste automatizovali nasadenie, správu životného cyklu a CI/CD pracovné postupy.

Poznámka

Tieto API sú podporované iba v Fabric notebookoch, nie v Azure Synapse. Musíte mať príslušné oprávnenia v cieľovom pracovnom priestore pre každú operáciu.

Nasledujúca tabuľka uvádza dostupné metódy správy zápisníka:

Method Podpis Description
create create(name, description, content, defaultLakehouse, defaultLakehouseWorkspace, workspaceId): Artifact Vytvorí nový zápisník.
get get(name, workspaceId): Artifact Získa zápisník podľa mena alebo dokladu totožnosti.
getDefinition getDefinition(name, workspaceId, format): String Získa definíciu (obsah) zápisníka.
update update(name, newName, description, workspaceId): Artifact Aktualizuje metadáta zápisníka.
updateDefinition updateDefinition(name, content, defaultLakehouse, defaultLakehouseWorkspace, workspaceId, environmentId, environmentWorkspaceId): bool Aktualizuje definíciu zápisníka a lakehouse.
delete delete(name, workspaceId): Boolean Odstráni poznámkový blok.
list list(workspaceId, maxResults): Array[Artifact] Zobrazuje všetky zápisníky v pracovnom priestore.

Vytvorenie poznámkového bloku

Použite notebookutils.notebook.create() na vytvorenie nového artefaktu zápisníka v aktuálnom pracovnom priestore alebo v určenom pracovnom priestore.

Poznámka

Príklady pracovných postupov v tomto článku, ktoré čítajú alebo zapisujú .ipynb súbory, používajú Python pre vstup/výstup súborov. Základné notebookutils.notebook API sú dostupné v Pythone, PySparku, Scale a R, pokiaľ nie je uvedené inak.

Parametre

Parameter Typ Požaduje sa Description
name Povrázok Áno Zobrazovacie meno pre nový zápisník. Musí byť jedinečný v rámci pracovného priestoru.
description Povrázok Nie Popis zápisníka. Predvolene je prázdny.
content Reťazec, bajty alebo dict Áno Obsah zápisníka v platnom .ipynb formáte JSON. Môžu to byť aj surové bajty alebo objekt dict. Nemôže byť prázdny.
defaultLakehouse Povrázok Nie Názov alebo ID predvoleného jazerného domu na pripojenie.
defaultLakehouseWorkspace Povrázok Nie Workspace ID predvoleného jazerného domu. Nechajte prázdne miesto pre aktuálny pracovný priestor.
workspaceId Povrázok Nie ID cieľového pracovného priestoru. Nechajte prázdne miesto pre aktuálny pracovný priestor.

Dôležité

Parameter content nemôže byť prázdny. Pri tvorbe zápisníka musíte poskytnúť obsah v platnom .ipynb formáte. Minimálne poskytnite platnú štruktúru prázdneho zápisníka:

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

Vytvorte si zápisník z šablóny

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

Vytvorte si zápisník s predvoleným jazerným domom

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

Vrátená hodnota

Metóda create()Artifact vracia objekt s nasledujúcimi vlastnosťami:

  • displayName: Zobrazovaný názov zápisníka.
  • id: Jedinečný identifikátor vytvoreného zápisníka.
  • description: Popis zápisníka.

Vytvorte si zápisník v inom pracovnom priestore

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

Vytvorte viacero zápisníkov z šablóny

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

Prepitné

Poskytujte zmysluplné názvy a popisy pre svoje zápisníky, aby boli ľahšie dostupné. Používajte konzistentnú konvenciu pomenovania, napríklad <Project>_<Purpose>_<Region> pri automatizovaných nasadeniach.

Kúp si zápisník

Použitie notebookutils.notebook.get() na získanie metadát zápisníka podľa mena alebo ID. Vracia Artifact objekt s vlastnosťami displayNameako , id, a description.

Parametre

Parameter Typ Požaduje sa Description
name Povrázok Áno Názov alebo ID zápisníka na vyzdvihnutie.
workspaceId Povrázok Nie ID pracovného priestoru. Nechajte prázdne miesto pre aktuálny pracovný priestor.

Zoberte si zápisník z aktuálneho pracoviska

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

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

Zoberte si zápisník z iného pracoviska

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

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

Vrátená hodnota

Metóda get()Artifact vracia objekt s nasledujúcimi vlastnosťami:

  • displayName: Zobrazovaný názov zápisníka.
  • id: Jedinečný identifikátor.
  • description: Popis zápisníka.

Prepitné

Použite get() operácie pred aktualizáciou alebo vymazaním na overenie, či cieľový zápisník existuje. Môžete ho tiež použiť na overenie, či je názov zápisníka už používaný predtým, než vytvoríte nový.

Získajte definíciu zápisníka

Použite notebookutils.notebook.getDefinition() na získanie celého obsahu zápisníka vo .ipynb formáte. Používajte ho na zálohovanie, migráciu, správu verzií alebo analýzu obsahu.

Parametre

Parameter Typ Požaduje sa Description
name Povrázok Áno Názov alebo ID zápisníka.
workspaceId Povrázok Nie ID pracovného priestoru. Nechajte prázdne miesto pre aktuálny pracovný priestor.
format Povrázok Nie Formát výstupu. Predvolene je nastavená na "ipynb"hodnotu .

Vyhľadajte a uložte definíciu zápisníka

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

Získajte definíciu zápisníka z iného pracovného priestoru

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

Vrátená hodnota

Metóda getDefinition() vráti reťazec obsahujúci obsah zápisníka vo .ipynb formáte JSON.

Exportujte všetky notebooky na zálohovanie

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

Aktualizujte si zápisník

Použiť na notebookutils.notebook.update() zmenu metadát zápisníka, ako je jeho zobrazovaný názov a popis. Neupravuje obsah notebooku ani konfiguráciu lakehouse.

Parametre

Parameter Typ Požaduje sa Description
name Povrázok Áno Aktuálny názov alebo ID zápisníka.
newName Povrázok Áno Nový zobrazovací názov zápisníka.
description Povrázok Nie Aktualizovaný popis.
workspaceId Povrázok Nie ID pracovného priestoru. Nechajte prázdne miesto pre aktuálny pracovný priestor.

Premenujte zápisník

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

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

Vrátená hodnota

Metóda update() vráti Artifact objekt s aktualizovanými vlastnosťami.

Aktualizujte definíciu zápisníka

Použite notebookutils.notebook.updateDefinition() na úpravu obsahu zápisníka, predvoleného jazerného domu alebo oboch. Používajte ho, keď potrebujete zmeniť definíciu zápisníka, nie jeho metadáta.

Parametre

Parameter Typ Požaduje sa Description
name Povrázok Áno Názov alebo ID zápisníka na aktualizáciu.
content Povrázok Nie Nový obsah zápisníka vo formáte .ipynb .
defaultLakehouse Povrázok Nie Nový predvolený názov jazerného domu.
defaultLakehouseWorkspace Povrázok Nie ID pracovného priestoru nového predvoleného jazerného domu. Nechajte prázdne miesto pre aktuálny pracovný priestor.
workspaceId Povrázok Nie ID pracovného priestoru. Nechajte prázdne miesto pre aktuálny pracovný priestor.
environmentId Povrázok Nie Environment ID na pripojenie k zápisníku.
environmentWorkspaceId Povrázok Nie ID pracovného priestoru prostredia. Nechajte prázdne miesto pre aktuálny pracovný priestor.

Poznámka

Parametre environmentId a environmentWorkspaceId sú dostupné iba v runtime Spark notebooku. Python notebooky tieto parametre nepodporujú.

Aktualizujte obsah zápisníka

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

Zmeň predvolený jazerný dom

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

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

Aktualizujte obsah aj 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}")

Vrátená hodnota

Metóda updateDefinition() sa vráti, True ak je aktualizácia úspešná alebo False ak zlyhá.

Prepitné

Použitie update() na zmeny metadát (názov, popis) a updateDefinition() na zmeny obsahu a jazerných domov. Keď potrebujete úplné obnovenie metadát aj obsahu, volajte obe metódy postupne.

Odstránenie poznámkového bloku

Použitie notebookutils.notebook.delete() na trvalé odstránenie zápisníka z pracovného priestoru. Vráti, True ak vymazanie uspeje; inak vráti .False

Parametre

Parameter Typ Požaduje sa Description
name Povrázok Áno Názov alebo ID zápisníka na vymazanie.
workspaceId Povrázok Nie ID pracovného priestoru. Nechajte prázdne miesto pre aktuálny pracovný priestor.

Dôležité

Vymazanie je trvalé. Vymazané zápisníky sa nedajú obnoviť. Vždy si overte názov zápisníka pred vymazaním a zvážte zálohovanie definície zápisníka na prvé getDefinition() .

Vrátená hodnota

Metóda delete() sa vráti, True ak vymazanie uspeje alebo False ak zlyhá.

Odstránenie poznámkového bloku

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

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

Bezpečne upratujte zošity podľa 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)

Prepitné

Pre bezpečné hromadné mazanie vždy používajte prvú možnosť dry_run=True náhľadu, ktoré zápisníky budú odstránené. Zvážte premenovanie zápisníkov na _TO_DELETE prefix namiesto ich okamžitého vymazania, aby ste ich mohli v prípade potreby obnoviť.

Zoznamové zápisníky

Používajte notebookutils.notebook.list() na enumeráciu zápisníkov v pracovnom priestore. Vráti pole Artifact objektov.

Parametre

Parameter Typ Požaduje sa Description
workspaceId Povrázok Nie ID pracovného priestoru. Nechajte prázdne miesto pre aktuálny pracovný priestor.
maxResults Int Nie Maximálny počet výsledkov na vrátenie. Predvolene je nastavená na 1000.

Zoznam všetkých zápisníkov v aktuálnom pracovnom priestore

notebooks = notebookutils.notebook.list()

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

Zaradiť zápisníky do iného pracovného priestoru

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

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

Vrátená hodnota

Metóda list() vráti pole Artifact objektov. Každý objekt obsahuje displayName, id, a description vlastnosti.

Filtrovať zápisníky podľa vzoru názvov

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 zápisník

Použite list() a getDefinition() spolu na klonovanie zápisníka v rámci rovnakého pracovného priestoru alebo do iného pracovného priestoru.

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

Migrujte zápisník do iného pracovného priestoru

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

Súvisiaci obsah

  • Last updated on