Контекст среды выполнения NotebookUtils для Fabric

Используйте notebookutils.runtime, чтобы прочитать сведения о контексте текущего сеанса блокнота. Вы можете получить метаданные, такие как имя записной книжки, сведения о рабочей области, конфигурация lakehouse по умолчанию, флаги выполнения конвейера и эталонная иерархия запуска без изменения состояния.

Использование контекста среды выполнения для:

• Динамическая конфигурация — адаптация поведения записной книжки в зависимости от среды выполнения.
• Условная логика — ветвление логики в зависимости от того, выполняется ли записная книжка в конвейере или интерактивно.
• Отладка и мониторинг — включение свойств контекста в выходные данные журнала и сопоставление связанных выполнений.
• Журналы аудита — сбор метаданных о выполнении для обеспечения отслеживания соответствия и происхождения данных.

Замечание

Контекст среды выполнения доступен в записных книжках Python, PySpark, Scala и R. Контекст доступен только для чтения. Вы не можете изменить какие-либо свойства, возвращаемые notebookutils.runtime.context. Некоторые свойства заполняются только в определённых контекстах, таких как запуски ссылок или выполнение конвейера, а в остальных случаях могут возвращать null или пустые значения.

Просмотр контекста сеанса

Используйте notebookutils.runtime.context, чтобы просмотреть сведения о контексте текущего сеанса, включая имя записной книжки, данные о lakehouse по умолчанию, сведения о рабочей области и информацию о том, выполняется ли сеанс в конвейере.

Python

notebookutils.runtime.context

Scala

notebookutils.runtime.context

R

notebookutils.runtime.context()

В следующей таблице описываются доступные свойства.

Недвижимость	Тип	Описание	Availability
currentNotebookName	String	Имя текущей записной книжки.	Все контексты
currentNotebookId	String	Уникальный идентификатор текущей записной книжки.	Все контексты
currentWorkspaceName	String	Имя текущей рабочей области.	Все контексты
currentWorkspaceId	String	Идентификатор текущей рабочей области.	Все контексты
defaultLakehouseName	String	Отображаемое имя озера по умолчанию, если определено.	Когда lakehouse по умолчанию присоединён
defaultLakehouseId	String	Идентификатор озера по умолчанию, если определен.	Когда lakehouse по умолчанию присоединён
defaultLakehouseWorkspaceName	String	Имя рабочей области lakehouse по умолчанию, если определено.	Когда lakehouse по умолчанию присоединён
defaultLakehouseWorkspaceId	String	Идентификатор рабочего пространства lakehouse по умолчанию, если определен.	Когда lakehouse по умолчанию присоединён
currentRunId	String	В эталонном запуске текущий идентификатор выполнения.	Только контрольные запуски
parentRunId	String	При эталонном запуске с вложенными запусками этот идентификатор является идентификатором родительского запуска.	Только вложенные ссылки выполняются
rootRunId	String	В эталонном запуске с вложенными запусками этот идентификатор является идентификатором корневого запуска.	Только вложенные ссылки выполняются
isForPipeline	Boolean	Указывает, является ли данный процесс запуском для конвейера.	Все контексты
isForInteractive	Boolean	Является ли запуск интерактивным сеансом.	Все контексты
isReferenceRun	Boolean	Указывает, является ли текущий запуск эталонным.	Все контексты
referenceTreePath	String	Структура дерева вложенных референсных запусков, используемая только для иерархии моментальных снимков на L2 странице мониторинга.	Только вложенные ссылки выполняются
rootNotebookId	String	Идентификатор корневой записной книжки в эталонном запуске.	Только контрольные запуски
rootNotebookName	String	Имя корневой записной книжки в эталонном запуске.	Только контрольные запуски
rootWorkspaceId	String	Идентификатор рабочей области корневой записной книжки в контрольном запуске.	Только контрольные запуски
rootWorkspaceName	String	Название рабочей области корневого блокнота в эталонном запуске.	Только контрольные запуски
activityId	String	Идентификатор задания Livy для текущего действия.	Все контексты
hcReplId	String	Идентификатор REPL в режиме высокой конкурентности.	Только режим высокой параллелизма
clusterId	String	Идентичность кластера Azure Synapse Spark.	Все контексты
poolName	String	Имя используемого пула Spark.	Все контексты
environmentId	String	Идентификатор среды, в которой выполняется задание.	Все контексты
environmentWorkspaceId	String	Идентификатор рабочей области среды.	Все контексты
userId	String	Идентификатор пользователя текущего пользователя.	Все контексты
userName	String	Имя текущего пользователя.	Все контексты
currentKernel	String	Имя текущего ядра записной книжки.	Только для Python notebook
productType	String	Идентификатор типа продукта (например, Fabric).	Все контексты

