Compartilhar via

Contexto de tempo de execução do NotebookUtils para o Fabric

Use notebookutils.runtime para ler informações de contexto sobre a sessão atual do notebook. Você pode recuperar metadados como o nome do notebook, detalhes do espaço de trabalho, configuração padrão do lakehouse, flags de execução do pipeline e hierarquia de execução de referência sem alterar nenhum estado.

Use o contexto de runtime para:

  • Configuração dinâmica – adaptar o comportamento do notebook com base no ambiente de execução.
  • Lógica condicional – lógica de ramificação dependendo se o notebook é executado em um pipeline ou interativamente.
  • Depuração e monitoramento – inclua propriedades de contexto na saída do log e correlacione as execuções relacionadas.
  • Trilhas de auditoria – capturar metadados de execução para conformidade e acompanhamento de linhagem.

Observação

O contexto de runtime está disponível em blocos de anotações Python, PySpark, Scala e R. O contexto é somente leitura– você não pode modificar nenhuma das propriedades retornadas por notebookutils.runtime.context. Algumas propriedades são preenchidas apenas em contextos específicos, como execuções de referência ou execuções de pipeline, e podem retornar null ou retornar valores vazios de outra forma.

Exibir contexto de sessão

Use notebookutils.runtime.context para exibir informações de contexto para a sessão atual, incluindo o nome do notebook, o lakehouse padrão, as informações do workspace e se a sessão está sendo executada em um pipeline.

notebookutils.runtime.context

A tabela a seguir descreve as propriedades disponíveis.

Propriedade Tipo Descrição Disponibilidade
currentNotebookName String O nome do bloco de anotações atual. Todos os contextos
currentNotebookId String A ID exclusiva do notebook atual. Todos os contextos
currentWorkspaceName String O nome do espaço de trabalho atual. Todos os contextos
currentWorkspaceId String O ID do espaço de trabalho atual. Todos os contextos
defaultLakehouseName String O nome de exibição do lakehouse padrão, se definido. Quando o lakehouse padrão é anexado
defaultLakehouseId String O ID do lakehouse padrão, caso esteja definido. Quando o sistema lakehouse padrão está conectado
defaultLakehouseWorkspaceName String O nome do espaço de trabalho do lakehouse padrão, se definido. Quando o lakehouse padrão é anexado
defaultLakehouseWorkspaceId String O ID do espaço de trabalho do lakehouse padrão, se definido. Quando o lakehouse padrão está conectado
currentRunId String Em uma execução de referência, a ID de execução atual. Somente execuções de referência
parentRunId String Em uma execução de referência com execuções aninhadas, esta ID é a ID principal. Apenas execuções de referência aninhadas
rootRunId String Em uma execução de referência com execuções aninhadas, essa ID é a ID da execução raiz. Somente execuções de referência aninhadas
isForPipeline booleano Se a execução é para um pipeline. Todos os contextos
isForInteractive booleano Se a execução é uma sessão interativa. Todos os contextos
isReferenceRun booleano Se a execução atual é uma execução de referência. Todos os contextos
referenceTreePath String A estrutura em árvore de execuções de referência aninhadas, usada somente para a hierarquia de snapshots na página de monitoramento L2. Apenas execuções de referência aninhadas
rootNotebookId String A ID do notebook raiz em uma execução de referência. Somente execuções de referência
rootNotebookName String O nome do notebook raiz em uma execução de referência. Somente execuções de referência
rootWorkspaceId String A ID do workspace do notebook raiz em uma execução de referência. Somente execuções de referência
rootWorkspaceName String O nome do workspace do notebook principal em uma execução de referência. Somente execuções de referência
activityId String A ID do trabalho do Livy para a atividade atual. Todos os contextos
hcReplId String O ID do REPL no modo de alta concorrência. Somente modo de alta simultaneidade
clusterId String A identidade do cluster Spark do Synapse. Todos os contextos
poolName String O nome do pool do Spark que está sendo usado. Todos os contextos
environmentId String A ID do ambiente em que o trabalho está em execução. Todos os contextos
environmentWorkspaceId String O ID do espaço de trabalho do ambiente. Todos os contextos
userId String A ID do usuário atual. Todos os contextos
userName String O nome de usuário do usuário atual. Todos os contextos
currentKernel String O nome do kernel do notebook atual. Notebook Python somente
productType String O identificador de tipo de produto (por exemplo, Fabric). Todos os contextos

Exemplos de uso

Acessar informações básicas de contexto

Armazene em cache o objeto de contexto quando precisar ler várias propriedades.

context = notebookutils.runtime.context

print(f"Notebook: {context['currentNotebookName']}")
print(f"Workspace: {context['currentWorkspaceName']}")
print(f"Lakehouse: {context['defaultLakehouseName'] or 'None'}")

Verificar pipeline versus execução interativa

Use o isForPipeline sinalizador para ramificar a lógica dependendo do modo de execução. Por exemplo, você pode aplicar um tratamento de erro mais rigoroso em execuções de pipeline.

context = notebookutils.runtime.context

if context['isForPipeline']:
    print("Pipeline mode: Strict error handling")
    error_handling = "strict"
    max_retries = 3
elif context['isReferenceRun']:
    print("Running as a referenced notebook")
    error_handling = "strict"
    max_retries = 2
else:
    print("Interactive mode: Lenient error handling")
    error_handling = "lenient"
    max_retries = 1

Dica

Use isForPipeline e isReferenceRun em conjunto para implementar ramificação de três vias para diferentes contextos de execução. Esse padrão ajuda você a adaptar a contagem de repetições, a verbosidade de registros e as estratégias de tratamento de erros. Para cargas de trabalho de produção, as execuções de pipeline e referência normalmente exigem tratamento de erros mais rigoroso do que sessões interativas.

Verificar a hierarquia da execução de referência

Quando um notebook é executado como parte de uma execução de referência aninhada, você pode rastrear a hierarquia completa da execução atual até a raiz:

context = notebookutils.runtime.context

if context['isReferenceRun']:
    print("Reference Run Context:")
    print(f"  Current Run ID: {context['currentRunId']}")
    print(f"  Parent Run ID: {context['parentRunId']}")
    print(f"  Root Run ID: {context['rootRunId']}")
    print(f"  Root Notebook: {context['rootNotebookName']}")
else:
    print("Not a reference run")

Incluir contexto no registro em log

Enriquecer as mensagens de log com o contexto de execução para facilitar a depuração e o monitoramento.

context = notebookutils.runtime.context

run_id = context.get("currentRunId") or "interactive"
log_prefix = (
    f"[{context['currentWorkspaceName']}/{context['currentNotebookName']}]"
    f" run={run_id}"
)

print(f"{log_prefix} Processing started")
  • Last updated on