Compartilhar via

Gerenciar artefatos de notebook com NotebookUtils

Use notebookutils.notebook para gerenciar itens de notebook programaticamente no Microsoft Fabric. Você pode criar, recuperar, atualizar, excluir e listar artefatos de notebook para automatizar a implantação, o gerenciamento do ciclo de vida e os fluxos de trabalho de CI/CD.

Observação

Essas APIs têm suporte apenas em notebooks do Fabric, não no Azure Synapse. Você deve ter permissões apropriadas no workspace de destino para cada operação.

A tabela a seguir lista os métodos de gerenciamento de notebook disponíveis:

Método Signature Descrição
create create(name, description, content, defaultLakehouse, defaultLakehouseWorkspace, workspaceId): Artifact Cria um novo bloco de anotações.
get get(name, workspaceId): Artifact Recupera um notebook por nome ou ID.
getDefinition getDefinition(name, workspaceId, format): String Recupera a definição do notebook (conteúdo).
update update(name, newName, description, workspaceId): Artifact Atualiza os metadados do notebook.
updateDefinition updateDefinition(name, content, defaultLakehouse, defaultLakehouseWorkspace, workspaceId, environmentId, environmentWorkspaceId): bool Atualiza a definição do notebook e o Lakehouse.
delete delete(name, workspaceId): Boolean Exclui um notebook.
list list(workspaceId, maxResults): Array[Artifact] Lista todos os blocos de anotações em um workspace.

Criar um notebook

Use notebookutils.notebook.create() para criar um novo artefato de notebook no espaço de trabalho atual ou em um espaço de trabalho especificado.

Observação

Exemplos de fluxo de trabalho neste artigo que leem ou gravam .ipynb arquivos usam Python para E/S de arquivo. As APIs principais notebookutils.notebook estão disponíveis em Python, PySpark, Scala e R, a menos que indicado de outra forma.

Parâmetros

Parâmetro Tipo Obrigatório Descrição
name String Sim Nome de exibição para o novo bloco de anotações. Deve ser exclusivo dentro do espaço de trabalho.
description String No Descrição do bloco de anotações. O padrão é vazio.
content string, bytes ou dicionário Sim Conteúdo do notebook no formato JSON válido .ipynb. Também pode ser bytes brutos ou um objeto de ditado. Não pode estar vazio.
defaultLakehouse String No Nome ou ID do lakehouse padrão a ser anexado.
defaultLakehouseWorkspace String No ID do workspace do lakehouse padrão. Deixe vazio para o espaço de trabalho atual.
workspaceId String No ID do workspace de destino. Deixe vazio para o espaço de trabalho atual.

Importante

O content parâmetro não pode estar vazio. Você deve fornecer conteúdo de formato válido .ipynb ao criar um bloco de anotações. No mínimo, forneça uma estrutura de notebook vazia válida:

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

Criar um notebook com base em um modelo

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

Criar um bloco de anotações com um lakehouse padrão

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

Valor de retorno

O create() método retorna um Artifact objeto com as seguintes propriedades:

  • displayName: o nome de exibição do bloco de anotações.
  • id: o identificador exclusivo do notebook criado.
  • description: a descrição do bloco de anotações.

Criar um notebook em outro espaço de trabalho

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

Criar vários cadernos digitais seguindo um modelo

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

Dica

Forneça nomes e descrições significativos para seus blocos de anotações para facilitar a localização deles. Use uma convenção de nomenclatura consistente, como <Project>_<Purpose>_<Region> para implantações automatizadas.

Obter um notebook

Use notebookutils.notebook.get() para recuperar metadados do notebook por nome ou ID. Ele retorna um Artifact objeto com propriedades como displayName, ide description.

Parâmetros

Parâmetro Tipo Obrigatório Descrição
name String Sim Nome ou ID do notebook a ser recuperado.
workspaceId String No ID do workspace. Deixe vazio para o espaço de trabalho atual.

Obter um notebook do espaço de trabalho atual

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

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

Obter um caderno de outro espaço de trabalho

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

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

Valor de retorno

O get() método retorna um Artifact objeto com as seguintes propriedades:

  • displayName: o nome de exibição do bloco de anotações.
  • id: o identificador exclusivo.
  • description: a descrição do bloco de anotações.

Dica

Use get() antes de operações de atualização ou exclusão para verificar se o notebook de destino existe. Você também pode usá-lo para verificar se um nome de bloco de anotações já está em uso antes de criar um novo.

Obtenha uma definição de notebook

Use notebookutils.notebook.getDefinition() para recuperar o conteúdo completo do bloco de anotações em .ipynb formato. Use-o para backup, migração, controle de versão ou análise de conteúdo.

Parâmetros