Примеры использования

Доступ к базовым сведениям о контексте

Кэшируйте объект контекста при необходимости считывания нескольких свойств.

Python

context = notebookutils.runtime.context

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

Scala

val context = notebookutils.runtime.context

println(s"Notebook: ${context("currentNotebookName")}")
println(s"Workspace: ${context("currentWorkspaceName")}")

R

context <- notebookutils.runtime.context()

cat(paste("Notebook:", context$currentNotebookName, "\n"))
cat(paste("Workspace:", context$currentWorkspaceName, "\n"))

Проверка конвейера по сравнению с интерактивным выполнением

Используйте флаг isForPipeline для ветвления логики в зависимости от режима работы. Например, можно применить более строгую обработку ошибок в запусках конвейера.

Python

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

Scala

val context = notebookutils.runtime.context

if (context("isForPipeline").asInstanceOf[Boolean]) {
    println("Pipeline mode: Strict error handling")
} else if (context("isReferenceRun").asInstanceOf[Boolean]) {
    println("Running as a referenced notebook")
} else {
    println("Interactive mode: Lenient error handling")
}

R

context <- notebookutils.runtime.context()

if (context$isForPipeline) {
    print("Pipeline mode: Strict error handling")
} else if (context$isReferenceRun) {
    print("Running as a referenced notebook")
} else {
    print("Interactive mode: Lenient error handling")
}

Подсказка

Используйте isForPipeline и isReferenceRun вместе для реализации трехстороннего ветвления для различных контекстов выполнения. Этот шаблон помогает настроить количество повторных попыток, подробное ведение журнала и стратегии обработки ошибок. Для производственных нагрузок пайплайны и эталонные прогоны обычно требуют более строгого управления ошибками, чем интерактивные сессии.

Проверка эталонной иерархии выполнения

Когда записная книжка выполняется в рамках вложенного ссылочного запуска, можно отслеживать полную иерархию от текущего запуска до корня.

Python

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

Scala

val context = notebookutils.runtime.context

if (context("isReferenceRun").asInstanceOf[Boolean]) {
    println("Reference Run Context:")
    println(s"  Current Run ID: ${context("currentRunId")}")
    println(s"  Parent Run ID: ${context("parentRunId")}")
    println(s"  Root Run ID: ${context("rootRunId")}")
    println(s"  Root Notebook: ${context("rootNotebookName")}")
} else {
    println("Not a reference run")
}

R

context <- notebookutils.runtime.context()

if (context$isReferenceRun) {
    print("Reference Run Context:")
    print(paste("Current Run ID:", context$currentRunId))
    print(paste("Parent Run ID:", context$parentRunId))
    print(paste("Root Run ID:", context$rootRunId))
    print(paste("Root Notebook:", context$rootNotebookName))
} else {
    print("Not a reference run")
}

Учет контекста в ведении журнала

Обогащение сообщений журнала с помощью контекста выполнения для упрощения отладки и мониторинга:

Python

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

Scala

val context = notebookutils.runtime.context

val logPrefix = s"[${context("currentWorkspaceName")}/${context("currentNotebookName")}] run=${context.getOrElse("currentRunId", "interactive")}"

println(s"${logPrefix} Processing started")

R

context <- notebookutils.runtime.context()

run_id <- if (!is.null(context$currentRunId) && nzchar(context$currentRunId)) context$currentRunId else "interactive"
log_prefix <- paste0("[", context$currentWorkspaceName, "/", context$currentNotebookName, "] run=", run_id)

print(paste(log_prefix, "Processing started"))

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

• NotebookUtils для Fabric