Управляйте артефактами записных книжек с использованием NotebookUtils

Используйте notebookutils.notebook для программного управления элементами записной книжки в Microsoft Fabric. Вы можете создавать, извлекать, обновлять, удалять и перечислять артефакты записных книжек для автоматизации развертывания, управления жизненным циклом и рабочих процессов CI/CD.

В следующей таблице перечислены доступные методы управления записными книжками:

Создание записной книжки

Используйте notebookutils.notebook.create() для создания артефакта записной книжки в текущей рабочей области или указанной рабочей области.

Параметры

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

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

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

Возвращаемое значение

Метод 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")

Получение записной книжки

Используется notebookutils.notebook.get() для получения метаданных записной книжки по имени или идентификатору. Он возвращает Artifact объект со свойствами, такими как displayName, idи description.

Параметры

Получите записную книжку из текущей рабочей области

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

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

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

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

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

print(paste("Notebook Name:", notebook$displayName))
print(paste("Notebook ID:", notebook$id))
print(paste("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: описание записной книжки.

Получить определение электронной тетради

Используется notebookutils.notebook.getDefinition() для получения полного содержимого записной книжки в .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")

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

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

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

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

Получение определения записной книжки из другой рабочей области

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.

Параметры

Переименование записной книжки

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() для изменения содержимого записной книжки, озера по умолчанию или обоих. Используйте его, если необходимо изменить определение записной книжки, а не его метаданные.

Параметры

Обновление содержимого записной книжки

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

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

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

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

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

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

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

Изменение озера по умолчанию

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 если оно завершается ошибкой.

Удаление записной книжки

Используйте notebookutils.notebook.delete(), чтобы окончательно удалить записную книжку из рабочей области. Возвращается True , если удаление выполнено успешно; в противном случае возвращается False.

Параметры

Возвращаемое значение

Метод delete() возвращается True , если удаление выполнено успешно или False если оно завершается ошибкой.

Удаление записной книжки

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

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

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

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

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)

Список записных книжек

Используйте notebookutils.notebook.list() для перечисления записных книжек в рабочей области. Он возвращает массив Artifact объектов.

Параметры

Перечислить все ноутбуки в текущей рабочей области

notebooks = notebookutils.notebook.list()

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

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

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

notebooks <- notebookutils.notebook.list()

print(paste("Found", length(notebooks), "notebooks:"))
for (nb in notebooks) {
    print(paste(" -", 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и iddescription свойства.

Фильтрация записных книжек по шаблону имени

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

Связанный контент

• NotebookUtils для Fabric
• NotebookUtils: запуск ноутбука