Partilhar via

Gerir os artefactos do notebook com o NotebookUtils

Uso notebookutils.notebook para gerir itens de cadernos programaticamente no Microsoft Fabric. Pode criar, recuperar, atualizar, eliminar e listar artefatos de notebooks para automatizar a implementação, gerenciamento do ciclo de vida e fluxos de trabalho CI/CD.

Observação

Estas APIs são suportadas apenas em notebooks Fabric, não no Azure Synapse. Deve ter permissões apropriadas no espaço de trabalho alvo para cada operação.

A tabela seguinte lista os métodos disponíveis de gestão de cadernos:

Método Signature Descrição
create create(name, description, content, defaultLakehouse, defaultLakehouseWorkspace, workspaceId): Artifact Cria um novo caderno.
get get(name, workspaceId): Artifact Recupera um caderno pelo nome ou identificação.
getDefinition getDefinition(name, workspaceId, format): String Recupera a definição do caderno (conteúdo).
update update(name, newName, description, workspaceId): Artifact Atualiza os metadados do caderno.
updateDefinition updateDefinition(name, content, defaultLakehouse, defaultLakehouseWorkspace, workspaceId, environmentId, environmentWorkspaceId): bool Atualiza a definição do caderno e a casa do lago.
delete delete(name, workspaceId): Boolean Elimina um caderno.
list list(workspaceId, maxResults): Array[Artifact] Lista todos os cadernos num espaço de trabalho.

Criar um bloco de notas

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

Observação

Exemplos de fluxos de trabalho neste artigo que leem ou escrevem .ipynb ficheiros usam Python para I/O de ficheiros. As APIs principais notebookutils.notebook estão disponíveis em Python, PySpark, Scala e R, salvo indicação em contrário.

Parâmetros

Parâmetro Tipo Obrigatório Descrição
name Cordão Sim Nome de exibição para o novo notebook. Tem de ser único dentro do espaço de trabalho.
description Cordão No Descrição do caderno. O padrão é vazio.
content String, bytes ou dict Sim Conteúdo do bloco de notas em formato JSON válido .ipynb . Também pode ser bytes brutos ou um objeto dicionário. Não pode estar vazia.
defaultLakehouse Cordão No Nome ou ID do lakehouse predefinido a anexar.
defaultLakehouseWorkspace Cordão No ID do espaço de trabalho do "lakehouse" por predefinição. Deixe em branco para o espaço de trabalho atual.
workspaceId Cordão No ID do espaço de trabalho alvo. Deixe vazio para o espaço de trabalho atual.

Importante

O content parâmetro não pode estar vazio. Deve fornecer conteúdo em formato válido .ipynb ao criar um bloco de notas. No mínimo, forneça uma estrutura válida de caderno vazio:

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

Crie um caderno a partir de 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})")

Crie um caderno com um lakehouse por 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 devolve um Artifact objeto com as seguintes propriedades:

  • displayName: O nome de apresentação do notebook.
  • id: O identificador único do caderno criado.
  • description: A descrição do caderno.

Crie um caderno noutro 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}")

Crie vários cadernos a partir de 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")

Sugestão

Forneça nomes e descrições significativos para os seus cadernos para facilitar a sua localização. Use uma convenção de nomes consistente, como <Project>_<Purpose>_<Region> para implementações automatizadas.

Obtenha um caderno

Use notebookutils.notebook.get() para recuperar metadados do caderno por nome ou ID. Devolve um Artifact objeto com propriedades como displayName, id, e description.

Parâmetros

Parâmetro Tipo Obrigatório Descrição
name Cordão Sim Nome ou identificação do caderno a recuperar.
workspaceId Cordão No ID do espaço de trabalho. Deixe vazio para o espaço de trabalho atual.

Arranja um caderno 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}")

Obtenha um caderno em 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 devolve um Artifact objeto com as seguintes propriedades:

  • displayName: O nome de apresentação do notebook.
  • id: O identificador único.
  • description: A descrição do caderno.

Sugestão

Use get() antes das operações de atualização ou eliminação para verificar se o caderno alvo existe. Também pode usá-lo para verificar se o nome de um caderno já está em uso antes de criar um novo.

