Utilidades de la biblioteca de variables NotebookUtils para Fabric

Las bibliotecas de variables le ayudan a evitar valores de codificación rígida en el código del cuaderno. En lugar de editar código, actualizará los valores de la biblioteca y los recuperará en tiempo de ejecución. Este patrón le ayuda a reutilizar cuadernos en equipos y proyectos mediante la centralización de la configuración.

En la tabla siguiente se enumeran los métodos de biblioteca de variables disponibles:

Definición de variables

Defina las variables de la biblioteca de variables antes de usar notebookutils.variableLibrary. Puede crear y administrar bibliotecas de variables a través de la interfaz de usuario de Fabric.

Recuperación de la biblioteca de variables

Use getLibrary() para recuperar toda la biblioteca como un objeto y, a continuación, acceda a variables como propiedades. Use la sintaxis getVariable('name') o library['name'] de corchetes cuando necesite acceso dinámico.

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

val samplevl = notebookutils.variableLibrary.getLibrary("sampleVL")

samplevl.test_int
samplevl.test_str

samplevl <- notebookutils.variableLibrary.getLibrary("sampleVL")

samplevl$test_int()
samplevl$test_str()

En el ejemplo siguiente se muestra cómo construir dinámicamente una ruta de acceso de archivo mediante valores de biblioteca de variables:

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)

Acceso a una sola variable por referencia

Use el get() método con el patrón $(/**/libraryName/variableName) de referencia para recuperar un único valor de variable. El valor se escribe automáticamente en función de la definición de variable.

notebookutils.variableLibrary.get("$(/**/samplevl/test_int)")
notebookutils.variableLibrary.get("$(/**/samplevl/test_str)")
notebookutils.variableLibrary.get("$(/**/samplevl/test_bool)")

notebookutils.variableLibrary.get("$(/**/samplevl/test_int)")
notebookutils.variableLibrary.get("$(/**/samplevl/test_str)")
notebookutils.variableLibrary.get("$(/**/samplevl/test_bool)")

notebookutils.variableLibrary.get("$(/**/samplevl/test_int)")
notebookutils.variableLibrary.get("$(/**/samplevl/test_str)")
notebookutils.variableLibrary.get("$(/**/samplevl/test_bool)")

Tipos de variables admitidos

Las bibliotecas de variables admiten los siguientes tipos de datos. Los valores se escriben automáticamente al recuperarlos; no es necesario convertirlos explícitamente en la mayoría de los casos.

Configuración específica del entorno

Las bibliotecas de variables admiten conjuntos de valores, que permiten definir conjuntos alternativos de valores para las mismas variables, por ejemplo, desarrollo, prueba y prod. Cada área de trabajo tiene un valor activo establecido a la vez y las canalizaciones de implementación pueden activar automáticamente el conjunto de valores adecuado por fase.

Este patrón elimina la necesidad de cambios de código al promover cuadernos entre entornos:

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

val appConfig = notebookutils.variableLibrary.getLibrary("app_config")

val apiEndpoint = appConfig.api_endpoint
val batchSize = appConfig.batch_size
val debugMode = appConfig.debug_enabled

println(s"API Endpoint: ${apiEndpoint}")
println(s"Batch Size: ${batchSize}")
println(s"Debug Mode: ${debugMode}")

if (debugMode) {
    println("Running in debug mode")
}

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(paste("API Endpoint:", api_endpoint))
print(paste("Batch Size:", batch_size))
print(paste("Debug Mode:", debug_mode))

if (debug_mode) {
    print("Running in debug mode")
}

Consideraciones

Tenga en cuenta las consideraciones siguientes:

• La notebookutils.variableLibrary API solo admite el acceso a las bibliotecas de variables dentro del mismo área de trabajo. No se admite el acceso entre áreas de trabajo.
• No se pueden recuperar bibliotecas de variables entre áreas de trabajo de cuadernos secundarios durante una ejecución de referencia.
• El código del cuaderno hace referencia a las variables definidas en el conjunto de valores activos de la biblioteca de variables. Para usar valores diferentes, active un conjunto de valores diferente en el área de trabajo o use canalizaciones de implementación para administrar conjuntos de valores para cada entorno.
• La entidad de servicio (Service Principal, SPN) no es compatible actualmente con las utilidades de la biblioteca de variables.
• Las bibliotecas de variables son de solo lectura cuando se accede desde los cuadernos. Realice cambios a través de la interfaz de usuario o las API de Fabric.
• Cada biblioteca admite hasta 1000 variables y 1000 conjuntos de valores, con un máximo de 10 000 celdas y un límite de tamaño de 1 MB.
• Los nombres de variables y bibliotecas son sensibles a mayúsculas y minúsculas. Use coincidencias exactas de nombres al hacer referencia a variables.

Contenido relacionado

• NotebookUtils for Fabric