Διαχείριση αντικειμένων σημειωματαρίου με το NotebookUtils

Χρησιμοποιείται notebookutils.notebook για τη διαχείριση στοιχείων σημειωματαρίου μέσω προγραμματισμού στο Microsoft Fabric. Μπορείτε να δημιουργήσετε, να ανακτήσετε, να ενημερώσετε, να διαγράψετε και να παραθέσετε αντικείμενα σημειωματαρίου για να αυτοματοποιήσετε την ανάπτυξη, τη διαχείριση κύκλου ζωής και τις ροές εργασιών CI/CD.

Σημείωμα

Αυτά τα API υποστηρίζονται μόνο σε σημειωματάρια Fabric και όχι στο Azure Synapse. Πρέπει να έχετε τα κατάλληλα δικαιώματα στον χώρο εργασίας προορισμού για κάθε λειτουργία.

Ο παρακάτω πίνακας παραθέτει τις διαθέσιμες μεθόδους διαχείρισης σημειωματαρίου:

Μέθοδος Υπογραφή Περιγραφή
create create(name, description, content, defaultLakehouse, defaultLakehouseWorkspace, workspaceId): Artifact Δημιουργεί ένα νέο σημειωματάριο.
get get(name, workspaceId): Artifact Ανακτά ένα σημειωματάριο με βάση το όνομα ή το αναγνωριστικό.
getDefinition getDefinition(name, workspaceId, format): String Ανακτά τον ορισμό του σημειωματάριου (περιεχόμενο).
update update(name, newName, description, workspaceId): Artifact Ενημερώνει τα μετα-δεδομένα σημειωματαρίου.
updateDefinition updateDefinition(name, content, defaultLakehouse, defaultLakehouseWorkspace, workspaceId, environmentId, environmentWorkspaceId): bool Ενημερώνει τον ορισμό του σημειωματαρίου και το lakehouse.
delete delete(name, workspaceId): Boolean Διαγράφει ένα σημειωματάριο.
list list(workspaceId, maxResults): Array[Artifact] Παραθέτει όλα τα σημειωματάρια σε ένα χώρο εργασίας.

Δημιουργία σημειωματάριου

Χρησιμοποιήστε το notebookutils.notebook.create() για να δημιουργήσετε ένα νέο αντικείμενο σχεδίασης σημειωματαρίου στον τρέχοντα χώρο εργασίας ή σε έναν καθορισμένο χώρο εργασίας.

Σημείωμα

Παραδείγματα ροής εργασίας σε αυτό το άρθρο που διαβάζουν ή γράφουν .ipynb αρχεία χρησιμοποιούν Python για εισόδους/εξόδους αρχείων. Τα βασικά notebookutils.notebook API είναι διαθέσιμα σε Python, PySpark, Scala και R, εκτός εάν αναφέρεται διαφορετικά.

Παράμετροι

Παράμετρος Τύπος Υποχρεωτικό Περιγραφή
name Συμβλοσειρά Ναι Εμφανιζόμενο όνομα για το νέο σημειωματάριο. Πρέπει να είναι μοναδικό εντός του χώρου εργασίας.
description Συμβλοσειρά Όχι Περιγραφή του σημειωματάριου. Η προεπιλογή είναι κενή.
content Συμβολοσειρά, byte ή υπαγόρευση Ναι Περιεχόμενο σημειωματαρίου σε έγκυρη .ipynb μορφή JSON. Μπορεί επίσης να είναι ακατέργαστα byte ή ένα αντικείμενο υπαγόρευσης. Δεν μπορεί να είναι άδειο.
defaultLakehouse Συμβλοσειρά Όχι Όνομα ή αναγνωριστικό της προεπιλεγμένης λίμνης που θα επισυνάψετε.
defaultLakehouseWorkspace Συμβλοσειρά Όχι Αναγνωριστικό χώρου εργασίας του προεπιλεγμένου lakehouse. Αφήστε κενό για τον τρέχοντα χώρο εργασίας.
workspaceId Συμβλοσειρά Όχι Αναγνωριστικό χώρου εργασίας προορισμού. Αφήστε κενό για τον τρέχοντα χώρο εργασίας.

