Créer un élément de fonctions de données utilisateur Fabric

Les fonctions de données utilisateur vous permettent de créer des fonctions Python réutilisables qui peuvent être appelées dans Microsoft Fabric et à partir d’applications externes. En centralisant votre logique métier dans les fonctions, vous pouvez maintenir la cohérence, réduire la duplication du code et simplifier les flux de travail de transformation des données au sein de votre organisation.

Avec les fonctions de données utilisateur, vous pouvez :

Centraliser la logique métier - Écrire des fonctions une fois et les appeler à partir de pipelines, notebooks, règles d’activateur et Power BI
Intégrer en toute transparence - Appeler des fonctions via des points de terminaison REST à partir de n’importe quelle application ou service
Accélérer le développement - Utiliser des exemples de fonctions prédéfini ou créer des fonctions personnalisées avec le modèle de programmation Python
Maintenir la cohérence - Vérifier que les transformations de données et les règles métier sont appliquées uniformément dans toutes les charges de travail

Ce guide de démarrage rapide vous montre comment créer votre premier élément Fonctions de données utilisateur, ajouter des fonctions à partir de l’exemple de bibliothèque, écrire des fonctions personnalisées et les exécuter dans le portail Fabric. À la fin, vous disposez d’une fonction de travail qui illustre la normalisation des catégories pour les données de produit.

Ce que vous avez accompli

Dans ce guide de démarrage rapide, vous effectuez les tâches suivantes :

Créer un élément Fonctions de données utilisateur dans votre espace de travail
Ajouter et configurer des bibliothèques Python requises (comme pandas)
Insérer une fonction à partir de l’exemple de bibliothèque
Écrire une fonction personnalisée avec une syntaxe et des décorateurs appropriés
Tester et publier vos fonctions
Exécuter des fonctions dans le portail et afficher les résultats

Conditions préalables

Capacité Microsoft Fabric dans l’une des régions prises en charge. Si vous n’avez pas de capacité Fabric, démarrez une version d’évaluation gratuite de Fabric.
Un espace de travail Fabric affecté à cette capacité

Créez un nouvel élément de fonctions de données utilisateur

Dans votre espace de travail, sélectionnez + Nouvel élément.
Recherchez et sélectionnez la vignette Fonctions de données utilisateur .
Entrez un nom pour l’élément de fonctions de données utilisateur, puis sélectionnez Créer.
Sélectionnez le fichier Nouvelle fonction pour créer une nouvelle fonction. La hello_fabric fonction Python est publiée et chargée dans l’éditeur de code.
L’Explorateur Functions affiche toutes les fonctions publiées et prêtes à être appelées. Étant donné que la hello_fabric fonction est publiée, vous pouvez l’exécuter à partir de la liste des fonctions dans l’Explorateur Functions.

Ajouter une nouvelle fonction à partir de l’exemple

Cet exemple montre comment ajouter une nouvelle fonction à partir du menu Insérer un échantillon. Dans ce cas, nous ajoutons une fonction appelée Manipuler des données avec la bibliothèque pandas qui utilise la pandas bibliothèque comme condition.

Ajouter des bibliothèques requises

Assurez-vous que vous êtes en mode Développement .
Sélectionnez Gestion des bibliothèques pour ajouter les bibliothèques dont votre fonction a besoin.
Sélectionnez +Ajouter à partir de PyPI pour ajouter une nouvelle bibliothèque à partir du référentiel PyPI public.
Recherchez et sélectionnez la bibliothèque pandas , puis sélectionnez la version. Une fois la bibliothèque ajoutée, elle est automatiquement enregistrée dans votre élément fonctions des données d’utilisateur.
Si vous le souhaitez, vous pouvez mettre à jour la version de la fabric_user_data_functions bibliothèque vers la dernière version disponible. Sélectionnez l’icône de crayon à côté de la bibliothèque pour la mettre à jour.

Remarque

La fabric_user_data_functions bibliothèque est incluse par défaut et ne peut pas être supprimée. Cette bibliothèque est requise pour les fonctionnalités des fonctions de données utilisateur. Vous devez mettre à jour la version de cette bibliothèque pour toutes les versions ultérieures de ce Kit de développement logiciel (SDK).
Fermez le volet de gestion de la bibliothèque pour revenir à la page d’accueil User Data Functions.

Insérer l’exemple de fonction

Sélectionnez l’onglet Modifier pour ouvrir d’autres options d’édition dans le menu du ruban.
Sélectionnez Insérer un exemple>Manipulation de Données>Manipuler des données avec la bibliothèque pandas. Cette action ajoute une nouvelle fonction qui utilise la pandas bibliothèque pour manipuler des données.
Une fois l’exemple inséré dans l’éditeur, la nouvelle fonction s’affiche dans l’Explorateur Functions avec une icône de cercle en regard de celle-ci. Cette icône indique que la fonction a changé depuis sa dernière publication, ce qui signifie qu’il existe des mises à jour qui doivent être publiées.

