通过

Fabric 的 NotebookUtils 运行时上下文

用于 notebookutils.runtime 读取有关当前笔记本会话的上下文信息。 可以在不修改任何状态的情况下检索笔记本名称、工作区详细信息、默认 Lakehouse 配置、管道执行标志和引用运行层次结构等元数据。

使用运行时上下文来：

  • 动态配置 - 根据执行环境调整笔记本行为。
  • 条件逻辑 – 分支逻辑，具体取决于笔记本是在管道中运行还是以交互方式运行。
  • 调试和监视 – 在日志输出中包含上下文属性，并关联相关执行。
  • 审计日志 – 捕获用于合规和血统追踪的执行元数据。

注释

运行时上下文在 Python、PySpark、Scala 和 R 笔记本中可用。 上下文是只读的 ， 不能修改由 notebookutils.runtime.context它返回的任何属性。 某些属性仅在特定上下文中填充，例如引用运行或管道执行，否则可能会返回 null 或空值。

查看会话上下文

使用notebookutils.runtime.context查看当前会话的上下文信息，包括笔记本名称、默认Lakehouse、工作区信息，以及会话是否在管道中运行。

notebookutils.runtime.context

下表描述了可用的属性。

财产 类型 说明 可用性
currentNotebookName String 当前笔记本的名称。 全部上下文
currentNotebookId String 当前笔记本的唯一 ID。 全部上下文
currentWorkspaceName String 当前工作区的名称。 全部上下文
currentWorkspaceId String 当前工作区的 ID。 全部上下文
defaultLakehouseName String 默认数据湖库的显示名称（如果已定义）。 附加默认 Lakehouse 时
defaultLakehouseId String 默认 Lakehouse 的 ID（如果已定义）。 当附加默认的Lakehouse时
defaultLakehouseWorkspaceName String 默认 Lakehouse 的工作区名称（如果已定义）。 附加默认 Lakehouse 时
defaultLakehouseWorkspaceId String 默认的 Lakehouse 的工作区 ID（如果已定义）。 附加默认 Lakehouse 时
currentRunId String 在基准运行中，当前运行 ID。 仅参考运行
parentRunId String 在包含嵌套运行的引用运行中，此 ID 是父运行 ID。 仅嵌套引用运行
rootRunId String 在包含嵌套运行的引用运行中，此 ID 是根运行 ID。 仅嵌套引用运行
isForPipeline 布尔 运行是否用于管道。 全部上下文
isForInteractive 布尔 运行是否为交互式会话。 全部上下文
isReferenceRun 布尔 当前运行是否为引用运行。 全部上下文
referenceTreePath String 嵌套引用运行的树结构，仅用于 L2 页中的快照分层结构。 仅嵌套引用运行
rootNotebookId String 引用运行中根笔记本的ID。 仅用于参考的运行
rootNotebookName String 引用运行中的根笔记本的名称。 仅引用运行
rootWorkspaceId String 引用运行中根笔记本的工作区 ID。 参考性运行
rootWorkspaceName String 引用运行中根笔记本的工作区名称。 仅供参考运行
activityId String 当前活动的 Livy 作业 ID。 全部上下文
hcReplId String 高并发模式下的 REPL ID。 仅限高并发模式
clusterId String Synapse Spark 群集的标识。 全部上下文
poolName String 正在使用的 Spark 池的名称。 全部上下文
environmentId String 运行作业的环境 ID。 全部上下文
environmentWorkspaceId String 环境的工作区 ID。 全部上下文
userId String 当前用户的用户 ID。 全部上下文
userName String 当前用户的用户名。 全部上下文
currentKernel String 当前笔记本内核的名称。 仅 Python 笔记本
productType String 产品类型标识符（例如）。 Fabric 全部上下文

用法示例

访问基本上下文信息

需要读取多个属性时缓存上下文对象。

context = notebookutils.runtime.context

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

检查流水线与交互式执行

根据执行模式，使用 isForPipeline 标志对逻辑进行分支。 例如，可以在管道运行中应用更严格的错误处理。

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

小窍门

使用 isForPipeline 和 isReferenceRun 来为不同的执行上下文实现三向分支。 此模式可帮助你定制重试计数、日志记录详细程度和错误处理策略。 对于生产工作负荷，管道和引用运行通常需要比交互式会话更严格的错误处理。

检查参考运行层次结构

当笔记本作为嵌套引用运行的一部分运行时，可以从当前运行跟踪到根目录的完整层次结构：

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

在日志记录中包含上下文

使用执行上下文丰富日志消息，以便更轻松地进行调试和监视：

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