Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
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.
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.variableLibraryAPI 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.