Σημαντικό

Η content παράμετρος δεν μπορεί να είναι κενή. Πρέπει να παρέχετε περιεχόμενο έγκυρης .ipynb μορφής όταν δημιουργείτε ένα σημειωματάριο. Παρέχετε τουλάχιστον μια έγκυρη δομή κενού σημειωματαρίου:

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

Δημιουργία σημειωματαρίου από πρότυπο

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

Δημιουργία σημειωματαρίου με ένα προεπιλεγμένο lakehouse

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

Επιστρεφόμενη αξία

Η create() μέθοδος επιστρέφει ένα Artifact αντικείμενο με τις ακόλουθες ιδιότητες:

  • displayName: Το εμφανιζόμενο όνομα του φορητού υπολογιστή.
  • id: Το μοναδικό αναγνωριστικό του σημειωματαρίου που δημιουργήθηκε.
  • description: Η περιγραφή του σημειωματάριου.

Δημιουργία σημειωματαρίου σε άλλο χώρο εργασίας

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

Δημιουργία πολλών σημειωματαρίων από ένα πρότυπο

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

Συμβουλή

Δώστε ονόματα και περιγραφές με νόημα για τα σημειωματάριά σας για να διευκολύνετε την εύρεσή τους. Χρησιμοποιήστε μια συνεπή σύμβαση ονομασίας, όπως <Project>_<Purpose>_<Region> για αυτοματοποιημένες αναπτύξεις.

Λήψη σημειωματαρίου

Χρησιμοποιείται για notebookutils.notebook.get() την ανάκτηση μετα-δεδομένων σημειωματαρίου κατά όνομα ή αναγνωριστικό. Επιστρέφει ένα Artifact αντικείμενο με ιδιότητες όπως displayName, idκαι description.

Παράμετροι

Παράμετρος Τύπος Υποχρεωτικό Περιγραφή
name Συμβλοσειρά Ναι Όνομα ή αναγνωριστικό του σημειωματαρίου προς ανάκτηση.
workspaceId Συμβλοσειρά Όχι Αναγνωριστικό χώρου εργασίας. Αφήστε κενό για τον τρέχοντα χώρο εργασίας.

Λήψη σημειωματαρίου από τον τρέχοντα χώρο εργασίας

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

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

Λήψη σημειωματαρίου από άλλο χώρο εργασίας

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

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

Επιστρεφόμενη αξία

Η get() μέθοδος επιστρέφει ένα Artifact αντικείμενο με τις ακόλουθες ιδιότητες:

  • displayName: Το εμφανιζόμενο όνομα του φορητού υπολογιστή.
  • id: Ο μοναδικός αναγνωριστικός κωδικός.
  • description: Η περιγραφή του σημειωματάριου.

Συμβουλή

Χρησιμοποιήστε τις get() λειτουργίες πριν από την ενημέρωση ή τη διαγραφή για να επαληθεύσετε ότι υπάρχει το σημειωματάριο προορισμού. Μπορείτε επίσης να το χρησιμοποιήσετε για να ελέγξετε εάν ένα όνομα σημειωματαρίου χρησιμοποιείται ήδη πριν δημιουργήσετε ένα νέο.

Λήψη ορισμού σημειωματαρίου

Χρησιμοποιήστε notebookutils.notebook.getDefinition() το για να ανακτήσετε το πλήρες περιεχόμενο του σημειωματαρίου σε .ipynb μορφή. Χρησιμοποιήστε το για δημιουργία αντιγράφων ασφαλείας, μετεγκατάσταση, έλεγχο έκδοσης ή ανάλυση περιεχομένου.

Παράμετροι

Παράμετρος Τύπος Υποχρεωτικό Περιγραφή
name Συμβλοσειρά Ναι Όνομα ή αναγνωριστικό του σημειωματαρίου.
workspaceId Συμβλοσειρά Όχι Αναγνωριστικό χώρου εργασίας. Αφήστε κενό για τον τρέχοντα χώρο εργασίας.
format Συμβλοσειρά Όχι Μορφή εξόδου. Η προεπιλογή είναι "ipynb".

