Compartilhar via

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')

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