Утилиты библиотеки переменных NotebookUtils для Fabric

Библиотеки переменных помогают избежать жесткого кодирования значений в коде записной книжки. Вместо редактирования кода вы обновляете значения в библиотеке и извлекаете их во время выполнения. Этот шаблон помогает повторно использовать записные книжки между командами и проектами путем централизованной настройки.

В следующей таблице перечислены доступные методы библиотеки переменных:

Метод Signature Описание
getLibrary getLibrary(variableLibraryName: String): VariableLibrary Извлекает объект библиотеки переменных. Доступ к переменным в виде свойств возвращаемого объекта, например library.variableName. Для динамического доступа можно использовать getVariable('name') или синтаксис скобок library['name'].
get get(variableReference: String): Any Извлекает одно значение переменной по его ссылочному пути в формате $(/**/libraryName/variableName). Префикс /**/ обязателен. Значение автоматически вводится в зависимости от определения переменной.

Определение переменных

Определите переменные в библиотеке переменных перед использованием notebookutils.variableLibrary. Вы можете создавать библиотеки переменных и управлять ими с помощью пользовательского интерфейса Fabric.

Снимок экрана: список переменных в библиотеке переменных.

Получение библиотеки переменных

Используется 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)")

Поддерживаемые типы переменных

Библиотеки переменных поддерживают следующие типы данных. Значения автоматически типизируются при их извлечении — в большинстве случаев их не нужно явно приводить.

Тип Описание Пример
String Текстовые значения. "my_connection_string"
Целое число Целые числа. 42
Boolean Булево значение истина/ложь. true
Число Десятичные числа. 3.14
DateTime Значения даты и времени в формате 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")

Рекомендации

Учитывайте следующие аспекты:

  • notebookutils.variableLibrary API поддерживает доступ только к библиотекам переменных в одной рабочей области. Доступ между рабочими областями не поддерживается.
  • Невозможно получить библиотеки переменных между рабочими областями в дочерних ноутбуках при выполнении контрольного запуска.
  • Код записной книжки ссылается на переменные, определенные в активном наборе значений библиотеки переменных. Чтобы использовать разные значения, активируйте другой набор значений в рабочей области или используйте конвейеры развертывания для управления наборами значений для каждой среды.
  • Субъект-служба (SPN) в настоящее время не поддерживается для служебных программ библиотек переменных.
  • Библиотеки переменных доступны только для чтения из записных книжек. Внесите изменения с помощью пользовательского интерфейса Fabric или API.
  • Каждая библиотека поддерживает до 1000 переменных и 1000 наборов значений, при этом не более 10 000 ячеек и ограничение размера 1 МБ.
  • Имена переменных и библиотек чувствительны к регистру. Используйте точное сопоставление имен при ссылке на переменные.

Подсказка

Используйте конвейеры развертывания для автоматической активации соответствующего набора значений для каждого этапа (dev, test, prod). Это устраняет необходимость вручную переключать наборы значений или изменять код при продвижении записных книжек в разных средах.

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

  • Last updated on