Ανάκτηση και αποθήκευση ορισμού σημειωματαρίου

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

Λήψη ορισμού σημειωματαρίου από άλλο χώρο εργασίας

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

Επιστρεφόμενη αξία

Η getDefinition() μέθοδος επιστρέφει μια συμβολοσειρά που περιέχει το περιεχόμενο του σημειωματαρίου σε .ipynb μορφή JSON.

Εξαγωγή όλων των φορητών υπολογιστών για δημιουργία αντιγράφων ασφαλείας

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

Ενημέρωση σημειωματαρίου

Χρησιμοποιείται για notebookutils.notebook.update() την αλλαγή μετα-δεδομένων σημειωματαρίου, όπως το εμφανιζόμενο όνομα και η περιγραφή του. Δεν τροποποιεί το περιεχόμενο του σημειωματαρίου ή τη ρύθμιση παραμέτρων του lakehouse.

Παράμετροι

Παράμετρος Τύπος Υποχρεωτικό Περιγραφή
name Συμβλοσειρά Ναι Τρέχον όνομα ή αναγνωριστικό του σημειωματαρίου.
newName Συμβλοσειρά Ναι Νέο εμφανιζόμενο όνομα για το Notebook.
description Συμβλοσειρά Όχι Ενημερωμένη περιγραφή.
workspaceId Συμβλοσειρά Όχι Αναγνωριστικό χώρου εργασίας. Αφήστε κενό για τον τρέχοντα χώρο εργασίας.

Μετονομασία σημειωματαρίου

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

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

Επιστρεφόμενη αξία

Η update() μέθοδος επιστρέφει ένα Artifact αντικείμενο με τις ενημερωμένες ιδιότητες.

Ενημέρωση ορισμού σημειωματαρίου

Χρησιμοποιήστε το notebookutils.notebook.updateDefinition() για να τροποποιήσετε το περιεχόμενο του σημειωματαρίου, το προεπιλεγμένο lakehouse ή και τα δύο. Χρησιμοποιήστε το όταν πρέπει να αλλάξετε τον ορισμό του σημειωματάριου και όχι τα μετα-δεδομένα του.

Παράμετροι

Παράμετρος Τύπος Υποχρεωτικό Περιγραφή
name Συμβλοσειρά Ναι Όνομα ή αναγνωριστικό του σημειωματαρίου για ενημέρωση.
content Συμβλοσειρά Όχι Νέο περιεχόμενο σημειωματάριου σε .ipynb μορφή.
defaultLakehouse Συμβλοσειρά Όχι Νέο προεπιλεγμένο όνομα lakehouse.
defaultLakehouseWorkspace Συμβλοσειρά Όχι Αναγνωριστικό χώρου εργασίας του νέου προεπιλεγμένου lakehouse. Αφήστε κενό για τον τρέχοντα χώρο εργασίας.
workspaceId Συμβλοσειρά Όχι Αναγνωριστικό χώρου εργασίας. Αφήστε κενό για τον τρέχοντα χώρο εργασίας.
environmentId Συμβλοσειρά Όχι Αναγνωριστικό περιβάλλοντος για επισύναψη στο σημειωματάριο.
environmentWorkspaceId Συμβλοσειρά Όχι Αναγνωριστικό χώρου εργασίας του περιβάλλοντος. Αφήστε κενό για τον τρέχοντα χώρο εργασίας.

Σημείωμα

Οι environmentId παράμετροι και environmentWorkspaceId είναι διαθέσιμες μόνο στο χρόνο εκτέλεσης του σημειωματάριου Spark. Τα σημειωματάρια 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}")

Αλλαγή του προεπιλεγμένου lakehouse

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

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

Ενημερώστε τόσο το περιεχόμενο όσο και το 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}")

Επιστρεφόμενη αξία