Écrire une fonction personnalisée

Maintenant que vous avez ajouté une fonction à partir de l’exemple de bibliothèque, vous pouvez écrire votre propre fonction personnalisée directement dans l’éditeur de code. Cette section présente la syntaxe et la structure requises pour la création de fonctions à partir de zéro.

Chaque fonction exécutable nécessite l’élément @udf.function() décoratif avant la définition de la fonction. Ce décorateur marque votre fonction Python comme exécutable dans l’infrastructure User Data Functions. La syntaxe de base est la suivante :

@udf.function()
def your_function_name(parameter: type) -> return_type:
    # Your function logic here
    return result

Important

Les noms de paramètres doivent utiliser camelCase (par exemple, productName au lieu de product_name) et tous les paramètres sont requis. Pour connaître les exigences et limitations complètes de la syntaxe, consultez les exigences et limitations de syntaxe.

Voici un exemple complet qui normalise les catégories de produits à partir des données brutes des ventes :

# This function standardizes inconsistent product category names from different data sources

@udf.function()
def standardize_category(productName: str, rawCategory: str) -> dict:
    # Define category mappings for common variations
    category_mapping = {
        "electronics": ["electronic", "electronics", "tech", "devices"],
        "clothing": ["clothes", "clothing", "apparel", "fashion"],
        "home_goods": ["home", "household", "home goods", "furniture"],
        "food": ["food", "grocery", "groceries", "snacks"],
        "books": ["book", "books", "reading", "literature"]
    }
    
    # Normalize the input
    raw_lower = rawCategory.lower().strip()
    
    # Find the standardized category
    standardized = "other"
    for standard_name, variations in category_mapping.items():
        if raw_lower in variations:
            standardized = standard_name
            break
    
    return {
        "product_name": productName,
        "original_category": rawCategory,
        "standardized_category": standardized,
        "needs_review": standardized == "other"
    }

Vous pouvez ajouter cette fonction à votre éditeur de code en même temps que les fonctions existantes. La fonction apparaît dans l’Explorateur Functions avec une icône de cercle, indiquant qu’elle doit être publiée.

Concepts clés du modèle de programmation

Vos fonctions de données utilisateur utilisent le modèle de programmation Python User Data Functions pour créer, exécuter, déboguer et modifier des fonctions individuelles. Le modèle de programmation est fourni par le fabric-user-data-functions package, disponible publiquement sur PyPI et préinstallé dans vos éléments de fonctions de données utilisateur.

Lorsque vous créez votre première fonction, le fichier de code inclut les instructions import requises :

import datetime
import fabric.functions as fn
import logging

udf = fn.UserDataFunctions()

Points clés sur le modèle de programmation :

Le fabric-user-data-functions package fournit le fabric.functions module que vous importez comme fn dans votre code.
L’appel fn.UserDataFunctions() crée le contexte d’exécution requis pour définir et exécuter des fonctions dans un élément User Data Functions.
D’autres bibliothèques comme logging vous permettent d’écrire des journaux personnalisés pour le débogage et la surveillance.

Remarque

L’instruction import fabric.functions as fn et la udf = fn.UserDataFunctions() ligne sont requises pour que vos fonctions fonctionnent correctement. Vos fonctions ne fonctionneront pas si ces lignes sont manquantes.

Tester et publier vos fonctions

Maintenant que vous avez créé plusieurs fonctions (l’exemple manipulate_data de fonction et votre fonction personnalisée standardize_category ), vous pouvez les tester et les publier ensemble.

En mode Développement , vous pouvez tester chaque fonction à l’aide de la fonctionnalité test avant la publication. Le test vous permet de valider vos modifications de code sans les rendre disponibles pour l’appel externe.
Lorsque vous êtes prêt à rendre vos fonctions disponibles, sélectionnez Publier pour enregistrer vos modifications et mettre à jour toutes vos fonctions. La publication peut prendre quelques minutes.
Une fois la publication terminée, toutes les fonctions sont actualisées dans la liste de l’Explorateur Functions et les icônes de cercle sont supprimées. Vos fonctions sont maintenant prêtes à être :
- Exécuter à partir du portail en mode Exécuter uniquement
- Appelé à partir d’un autre élément Fabric, tel qu’un pipeline, un bloc-notes ou une règle d’Activator
- Appelé à partir d’une application externe via le point de terminaison REST

Exécuter vos fonctions

Avec toutes vos fonctions créées, testées et publiées, vous pouvez désormais basculer vers le mode Exécuter uniquement pour les exécuter et afficher les résultats.

Sélectionnez Exécuter uniquement le mode dans le sélecteur de mode en haut à droite du portail.
Sélectionnez l’icône Exécuter qui s’affiche lorsque vous pointez sur une fonction dans la liste de l’Explorateur Functions.

