Utilitários da UDF (Função de Dados do Usuário) do NotebookUtils para Fabric

O notebookutils.udf módulo fornece utilitários para integrar o código do notebook com itens da UDF (Função de Dados do Usuário). Você pode acessar funções de um item UDF no mesmo workspace ou em workspaces diferentes e, em seguida, invocar essas funções conforme necessário. Os itens UDF promovem a reutilização de código, a manutenção centralizada e a colaboração em equipe.

Use utilitários UDF para:

  • Recuperação de função – Acessar funções por nome a partir de elementos UDF.
  • Acesso entre workspaces – Use funções dos itens UDF em outros workspaces.
  • Descoberta de funções – inspecione as funções disponíveis e suas assinaturas.
  • Invocação flexível – chamar funções com parâmetros apropriados para o idioma.

Observação

Você precisa de acesso de leitura a um item UDF no workspace de destino para recuperar suas funções. As exceções das funções UDF se propagam para o notebook chamador.

A tabela a seguir 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 por ID de artefato ou nome. Retorna um objeto com atributos de função que podem ser chamados.

O objeto retornado expõe as seguintes propriedades:

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

Dica

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

Recuperar funções de uma UDF

Use notebookutils.udf.getFunctions() para obter todas as funções de um item UDF. Opcionalmente, você pode especificar uma ID do workspace 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. O Python dá suporte a 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âmetro padrão

Fabric funções de dados do usuário dão suporte a valores de argumento padrão. Quando você invoca funções recuperadas por meio de notebookutils.udf.getFunctions, qualquer parâmetro que possua um padrão definido pode ser omitido e o tempo de execução usa o padrão automaticamente. Você também pode fornecer argumentos nomeados para substituir padrões específicos, mantendo outros em seus padrões originais.

# 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 com suporte

Os seguintes tipos têm suporte como valores de parâmetro padrão:

Tipo padrão Notes
String Qualquer cadeia de caracteres serializável JSON.
Cadeia de caracteres de data e hora Especifique como uma cadeia de caracteres na assinatura da função. O tempo de execução o analisa para datetime no momento 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.
Float Qualquer valor de ponto flutuante.
Lista Deve ser serializável em JSON; prefira None na assinatura e atribua dentro da função para evitar problemas com valores padrão mutáveis.
Dicionário Deve ser serializável em JSON; prefira None na assinatura e atribua dentro da função.
DataFrame do pandas Fornecido como um objeto JSON que o SDK converte em um tipo pandas. Requer a fabric-user-data-functions versão 1.0.0 ou posterior.
Série pandas Fornecido como um array JSON de objetos que o SDK converte para o tipo pandas. Requer a fabric-user-data-functions versão 1.0.0 ou posterior.

Limitações e diretrizes

Os padrões devem ser serializáveis em JSON (não há suporte para conjuntos e tuplas). Para padrões de lista ou dicionário, use None na assinatura e atribua o padrão real dentro da função para evitar padrões mutáveis compartilhados. Use o formato ISO 8601 (por exemplo, 2025-12-31T23:59:59Z) para padrões de datetime. Usar o Pandas DataFrame ou Series como padrão requer fabric-user-data-functions a versão 1.0.0 ou posterior.

Exibir detalhes

Você pode inspecionar os metadados de item da UDF e as assinaturas de função programaticamente.

Exibir detalhes do item UDF

display(myFunctions.itemDetails)

Exibir detalhes da função

display(myFunctions.functionDetails)

Dica

Sempre inspecione functionDetails ao trabalhar com um novo item UDF. Isso ajuda você a verificar as funções disponíveis e seus tipos de parâmetro esperados antes da invocação.

Tratamento de erros

Envolver invocações UDF no tratamento de erros adequado ao idioma para gerenciar funções ausentes ou tipos de parâmetro inesperados de forma elegante. Sempre verifique se existe uma função no item UDF antes de chamá-la.

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

Usar funções UDF em um pipeline de dados

Você pode compor funções UDF para criar etapas de 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

Invocações de UDF têm sobrecarga. Se você chamar a mesma função com os mesmos parâmetros repetidamente, considere armazenar o resultado em cache. Evite chamar funções UDF em loops apertados quando possível.

Conteúdo relacionado

  • Last updated on