Obtenha uma definição de computador portátil.

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

Parâmetros

Parâmetro Tipo Obrigatório Descrição
name Cordão Sim Nome ou identificação do caderno.
workspaceId Cordão No ID do espaço de trabalho. Deixe vazio para o espaço de trabalho atual.
format Cordão No Formato de saída. O padrão é "ipynb".

Recuperar e guardar uma definição de caderno

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

Obtenha uma definição de caderno 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 devolve uma string contendo o conteúdo do caderno em .ipynb formato JSON.

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

Atualize um caderno

Usar notebookutils.notebook.update() para alterar metadados do caderno, como o nome de exibição e a descrição. Não modifica o conteúdo do caderno nem a configuração do lakehouse.

Parâmetros

Parâmetro Tipo Obrigatório Descrição
name Cordão Sim Nome ou ID atual do caderno.
newName Cordão Sim Novo nome de exibição para o caderno.
description Cordão No Descrição atualizada.
workspaceId Cordão No ID do espaço de trabalho. Deixe vazio para o espaço de trabalho atual.

Mudar o nome de um bloco de notas

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 devolve um Artifact objeto com as propriedades atualizadas.

Atualizar a definição de um caderno

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

Parâmetros

Parâmetro Tipo Obrigatório Descrição
name Cordão Sim Nome ou ID do caderno para atualizar.
content Cordão No Novo conteúdo do bloco de notas no formato .ipynb.
defaultLakehouse Cordão No Novo nome padrão do lakehouse.
defaultLakehouseWorkspace Cordão No ID do espaço de trabalho da nova lakehouse padrão. Deixe vazio para o espaço de trabalho atual.
workspaceId Cordão No ID do espaço de trabalho. Deixe vazio para o espaço de trabalho atual.
environmentId Cordão No ID de ambiente para anexar ao caderno.
environmentWorkspaceId Cordão No Identificador do ambiente do espaço de trabalho. Deixe vazio para o espaço de trabalho atual.

Observação

Os parâmetros environmentId e environmentWorkspaceId estão disponíveis apenas no tempo de execução do notebook Spark. Os cadernos Python não suportam estes parâmetros.

Atualizar conteúdo do caderno

# 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 tanto o conteúdo como 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 método updateDefinition() devolve True se a atualização for bem-sucedida ou False se falhar.

Sugestão

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

Eliminar um bloco de notas

Use notebookutils.notebook.delete() para remover permanentemente um caderno de um espaço de trabalho. Devolve True se a eliminação for bem-sucedida; caso contrário, devolve False.

Parâmetros

Parâmetro Tipo Obrigatório Descrição
name Cordão Sim Nome ou ID do caderno para eliminar.
workspaceId Cordão No ID do espaço de trabalho. Deixe vazio para o espaço de trabalho atual.

Importante

A eliminação é permanente. Cadernos apagados não podem ser recuperados. Verifique sempre o nome do caderno antes de o apagar e considere fazer uma cópia de segurança da definição do caderno com o getDefinition() primeiro.

Valor de retorno

O delete() método retorna True se a eliminação for bem-sucedida ou False se falhar.

Eliminar um bloco de notas

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

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

Limpar os cadernos em 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)

Sugestão

Para uma eliminação em massa segura, execute sempre com dry_run=True primeiro para pré-visualizar quais os notebooks que serão removidos. Considere renomear cadernos com o prefixo _TO_DELETE em vez de os apagar imediatamente, para poder recuperá-los se necessário.

Cadernos de lista

Use notebookutils.notebook.list() para enumerar cadernos num espaço de trabalho. Devolve um array de Artifact objetos.

Parâmetros

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

Liste todos os cadernos 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})")

Lista cadernos noutro espaço de trabalho

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 devolve um array de Artifact objetos. Cada objeto contém displayName, id, e description propriedades.

Filtrar cadernos por padrão de nomes

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

Clone um bloco de notas

Use list() e getDefinition() em conjunto para clonar um caderno dentro do mesmo espaço de trabalho ou para outro espaço de trabalho.

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 caderno para outro espaço de trabalho

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