Utilidades da Função de Dados do Utilizador (UDF) do NotebookUtils para Fabric

O notebookutils.udf módulo fornece utilitários para integrar código de cadernos com itens da Função de Dados do Utilizador (UDF). Podes aceder a funções de um item UDF dentro do mesmo espaço de trabalho ou entre diferentes espaços de trabalho, e depois invocar essas funções conforme necessário. Os itens UDF promovem a reutilização do código, manutenção centralizada e colaboração em equipa.

Utilizar utilidades UDF para:

  • Recuperação de funções – Aceder a funções a partir de itens UDF pelo nome.
  • Acesso entre espaços de trabalho – Use funções de itens UDF noutros espaços de trabalho.
  • Descoberta de funções – Inspecionar as funções disponíveis e as suas assinaturas.
  • Invocação flexível – Chamar funções com parâmetros adequados à linguagem.

Observação

É necessário acesso de leitura a um item UDF no workspace de destino para recuperar as suas funções. Exceções de funções UDF propagam-se para o notebook que as invoca.

A tabela seguinte lista os métodos UDF disponíveis:

Método Signature Descrição
getFunctions getFunctions(udf: String, workspaceId: String = ""): UDF Recupera todas as funções de um item UDF pelo ID do artefacto ou nome. Devolve um objeto com atributos de função chamáveis.

O objeto devolvido expõe as seguintes propriedades:

Propriedade Tipo Descrição
functionDetails Lista Uma lista de dicionários de metadados de funções. Cada dicionário inclui: Name (nome da função), Description (descrição da função), Parameters (lista de definições de parâmetros), FunctionReturnType (tipo de retorno) e DataSourceConnections (ligações de fonte de dados usadas).
itemDetails Dicionário Um dicionário de metadados de itens UDF com chaves: Id (ID do artefacto), Name (nome do item), WorkspaceId (ID do espaço de trabalho) e CapacityId (ID de capacidade).
<functionName> Callable Cada função no item UDF torna-se um método chamável no objeto devolvido. Usar myFunctions.functionName(...) para invocar.

Sugestão

Recupere as funções de UDF uma vez e armazene em cache o objeto wrapper. Evite chamar getFunctions() repetidamente num ciclo — armazene o resultado em cache para minimizar a sobrecarga.

Recuperar funções de um UDF

Use notebookutils.udf.getFunctions() para obter todas as funções de um item UDF. Pode, opcionalmente, especificar um ID de espaço de trabalho para acesso entre espaços de trabalho.

# Get functions from a UDF item in the current workspace
myFunctions = notebookutils.udf.getFunctions('UDFItemName')

# Get functions from a UDF item in another workspace
myFunctions = notebookutils.udf.getFunctions('UDFItemName', 'workspaceId')

Invocar uma função

Depois de recuperar funções de um item UDF, chame-as pelo nome. Python suporta parâmetros posicionais e nomeados. Exemplos de Scala e R usam parâmetros posicionais.

# Positional parameters
myFunctions.functionName('value1', 'value2')

# Named parameters (recommended for clarity)
myFunctions.functionName(parameter1='value1', parameter2='value2')

Valores de parâmetros padrão

As funções de dados de utilizador do Fabric suportam valores de argumento predefinidos. Quando invocas funções recuperadas via notebookutils.udf.getFunctions, qualquer parâmetro que tenha um padrão definido pode ser omitido — o tempo de execução usa automaticamente o padrão. Também podes fornecer argumentos nomeados para substituir valores padrão específicos, mantendo outros nos seus valores padrão.

# Assume the UDF item defines a function like:
# def score_customer(customerId: str, startDate: datetime = "2025-01-01T00:00:00Z", isActive: bool = True, maxRecords: int = 100) -> dict
# The datetime defaults are specified as strings in the signature; the runtime parses them to datetime at invocation time.

# 1. Call without optional parameters — defaults are used for startDate, isActive, and maxRecords
result = myFunctions.scoreCustomer(customerId='C001')

# 2. Override one default via a named argument, keep the others at their defaults
result = myFunctions.scoreCustomer(customerId='C001', maxRecords=50)

