Utilità della libreria di variabili NotebookUtils per Fabric

Le librerie delle variabili consentono di evitare l'uso di valori hardcoded nel codice del notebook. Anziché modificare il codice, aggiornare i valori nella libreria e recuperarli in fase di esecuzione. Questo modello consente di riutilizzare i notebook tra team e progetti centralizzando la configurazione.

Nella tabella seguente sono elencati i metodi disponibili per la libreria di variabili:

Definire le variabili

Definire le variabili nella libreria di variabili prima di usare notebookutils.variableLibrary. È possibile creare e gestire librerie di variabili tramite l'interfaccia utente di Fabric.

Recuperare la libreria di variabili

Usare getLibrary() per recuperare l'intera libreria come oggetto e quindi accedere alle variabili come proprietà. Usare getVariable('name') o la sintassi library['name'] tra parentesi quadre quando è necessario l'accesso dinamico.

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

Nell'esempio seguente viene illustrato come costruire in modo dinamico un percorso di file usando i valori della libreria di variabili:

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)

Accedere a una singola variabile in base al riferimento

Usare il get() metodo con il modello $(/**/libraryName/variableName) di riferimento per recuperare un singolo valore di variabile. Il valore viene tipizzato automaticamente in base alla definizione della variabile.

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

Tipi di variabili supportati

Le librerie di variabili supportano i tipi di dati seguenti. I valori vengono digitati automaticamente quando vengono recuperati. Non è necessario eseguirne il cast in modo esplicito nella maggior parte dei casi.

Configurazione specifica dell'ambiente

Le librerie di variabili supportano i set di valori, che consentono di definire set alternativi di valori per le stesse variabili, ad esempio sviluppo, test e produzione. Ogni area di lavoro ha un valore attivo impostato alla volta e le pipeline di distribuzione possono attivare automaticamente il valore appropriato impostato per fase.

Questo modello elimina la necessità di modifiche al codice quando si alzano di livello i notebook in ambienti diversi:

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

Considerazioni

Tenere presenti queste considerazioni:

• L'API notebookutils.variableLibrary supporta solo l'accesso alle librerie di variabili all'interno della stessa area di lavoro. L'accesso tra aree di lavoro non è supportato.
• Non è possibile recuperare librerie di variabili tra aree di lavoro nei notebook secondari durante un'esecuzione di riferimento.
• Il codice del notebook fa riferimento alle variabili definite nel set di valori attivi della libreria di variabili. Per usare valori diversi, attivare un valore diverso impostato nell'area di lavoro o usare le pipeline di distribuzione per gestire i set di valori per ogni ambiente.
• Il principale del servizio (SPN) non è attualmente supportato per le utilità della libreria di variabili.
• Le librerie di variabili sono di sola lettura dai notebook. Apportare modifiche tramite l'interfaccia utente o le API di Fabric.
• Ogni libreria supporta fino a 1.000 variabili e 1.000 set di valori, con un massimo di 10.000 celle e un limite di dimensioni di 1 MB.
• I nomi delle variabili e delle librerie fanno distinzione tra maiuscole e minuscole. Usa la corrispondenza esatta dei nomi quando fai riferimento alle variabili.

Contenuti correlati

• NotebookUtils per Fabric