Η updateDefinition() μέθοδος επιστρέφει True εάν η ενημέρωση είναι επιτυχής ή False εάν αποτύχει.

Συμβουλή

Χρησιμοποιείται update() για αλλαγές μετα-δεδομένων (όνομα, περιγραφή) και updateDefinition() για αλλαγές περιεχομένου και lakehouse. Όταν χρειάζεστε πλήρη ανανέωση τόσο των μετα-δεδομένων όσο και του περιεχομένου, καλέστε και τις δύο μεθόδους με τη σειρά.

Διαγραφή σημειωματάριου

Χρησιμοποιήστε το notebookutils.notebook.delete() για να καταργήσετε οριστικά ένα σημειωματάριο από έναν χώρο εργασίας. Επιστρέφει True εάν η διαγραφή είναι επιτυχής. Διαφορετικά, επιστρέφει False.

Παράμετροι

Παράμετρος Τύπος Υποχρεωτικό Περιγραφή
name Συμβλοσειρά Ναι Όνομα ή αναγνωριστικό του σημειωματαρίου που θέλετε να διαγράψετε.
workspaceId Συμβλοσειρά Όχι Αναγνωριστικό χώρου εργασίας. Αφήστε κενό για τον τρέχοντα χώρο εργασίας.

Σημαντικό

Η διαγραφή είναι μόνιμη. Δεν είναι δυνατή η ανάκτηση διαγραμμένων σημειωματαρίων. Επαληθεύετε πάντα το όνομα του σημειωματαρίου πριν διαγράψετε και εξετάστε το ενδεχόμενο να δημιουργήσετε αντίγραφα ασφαλείας του ορισμού του σημειωματαρίου με getDefinition() πρώτα.

Επιστρεφόμενη αξία

Η delete() μέθοδος επιστρέφει True εάν η διαγραφή είναι επιτυχής ή False εάν αποτύχει.

Διαγραφή σημειωματάριου

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

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

Ασφαλής καθαρισμός σημειωματάριων ανά μοτίβο

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)

Συμβουλή

Για ασφαλή μαζική διαγραφή, εκτελείτε πάντα με dry_run=True το first για να κάνετε προεπισκόπηση των σημειωματαρίων που θα καταργηθούν. Εξετάστε το ενδεχόμενο να μετονομάσετε σημειωματάρια με πρόθεμα _TO_DELETE αντί να τα διαγράψετε αμέσως, ώστε να μπορείτε να τα ανακτήσετε εάν χρειάζεται.

Λίστα σημειωματαρίων

Χρησιμοποιείται για notebookutils.notebook.list() την απαρίθμηση σημειωματαρίων σε ένα χώρο εργασίας. Επιστρέφει μια σειρά Artifact αντικειμένων.

Παράμετροι

Παράμετρος Τύπος Υποχρεωτικό Περιγραφή
workspaceId Συμβλοσειρά Όχι Αναγνωριστικό χώρου εργασίας. Αφήστε κενό για τον τρέχοντα χώρο εργασίας.
maxResults Int Όχι Μέγιστος αριθμός αποτελεσμάτων προς επιστροφή. Προεπιλογή 1000.

Λίστα όλων των σημειωματαρίων στον τρέχοντα χώρο εργασίας

notebooks = notebookutils.notebook.list()

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

Λίστα σημειωματαρίων σε άλλο χώρο εργασίας

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

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

Επιστρεφόμενη αξία

Η list() μέθοδος επιστρέφει έναν πίνακα Artifact αντικειμένων. Κάθε αντικείμενο περιέχει displayName, idκαι description ιδιότητες.

Φιλτράρισμα σημειωματαρίων κατά μοτίβο ονόματος

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

Κλωνοποιήστε ένα σημειωματάριο

Χρησιμοποιήστε list() και getDefinition() μαζί για να κλωνοποιήσετε ένα σημειωματάριο στον ίδιο χώρο εργασίας ή σε έναν άλλο χώρο εργασίας.

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

Μετεγκατάσταση σημειωματαρίου σε άλλο χώρο εργασίας

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