Partager via

Utilitaires de fonctions de données utilisateur (UDF) de NotebookUtils pour Fabric

Le notebookutils.udf module fournit des utilitaires permettant d’intégrer du code de notebook à des éléments UDF (User Data Function). Vous pouvez accéder aux fonctions à partir d’un élément UDF au sein du même espace de travail ou entre différents espaces de travail, puis appeler ces fonctions en fonction des besoins. Les éléments UDF favorisent la réutilisation du code, la maintenance centralisée et la collaboration d’équipe.

Utilisez les utilitaires UDF pour :

  • Récupération des fonctions : accéder aux fonctions à partir d’éléments UDF par nom.
  • Accès inter-espaces de travail : utilisez des fonctions à partir d’éléments UDF dans d’autres espaces de travail.
  • Découverte de fonctions : inspectez les fonctions disponibles et leurs signatures.
  • Appel flexible : appeler des fonctions avec des paramètres appropriés au langage.

Note

Vous avez besoin d’un accès en lecture à un élément UDF dans l’espace de travail cible pour récupérer ses fonctions. Les exceptions des fonctions UDF se propagent au notebook appelant.

Le tableau suivant répertorie les méthodes UDF disponibles :

Méthode Signature Description
getFunctions getFunctions(udf: String, workspaceId: String = ""): UDF Récupère toutes les fonctions d’un élément UDF par ID ou nom d’artefact. Retourne un objet avec des attributs de fonction appelables.

L’objet retourné expose les propriétés suivantes :

Propriété Catégorie Description
functionDetails Liste Liste des dictionnaires de métadonnées de fonction. Chaque dictionnaire comprend : Name (nom de la fonction), Description (description de la fonction), Parameters (liste des définitions de paramètres), (type de retour) FunctionReturnType et DataSourceConnections (connexions de source de données utilisées).
itemDetails Dictionnaire Dictionnaire des métadonnées d’élément UDF avec des clés : Id (ID d’artefact), Name (nom de l’élément), WorkspaceId (ID d’espace de travail) et CapacityId (ID de capacité).
<functionName> Callable Chaque fonction de l’élément UDF devient une méthode appelante sur l’objet retourné. Utilisez myFunctions.functionName(...) pour invoquer.

Conseil / Astuce

Récupérez les fonctions UDF une fois et cachez l’objet wrapper. Évitez d’appeler getFunctions() à plusieurs reprises dans une boucle : mettant en cache le résultat à la place pour réduire la surcharge.

Récupérer des fonctions depuis une UDF

Permet notebookutils.udf.getFunctions() d’obtenir toutes les fonctions d’un élément UDF. Vous pouvez éventuellement spécifier un ID d’espace de travail pour l’accès inter-espaces de travail.

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

Invoquer une fonction

Après avoir récupéré des fonctions à partir d’un élément UDF, appelez-les par nom. Python prend en charge les paramètres positionnels et nommés. Les exemples Scala et R utilisent des paramètres positionnels.

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

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

Afficher les détails

Vous pouvez inspecter les métadonnées d’élément UDF et les signatures de fonction par programmation.

Afficher les détails de l’élément UDF

display(myFunctions.itemDetails)

Afficher les détails de la fonction

display(myFunctions.functionDetails)

Conseil / Astuce

Inspectez functionDetails toujours lors de l’utilisation d’un nouvel élément UDF. Cela vous permet de vérifier les fonctions disponibles et leurs types de paramètres attendus avant l’appel.

Gestion des erreurs

Emballer les appels des fonctions UDF dans un traitement d'erreurs approprié au langage de programmation pour gérer avec élégance les fonctions manquantes ou les types de paramètres inattendus. Vérifiez toujours qu’une fonction existe dans l’élément UDF avant de l’appeler.

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

Utiliser des fonctions UDF dans un pipeline de données

Vous pouvez composer des fonctions UDF pour créer des étapes ETL réutilisables :

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

Important

Les appels UDF ont un coût en ressources. Si vous appelez la même fonction avec les mêmes paramètres à plusieurs reprises, envisagez de mettre en cache le résultat. Évitez d’appeler des fonctions UDF dans des boucles serrées lorsque cela est possible.

Contenu connexe

  • Last updated on