# 3. Pass a date/time in ISO 8601 format for reliable parsing
result = myFunctions.scoreCustomer(customerId='C001', startDate='2025-12-31T23:59:59Z')

Tipos de entrada padrão suportados

Os seguintes tipos são suportados como valores padrão de parâmetro:

Tipo padrão Notes
String Qualquer string serializável em JSON.
Cadeia de data e hora Especifique como uma cadeia na assinatura da função. O runtime analisa-o para datetime na altura da invocação. Use um formato consistente, como ISO 8601 (por exemplo, 2025-12-31T23:59:59Z).
booleano True ou False.
Integer Qualquer valor inteiro.
Flutuar Qualquer valor em ponto flutuante.
Lista Deve ser serializável em JSON; preferir None na assinatura e atribuir dentro da função para evitar armadilhas padrão mutáveis.
Dicionário Deve ser serializável em JSON; de preferência, use None na assinatura e atribua dentro da função.
Pandas DataFrame Fornecido como um objeto JSON que o SDK converte num tipo pandas. Requer fabric-user-data-functions a versão 1.0.0 ou posterior.
Série Pandas Fornecido como um array JSON de objetos que o SDK converte num tipo pandas. Requer fabric-user-data-functions a versão 1.0.0 ou posterior.

Limitações e orientações

Os valores predefinidos devem ser compatíveis com serialização em JSON (estruturas de dados como conjuntos e tuplas não são suportadas). Para valores padrão de lista ou dicionário, use None na assinatura e atribua o valor padrão real dentro da função para evitar valores padrão mutáveis partilhados. Use o formato ISO 8601 (por exemplo, 2025-12-31T23:59:59Z) para os padrões de data-hora. Usar o DataFrame ou o Series do pandas como padrão requer fabric-user-data-functions a versão 1.0.0 ou posterior.

Mostrar detalhes

Podes inspecionar os metadados dos itens UDF e as assinaturas de funções de forma programática.

Mostrar detalhes dos itens UDF

display(myFunctions.itemDetails)

Detalhes da função de visualização

display(myFunctions.functionDetails)

Sugestão

Inspecione functionDetails sempre ao trabalhar com um novo item UDF. Isto ajuda-te a verificar as funções disponíveis e os seus tipos de parâmetros esperados antes da invocação.

Tratamento de erros

Envolva as invocações UDF com um tratamento de erros adequado à linguagem de programação para gerir funções em falta ou tipos de parâmetros inesperados de forma eficaz. Verifique sempre que existe uma função no item UDF antes de a chamar.

import json

try:
    validators = notebookutils.udf.getFunctions('DataValidators')

    # Check if function exists before calling
    functions_info = json.loads(validators.functionDetails)
    function_names = [f['Name'] for f in functions_info]

    if 'validateSchema' in function_names:
        is_valid = validators.validateSchema(
            schema='sales_schema',
            data_path='Files/data/sales.csv'
        )
        print(f"Schema validation: {'passed' if is_valid else 'failed'}")
    else:
        print("validateSchema function not available in this UDF item")
        print(f"Available functions: {', '.join(function_names)}")

except AttributeError as e:
    print(f"Function not found: {e}")
except TypeError as e:
    print(f"Parameter type mismatch: {e}")
except Exception as e:
    print(f"Error invoking UDF: {e}")

Utilizar funções UDF num pipeline de dados

Pode compor funções UDF para construir passos ETL reutilizáveis:

etl_functions = notebookutils.udf.getFunctions('ETLUtilities')

df = spark.read.csv('Files/raw/sales.csv', header=True)
cleaned_df = etl_functions.removeOutliers(df, columns=['amount'])
enriched_df = etl_functions.addCalculatedColumns(cleaned_df)
validated_df = etl_functions.validateAndFilter(enriched_df)

validated_df.write.mode('overwrite').parquet('Files/processed/sales.parquet')
print("ETL pipeline completed using UDF functions")

Importante

As invocações UDF têm sobrecarga. Se chamar repetidamente a mesma função com os mesmos parâmetros, considere guardar o resultado em cache. Evite chamar funções UDF em circuitos apertados sempre que possível.

Conteúdo relacionado

  • Last updated on