Condividi tramite

Utilità UDF (User Data Function) di NotebookUtils per Fabric

Il notebookutils.udf modulo fornisce utilità per l'integrazione del codice del notebook con elementi UDF (User Data Function). È possibile accedere alle funzioni da un elemento UDF all'interno della stessa area di lavoro o in aree di lavoro diverse e quindi richiamare tali funzioni in base alle esigenze. Gli elementi UDF promuovono la riutilizzabilità del codice, la manutenzione centralizzata e la collaborazione tra team.

Usare le utilità UDF per:

  • Recupero delle funzioni – Accesso alle funzioni dagli elementi di una funzione definita dall'utente per nome.
  • Accesso tra aree di lavoro – Usa le funzioni degli elementi UDF in altre aree di lavoro.
  • Individuazione delle funzioni: controllare le funzioni disponibili e le relative firme.
  • Invocazione flessibile: invocare le funzioni con parametri appropriati del linguaggio.

Annotazioni

Per recuperare le funzioni, è necessario l'accesso in lettura a un elemento della funzione definita dall'utente nell'area di lavoro di destinazione. Le eccezioni dalle funzioni UDF vengono propagate al notebook chiamante.

Nella tabella seguente sono elencati i metodi UDF:

metodo Firma Descrizione
getFunctions getFunctions(udf: String, workspaceId: String = ""): UDF Recupera tutte le funzioni da un elemento UDF in base all'ID o al nome dell'artefatto. Restituisce un oggetto con attributi di funzione chiamabili.

L'oggetto restituito espone le proprietà seguenti:

Proprietà Tipo Descrizione
functionDetails Elenco Elenco di dizionari di metadati della funzione. Ogni dizionario include: Name (nome della funzione), Description (descrizione della funzione), Parameters (elenco di definizioni di parametri), FunctionReturnType (tipo restituito) e DataSourceConnections (connessioni all'origine dati usate).
itemDetails Dizionario Dizionario dei metadati degli elementi UDF con chiavi: Id (ID artefatto), Name (nome elemento), WorkspaceId (ID area di lavoro) e CapacityId (ID capacità).
<functionName> Callable Ogni funzione nell'elemento UDF diventa un metodo chiamabile sull'oggetto restituito. Usare myFunctions.functionName(...) per richiamare.

Suggerimento

Recuperare le funzioni UDF una sola volta e memorizzare nella cache l'oggetto wrapper. Evitare di chiamare getFunctions() ripetutamente in un ciclo: memorizzare nella cache il risultato per ridurre al minimo l'overhead.

Recuperare funzioni da una UDF

Usare notebookutils.udf.getFunctions() per ottenere tutte le funzioni da un elemento UDF. Facoltativamente, è possibile specificare un ID area di lavoro per l'accesso tra aree di lavoro.

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

Richiamare una funzione

Dopo aver recuperato le funzioni da un elemento UDF, chiamarle per nome. Python supporta parametri posizionali e denominati. Gli esempi scala e R usano parametri posizionali.

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

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

Visualizzare i dettagli

È possibile esaminare programmaticamente i metadati degli elementi UDF e le firme delle funzioni.

Visualizzare i dettagli dell'UDF

display(myFunctions.itemDetails)

Visualizzare i dettagli della funzione

display(myFunctions.functionDetails)

Suggerimento

Controllare sempre functionDetails quando si lavora con un nuovo elemento della funzione definita dall'utente. Ciò consente di verificare le funzioni disponibili e i relativi tipi di parametri previsti prima della chiamata.

Gestione degli errori

Racchiudere le chiamate definite dall'utente nella gestione errori appropriata al linguaggio per gestire funzioni mancanti o tipi di parametri imprevisti. Verificare sempre che esista una funzione nell'elemento UDF prima di chiamarla.

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

Usare funzioni UDF in una pipeline di dati

È possibile comporre funzioni UDF per creare passaggi ETL riutilizzabili.

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

Le invocazioni UDF hanno dei costi aggiuntivi. Se si chiama ripetutamente la stessa funzione con gli stessi parametri, prendere in considerazione la memorizzazione nella cache del risultato. Evitare di chiamare funzioni UDF in cicli stretti, quando possibile.

Contenuti correlati

  • Last updated on