Parâmetro Tipo Obrigatório Descrição
name String Sim Nome ou ID do bloco de anotações.
workspaceId String No ID do workspace. Deixe vazio para o espaço de trabalho atual.
format String No Formato de saída. Usa "ipynb" como padrão.

Recuperar e salvar uma definição de 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")

Obter uma definição de notebook de outro espaço de trabalho

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

Valor de retorno

O getDefinition() método retorna uma cadeia de caracteres que contém o conteúdo do bloco de anotações no .ipynb formato JSON.

Exportar todos os notebooks para 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()

Atualizar um notebook

Use notebookutils.notebook.update() para alterar metadados do notebook, como seu nome de exibição e descrição. Ele não modifica o conteúdo do notebook nem a configuração do lakehouse.

Parâmetros

Parâmetro Tipo Obrigatório Descrição
name String Sim Nome ou ID atual do bloco de anotações.
newName String Sim Novo nome de exibição para o notebook.
description String No Descrição atualizada.
workspaceId String No ID do workspace. Deixe vazio para o espaço de trabalho atual.

Renomear um notebook

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

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

Valor de retorno

O update() método retorna um Artifact objeto com as propriedades atualizadas.

Atualizar uma definição de computador portátil

Use notebookutils.notebook.updateDefinition() para modificar o conteúdo do notebook, o lakehouse padrão ou ambos. Use-a quando precisar alterar a definição do notebook em vez de seus metadados.

Parâmetros

Parâmetro Tipo Obrigatório Descrição
name String Sim Nome ou ID do notebook a ser atualizado.
content String No Novo conteúdo do bloco de anotações em .ipynb formato.
defaultLakehouse String No Novo nome padrão do lakehouse.
defaultLakehouseWorkspace String No ID do workspace do novo lakehouse padrão. Deixe vazio para o espaço de trabalho atual.
workspaceId String No ID do workspace. Deixe vazio para o espaço de trabalho atual.
environmentId String No ID do ambiente a ser anexado ao notebook.
environmentWorkspaceId String No Identificação do workspace do ambiente. Deixe vazio para o espaço de trabalho atual.

Observação

Os parâmetros environmentId e environmentWorkspaceId só estão disponíveis no ambiente de execução do notebook Spark. Notebooks Python não dão suporte a esses parâmetros.

Atualizar o conteúdo do bloco de anotações

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

Alterar o lakehouse padrão

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

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

Atualizar o conteúdo e o 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}")

Valor de retorno

O updateDefinition() método retornará True se a atualização for bem-sucedida ou False se falhar.

Dica

Use update() para alterações de metadados (nome, descrição) e updateDefinition() para alterações de conteúdo e lakehouse. Quando você precisar de uma atualização completa de metadados e conteúdo, chame ambos os métodos em sequência.

Excluir um notebook

Use notebookutils.notebook.delete() para remover permanentemente um notebook de um workspace. Ele retornará True se a exclusão for bem-sucedida; caso contrário, retornará False.

Parâmetros

Parâmetro Tipo Obrigatório Descrição
name String Sim Nome ou ID do bloco de anotações a ser excluído.
workspaceId String No ID do workspace. Deixe vazio para o espaço de trabalho atual.

Importante

A exclusão é permanente. Notebooks excluídos não podem ser recuperados. Sempre verifique o nome do bloco de anotações antes de excluir e considere fazer backup da definição do bloco de anotações com getDefinition() primeiro.

Valor de retorno

O delete() método retornará True se a exclusão for bem-sucedida ou False se falhar.

Excluir um notebook

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

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

Limpar notebooks com segurança por padrão

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)

Dica

Para uma exclusão em massa segura, sempre execute primeiro com dry_run=True para visualizar quais notebooks serão removidos. Considere renomear blocos de anotações com um _TO_DELETE prefixo em vez de excluí-los imediatamente, para que você possa recuperá-los, se necessário.

Listar blocos de anotações

Use notebookutils.notebook.list() para enumerar notebooks em um espaço de trabalho. Ele retorna uma matriz de Artifact objetos.

Parâmetros

Parâmetro Tipo Obrigatório Descrição
workspaceId String No ID do workspace. Deixe vazio para o espaço de trabalho atual.
maxResults int No Número máximo de resultados a serem retornados. O valor padrão é 1000.

Listar todos os notebooks no espaço de trabalho atual

notebooks = notebookutils.notebook.list()

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

Listar blocos de anotações em outro workspace

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

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

Valor de retorno

O list() método retorna uma matriz de Artifact objetos. Cada objeto contém displayName, ide description propriedades.

Filtrar notebooks por padrão de 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}")

Clonar um notebook

Use list() e getDefinition() em conjunto para clonar um notebook no mesmo workspace ou em outro workspace.

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

Migrar um notebook para outro workspace

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

Conteúdo relacionado

  • Last updated on