Partilhar via

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

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