Partilhar via

Contexto de execução NotebookUtils para Fabric

Use notebookutils.runtime para ler informações de contexto sobre a sessão atual do caderno. Pode recuperar metadados como o nome do caderno, 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 modificar qualquer estado.

Usar o contexto de execução para:

  • Configuração dinâmica – Adapte o comportamento do caderno com base no ambiente de execução.
  • Lógica condicional – Lógica de ramificação dependendo se o notebook corre num pipeline ou de forma interativa.
  • Depuração e monitorização – Incluir propriedades de contexto na saída do log e correlacionar execuções relacionadas.
  • Registos de auditoria – Recolha metadados de execução para conformidade e rastreio de linhagem.

Observação

O contexto em tempo de execução está disponível em notebooks Python, PySpark, Scala e R. O contexto é apenas de leitura — não pode modificar nenhuma das propriedades devolvidas 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 devolver null ou valores vazios caso contrário.

Ver contexto da sessão

Use notebookutils.runtime.context para visualizar a informação de contexto da sessão atual, incluindo o nome do caderno, o lakehouse padrão, as informações do espaço de trabalho e se a sessão é executada em um pipeline.

notebookutils.runtime.context

A tabela seguinte descreve as propriedades disponíveis.

Propriedade Tipo Descrição Availability
currentNotebookName Cordão O nome do caderno atual. Todos os contextos
currentNotebookId Cordão O identificador único do caderno atual. Todos os contextos
currentWorkspaceName Cordão O nome do espaço de trabalho atual. Todos os contextos
currentWorkspaceId Cordão O identificador do espaço de trabalho atual. Todos os contextos
defaultLakehouseName Cordão O nome de exibição do lakehouse predefinido, se definido. Quando o lakehouse predefinido está anexado
defaultLakehouseId Cordão O identificador do lakehouse padrão, se definido. Quando o lakehouse predefinido está anexado
defaultLakehouseWorkspaceName Cordão O nome do espaço de trabalho do lakehouse padrão, caso esteja definido. Quando a casa do lago por defeito está anexada
defaultLakehouseWorkspaceId Cordão O ID do espaço de trabalho do lakehouse padrão, se definido. Quando o lakehouse padrão está ligado
currentRunId Cordão Durante uma execução de referência, o ID de execução atual. Apenas corridas de referência
parentRunId Cordão Numa execução de referência com execuções aninhadas, este ID é o ID da execução principal. Apenas execuções de referência aninhada
rootRunId Cordão Numa execução referencial com execuções aninhadas, este ID é o ID raiz da execução. Apenas execuções de referência aninhada
isForPipeline booleano Se a execução é para um pipeline. Todos os contextos
isForInteractive booleano Se a corrida é uma sessão interativa. Todos os contextos
isReferenceRun booleano Seja a execução atual uma execução de referência. Todos os contextos
referenceTreePath Cordão A estrutura em árvore das referências aninhadas é usada apenas para a hierarquia de instantâneos na página L2 de monitorização. Apenas execuções de referência aninhada
rootNotebookId Cordão A ID do notebook raiz numa execução de referência. Apenas corridas de referência
rootNotebookName Cordão O nome do caderno raiz numa execução de referência. Apenas corridas de referência
rootWorkspaceId Cordão O ID do espaço de trabalho do notebook raiz numa execução de referência. Apenas corridas de referência
rootWorkspaceName Cordão O nome do espaço de trabalho do caderno raiz num processo de referência. Apenas corridas de referência
activityId Cordão O identificador de trabalho Livy para a atividade atual. Todos os contextos
hcReplId Cordão O ID REPL no modo de alta concorrência. Apenas modo de alta concorrência
clusterId Cordão A identidade do cluster Synapse Spark. Todos os contextos
poolName Cordão O nome da piscina Spark é usado. Todos os contextos
environmentId Cordão O ID do ambiente onde o trabalho está a correr. Todos os contextos
environmentWorkspaceId Cordão O ID de espaço de trabalho do ambiente. Todos os contextos
userId Cordão O identificador do utilizador atual. Todos os contextos
userName Cordão O nome de utilizador do utilizador corrente. Todos os contextos
currentKernel Cordão O nome do kernel atual do notebook. Somente Python Notebook
productType Cordão O identificador do tipo de produto (por exemplo, Fabric). Todos os contextos

Exemplos de utilização

Aceder a informações básicas de contexto

Armazena em cache o objeto de contexto quando precisares de 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'}")

Comparar pipeline contra execução interativa

Utilize o indicador isForPipeline para desviar a lógica dependendo do modo de execução. Por exemplo, pode aplicar um tratamento de erros 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

Sugestão

Utilize isForPipeline e isReferenceRun juntos para implementar ramificações de três vias para diferentes contextos de execução. Este padrão ajuda-te a personalizar a contagem de repetições, a verbosidade dos registos e estratégias de gestão de erros. Para cargas de trabalho em produção, as execuções de pipeline e de referência normalmente exigem um tratamento de erros mais rigoroso do que sessões interativas.

Inspecionar a hierarquia de execuções de referência

Quando um notebook é executado como parte de uma execução de referência em cascata, pode rastrear a hierarquia completa desde a execução atual até à origem.

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 nos logs

Enriquecer mensagens de registo com contexto de execução para facilitar a depuração e monitorização:

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