在笔记本代码中，使用变量库可以帮助避免硬编码值。 无需编辑代码，而是更新库中的值并在运行时检索它们。 此模式通过集中配置帮助跨团队和项目重复使用笔记本。
下表列出了可用的变量库方法：
| 方法 | Signature | 说明 |
|---|---|---|
getLibrary |
getLibrary(variableLibraryName: String): VariableLibrary |
检索变量库对象。 将变量作为返回对象的属性来访问，例如 library.variableName。 可以使用 getVariable('name') 或括号语法 library['name'] 进行动态访问。 |
get |
get(variableReference: String): Any |
按其引用路径检索单个变量的值$(/**/libraryName/variableName)。 需要 /**/ 前缀。 该值根据变量定义自动键入。 |
定义变量
使用 notebookutils.variableLibrary前在变量库中定义变量。 可以通过 Fabric UI 创建和管理变量库。
检索变量库
使用 getLibrary() 将整个库检索为对象，然后访问变量作为属性。 需要动态访问时，请使用 getVariable('name') 或括号语法 library['name'] 。
samplevl = notebookutils.variableLibrary.getLibrary("sampleVL")
# Property access
samplevl.test_int
samplevl.test_str
# Method access (useful for dynamic variable names)
samplevl.getVariable("test_int")
# Bracket access
samplevl["test_int"]
以下示例演示如何使用变量库值动态构造文件路径：
samplevl = notebookutils.variableLibrary.getLibrary("sampleVL")
file_path = f"abfss://{samplevl.Workspace_name}@onelake.dfs.fabric.microsoft.com/{samplevl.Lakehouse_name}.Lakehouse/Files/<FileName>.csv"
df = spark.read.format("csv").option("header","true").load(file_path)
display(df)
按引用访问单个变量
使用get()方法与引用模式$(/**/libraryName/variableName)获取单个变量的值。 该值根据变量定义自动键入。
重要
引用模式中必须包含/**/前缀。 完整模式必须是 $(/**/libraryName/variableName)，其中 libraryName 确切的变量库项名称是 variableName 该库中定义的变量。 名称区分大小写。
notebookutils.variableLibrary.get("$(/**/samplevl/test_int)")
notebookutils.variableLibrary.get("$(/**/samplevl/test_str)")
notebookutils.variableLibrary.get("$(/**/samplevl/test_bool)")
支持的变量类型
变量库支持以下数据类型。 检索值时会自动键入值 ，在大多数情况下不需要显式强制转换它们。
| 类型 | 说明 | 示例 |
|---|---|---|
| 字符串 | 文本值。 | "my_connection_string" |
| 整数 | 整数。 | 42 |
| 布尔值 | 布尔值 true/false。 | true |
| 数字 | 十进制数。 | 3.14 |
| 日期时间 | 采用 ISO 8601 格式的日期和时间值。 | "2025-01-15T08:30:00Z" |
| GUID | 全局唯一标识符。 | "123e4567-e89b-12d3-a456-426614174000" |
| 项目参考 | 与支持的 Fabric 项相关的引用。 | "workspace/item" |
环境特定的配置
变量库支持 值集，这使你可以为同一变量定义替代值集，例如开发、测试和生产。每个工作区一次设置一个活动值，部署管道可以自动激活每个阶段设置的相应值。
在跨环境推广笔记本时，此模式无需更改代码：
# These values change based on the active value set (dev/test/prod)
app_config = notebookutils.variableLibrary.getLibrary("app_config")
api_endpoint = app_config.api_endpoint
batch_size = app_config.batch_size
debug_mode = app_config.debug_enabled
print(f"API Endpoint: {api_endpoint}")
print(f"Batch Size: {batch_size}")
print(f"Debug Mode: {debug_mode}")
if debug_mode:
print("Running in debug mode")
注意事项
请记住以下注意事项：
- API
notebookutils.variableLibrary仅支持访问同一工作区中的变量库。 不支持跨工作区访问。 - 在引用执行时，无法在子笔记本中跨工作区检索变量库。
- 笔记本代码引用变量库的活动值集中定义的变量。 若要使用不同的值，请激活工作区中的不同值集，或使用部署管道管理每个环境的值集。
- 变量库实用工具当前不支持服务主体（SPN）。
- 变量库是笔记本中的只读库。 通过 Fabric UI 或 API 进行更改。
- 每个库最多支持 1,000 个变量和 1,000 个值集，最多包含 10,000 个单元格和 1 MB 大小限制。
- 变量和库名称区分大小写。 引用变量时，请使用确切的名称匹配。
小窍门
使用部署管道自动激活每个阶段（开发、测试、生产）相应的值集。 这样就无需在跨环境推广笔记本时手动切换值集或修改代码。