Compartilhar via

Utilitários da biblioteca de variáveis NotebookUtils para Fabric

Bibliotecas de variáveis ajudam você a evitar valores fixos dentro do código do notebook. Em vez de editar o código, você atualiza os valores na biblioteca e os recupera em tempo de execução. Esse padrão ajuda você a reutilizar notebooks entre equipes e projetos centralizando a configuração.

A tabela a seguir lista os métodos de biblioteca de variáveis disponíveis:

Método Signature Descrição
getLibrary getLibrary(variableLibraryName: String): VariableLibrary Recupera um objeto de biblioteca de variáveis. Acessar variáveis como propriedades no objeto retornado, como library.variableName. Você pode usar getVariable('name') ou sintaxe library['name'] de colchete para acesso dinâmico.
get get(variableReference: String): Any Recupera um único valor de variável por seu caminho de referência no formato $(/**/libraryName/variableName). O /**/ prefixo é necessário. O valor é digitado automaticamente com base na definição da variável.

Definir variáveis

Defina as variáveis em sua biblioteca de variáveis antes de usar notebookutils.variableLibrary. Você pode criar e gerenciar bibliotecas de variáveis por meio da interface do usuário 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 um objeto e, em seguida, acessar variáveis como propriedades. Use getVariable('name') ou sintaxe library['name'] de colchete quando precisar 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 a seguir mostra como construir dinamicamente um caminho de arquivo 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)

Acessar uma única variável por referência

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

Importante

O /**/ prefixo é necessário no padrão de referência. O padrão completo deve ser $(/**/libraryName/variableName), onde libraryName está o nome exato do item da biblioteca de variáveis e variableName é a variável definida nessa biblioteca. Os nomes diferenciam minúsculas e maiú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 dão suporte aos seguintes tipos de dados. Os valores são tipados automaticamente quando você os recupera; não é necessário convertê-los explicitamente na maioria dos casos.

Tipo Descrição Exemplo
String Valores de texto. "my_connection_string"
Inteiro Números inteiros. 42
Boolean Booliano 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 exclusivos. "123e4567-e89b-12d3-a456-426614174000"
Referência de item Referências aos itens compatíveis do Fabric. "workspace/item"

Configuração específica do ambiente

As bibliotecas de variáveis dão suporte a conjuntos de valores, que permitem definir conjuntos alternativos de valores para as mesmas variáveis, por exemplo, desenvolvimento, teste e prod. Cada workspace tem um valor ativo definido por vez e os pipelines de implantação podem ativar automaticamente o conjunto de valores apropriado por estágio.

Esse padrão elimina a necessidade de alterações de código ao promover notebooks em diferentes 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

Lembre-se do seguinte:

  • A notebookutils.variableLibrary API dá suporte apenas ao acesso a bibliotecas de variáveis no mesmo workspace. Não há suporte para acesso entre espaços de trabalho.
  • Não é possível recuperar variáveis de biblioteca entre workspaces em notebooks filhos durante uma execução de referência.
  • O código do notebook faz referência às variáveis definidas no conjunto de valores ativos da biblioteca de variáveis. Para usar valores diferentes, ative um conjunto de valores diferente no workspace ou use pipelines de implantação para gerenciar conjuntos de valores para cada ambiente.
  • Atualmente, não há suporte para SPN (Entidade de Serviço) para utilitários de biblioteca variável.
  • Bibliotecas de variáveis são somente leitura quando usadas em notebooks. Faça alterações por meio da interface do usuário ou das APIs do Fabric.
  • Cada biblioteca dá suporte a 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.
  • Nomes de variável e biblioteca são sensíveis a maiúsculas e minúsculas. Use a correspondência exata de nome ao referenciar variáveis.

Dica

Use pipelines de implantação para ativar automaticamente o conjunto de valores apropriado para cada estágio (desenvolvimento, teste, prod). Isso elimina a necessidade de alternar manualmente os conjuntos de valores ou modificar o código ao promover notebooks entre ambientes.

Conteúdo relacionado

  • Last updated on