Partilhar via

Utilidades da biblioteca de variáveis NotebookUtils para Fabric

As bibliotecas de variáveis ajudam a evitar codificar valores fixos no código do caderno. Em vez de editar código, atualiza os valores na biblioteca e recupera-os em tempo de execução. Este padrão ajuda-te a reutilizar cadernos entre equipas e projetos, centralizando a configuração.

A tabela seguinte lista os métodos disponíveis na biblioteca de variáveis:

Método Signature Descrição
getLibrary getLibrary(variableLibraryName: String): VariableLibrary Recupera um objeto de biblioteca de variáveis. Variáveis de acesso como propriedades no objeto devolvido, como library.variableName. Pode-se usar getVariable('name') ou a sintaxe de colchetes library['name'] para acesso dinâmico.
get get(variableReference: String): Any Recupera um valor de uma única variável pelo seu caminho de referência no formato $(/**/libraryName/variableName). O /**/ prefixo é obrigatório. O valor é automaticamente tipado com base na definição da variável.

Definir variáveis

Defina as variáveis na sua biblioteca de variáveis antes de usar notebookutils.variableLibrary. Pode criar e gerir bibliotecas de variáveis através da interface do Fabric.

Captura de tela da lista de variáveis na biblioteca de variáveis.

Recuperar biblioteca de variáveis

Use getLibrary() para recuperar toda a biblioteca como objeto, e depois aceder a variáveis como propriedades. Usa getVariable('name') a sintaxe library['name'] dos parênteses quando precisas de acesso 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"]

O exemplo seguinte mostra como construir dinamicamente um caminho de ficheiro usando valores de biblioteca variável:

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)

Aceda a uma única variável por referência

Use o get() método com o padrão $(/**/libraryName/variableName) de referência para recuperar um valor de uma única variável. O valor é automaticamente tipado com base na definição da variável.

Importante

O /**/ prefixo é obrigatório no padrão de referência. O padrão completo deve ser $(/**/libraryName/variableName), onde libraryName é o nome exato do item da biblioteca da variável e variableName é a variável definida nessa biblioteca. Os nomes diferenciam maiúsculas de minúsculas.

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

Tipos de variáveis suportados

As bibliotecas de variáveis suportam os seguintes tipos de dados. Os valores são automaticamente digitados quando os recupera — na maioria dos casos, não é necessário lançá-los explicitamente.

Tipo Descrição Exemplo
String Valores de texto. "my_connection_string"
Inteiro Números inteiros. 42
Booleano Boolean verdadeiro/falso. true
Número Números decimais. 3.14
DateTime Valores de data e hora no formato ISO 8601. "2025-01-15T08:30:00Z"
Guid Identificadores globalmente únicos. "123e4567-e89b-12d3-a456-426614174000"
Referência do item Referências a componentes "Fabric" suportados. "workspace/item"

Configuração específica do ambiente

As bibliotecas de variáveis suportam conjuntos de valores, que permitem definir conjuntos alternativos de valores para as mesmas variáveis — por exemplo, dev, test e prod. Cada espaço de trabalho tem um conjunto de valores ativos de cada vez, e os pipelines de implementação podem ativar automaticamente o conjunto de valores apropriado por etapa.

Este padrão elimina a necessidade de alterações de código quando se promovem cadernos entre ambientes:

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

Considerações

Tenha estas considerações em mente:

  • A notebookutils.variableLibrary API só suporta acesso a bibliotecas de variáveis dentro do mesmo espaço de trabalho. O acesso entre espaços de trabalho não é suportado.
  • Não é possível recuperar bibliotecas de variáveis entre espaços de trabalho em cadernos filhos numa execução de referência.
  • O código do caderno refere-se às variáveis definidas no conjunto de valores ativo da biblioteca de variáveis. Para usar valores diferentes, ative um conjunto de valores diferente no espaço de trabalho ou utilize pipelines de implementação para gerir conjuntos de valores para cada ambiente.
  • O Service Principal (SPN) não é atualmente suportado para utilitários de bibliotecas variáveis.
  • As bibliotecas de variáveis apenas podem ser lidas a partir de notebooks. Faça alterações através da interface ou APIs do Fabric.
  • Cada biblioteca suporta até 1.000 variáveis e 1.000 conjuntos de valores, com um máximo de 10.000 células e um limite de tamanho de 1 MB.
  • Os nomes das variáveis e das bibliotecas são diferenciados em maiúsculas e minúsculas. Use a correspondência exata de nomes quando referenciar variáveis.

Sugestão

Use pipelines de implementação para ativar automaticamente o conjunto de valores apropriado para cada etapa (desenvolvimento, teste, produção). Isto elimina a necessidade de alternar manualmente conjuntos de valores ou modificar código ao promover notebooks entre ambientes.

Conteúdo relacionado

  • Last updated on