Exécuter l’exemple de fonction

Dans l’Explorateur Functions, pointez sur la manipulate_data fonction.
Sélectionnez le bouton Exécuter qui s’affiche lorsque vous pointez sur la fonction.
Un volet d’exécution s’ouvre sur le côté droit de l’écran.
Dans le volet d’exécution, vous voyez le nom de paramètre data avec le type list. Entrez la valeur JSON suivante dans la zone de texte :
```
[
 {
  "Name": "John",
  "Age": 22,
  "Gender": "male"
 }
]
```
Sélectionnez le bouton Exécuter dans le volet d’exécution (situé en regard de l’emplacement où vous avez entré les données JSON) pour exécuter la fonction.
Affichez les résultats et les journaux sous Sortie (liste) dans le volet d’exécution. La sortie affiche les données manipulées sous la forme d’un DataFrame pandas au format JSON.

Exécuter la fonction personnalisée

Essayez maintenant d’exécuter votre fonction personnalisée standardize_category .

Dans l’Explorateur Functions, pointez sur la standardize_category fonction.
Sélectionnez le bouton Exécuter qui s’affiche lorsque vous pointez sur la fonction.
Un volet de commande s’ouvre sur le côté droit de l’écran.
Fournissez des paramètres de test :
- productName : Laptop Computer
- rawCategory : tech
Sélectionnez Exécuter et observez la sortie, qui doit afficher la catégorie standardisée comme « électronique » et inclure les métadonnées relatives à la catégorisation.

Gérer les fonctions

Après avoir créé et exécuté vos fonctions, vous pouvez les renommer ou les supprimer si nécessaire. Toutes les opérations de gestion nécessitent que vous soyez en mode Développement .

Renommer une fonction

En mode Développer, sélectionnez dans l’éditeur de code et mettez à jour le nom de la fonction. Par exemple, renommez hello_fabric :hello_fabric1

@udf.function()
def hello_fabric1(name: str) -> str:
   logging.info('Python UDF trigger function processed a request.')

   return f"Welcome to Fabric Functions, {name}, at {datetime.datetime.now()}!"

Après avoir modifié le nom, sélectionnez Publier pour enregistrer ces modifications.
Une fois les modifications publiées, vous voyez le nouveau nom de la fonction dans l’Explorateur Functions.

Supprimer une fonction

Pour supprimer une fonction, sélectionnez le code de fonction dans l’éditeur de code et supprimez la section de code entière. Publiez les modifications pour la supprimer entièrement de l’élément de fonctions de données utilisateur.

Par exemple, pour supprimer la fonction hello_fabric, supprimez le bloc de code suivant :

@udf.function()
def hello_fabric(name: str) -> str:
    logging.info('Python UDF trigger function processed a request.')

    return f"Welcome to Fabric Functions, {name}, at {datetime.datetime.now()}!"

Une fois le code supprimé, vous pouvez sélectionner Publier pour enregistrer vos modifications. Une fois la publication terminée, vous voyez une liste mise à jour des fonctions disponibles dans l’Explorateur Functions.

Résolution des problèmes

Si vous rencontrez des problèmes lors de l’utilisation des fonctions de données utilisateur :

La fonction ne publiera pas : recherchez les erreurs de syntaxe dans votre code. Vérifiez que toutes les importations requises (fabric.functions) et la udf = fn.UserDataFunctions() ligne sont présentes.
Erreurs d’affectation de noms de paramètre : n’oubliez pas que les noms de paramètres doivent utiliser camelCase (aucun trait de soulignement). Passez en revue les exigences et limitations de la syntaxe.
Erreurs d’importation de bibliothèque : vérifiez que toutes les bibliothèques requises sont ajoutées via gestion des bibliothèques et que la version est compatible avec Python 3.11.
Fonction qui n’apparaît pas dans l’Explorateur Functions : assurez-vous que vous avez publié vos modifications après l’ajout ou la modification de fonctions.

Pour plus d’aide, consultez les limites et considérations relatives au service Fonctions des données utilisateur.

Maintenant que vous avez créé votre premier élément Fonctions de données utilisateur, explorez ces ressources pour développer vos compétences :

Créer un élément de fonctions de données utilisateur Fabric dans Visual Studio Code - Apprenez à développer des fonctions en local avec un IDE pris en charge dans son intégralité
En savoir plus sur le modèle de programmation des fonctions de données utilisateur - Découvrez plus en détail le Kit de développement logiciel (SDK) Python et les fonctionnalités avancées
Appeler des fonctions de données utilisateur à partir d’une application Python : appelez vos fonctions à partir d’applications externes via des API REST
Gérer les bibliothèques pour les fonctions de données utilisateur - Découvrir les techniques de gestion avancée des bibliothèques

Rétroaction

Cette page a-t-elle été utile ?

Last updated on 2026-01-22