Générer du code d’appel pour les fonctions de données utilisateur

Une fois que vous avez publié vos fonctions de données utilisateur, vous pouvez les appeler à partir d’éléments Fabric ou d’applications externes. Au lieu d’écrire le code d’appel à partir de zéro, utilisez la fonctionnalité Générer un code d’appel pour créer automatiquement des modèles de code prêts à l’emploi.

Choisissez l’option de génération de code en fonction de votre scénario d’intégration :

• Code Fabric Notebooks (Python) : pour appeler des fonctions à partir de Notebooks Fabric, qui est un moyen d’intégrer des éléments Fabric. Pour d’autres éléments Fabric tels que Pipelines et Activator, consultez la documentation d’intégration.
• Code d’application client (Python, C#, Node.js) : pour appeler vos fonctions à partir d’applications externes via le point de terminaison REST unique que chaque fonction expose. Cela permet l’intégration à des applications web, des services ou à n’importe quel système en dehors de Fabric.
• Spécification OpenAPI (JSON, YAML) : pour les plateformes de gestion des API, les agents IA ou la génération de kits SDK clients. Utilisez-la pour intégrer vos fonctions à Gestion des API Azure, configurer des systèmes IA ou générer des bibliothèques pour des applications externes.

Prerequisites

Avant de générer du code d’appel, vous avez besoin des éléments suivants :

• Élément User Data Functions publié avec au moins une fonction
• Accès à l’élément Fonctions de données utilisateur dans le portail Fabric
• Au moins exécuter l’autorisation sur l’élément User Data Functions pour générer et utiliser le code d’appel

Générer du code pour les Bloc-notes Fabric

Lorsque vous intégrez des éléments Fabric, utilisez cette option pour appeler vos fonctions à partir de Notebooks Fabric. Le code généré utilise l’utilitaire intégré mssparkutils.userDataFunction , qui fournit un moyen simple d’appeler des fonctions sans gérer l’authentification ou les points de terminaison. Cela est idéal pour les flux de travail de traitement des données, l’analyse exploratoire et les pipelines Machine Learning dans l’environnement Fabric.

1. Ouvrez votre élément Fonctions de données utilisateur dans le portail Fabric.

2. Sous l’onglet Accueil, sélectionnez Générer le code d'invocation>client.

3. Sous Invoquer à partir de, sélectionnez Notebook dans la liste déroulante.

4. Sélectionnez le nom de la fonction que vous souhaitez appeler.

5. Le code est généré automatiquement en Python. (Python est le seul langage disponible pour le code d’appel de notebook.)

   

6. Copiez l’extrait de code généré.

7. Collez-le dans une nouvelle cellule de votre bloc-notes Fabric.

8. Mettez à jour les paramètres de fonction avec vos valeurs réelles. Le code généré inclut un commentaire montrant où mettre à jour :

   # UPDATE BELOW: Update the request body based on the inputs to your function
   myFunctions.hello_fabric(name = "string")
   

9. Exécutez la cellule pour appeler votre fonction.

Pour plus d’informations, consultez les utilitaires Fabric Notebook User Data Functions.

Générer du code pour les applications clientes

Lorsque vous intégrez des applications externes, utilisez cette option pour appeler vos fonctions via le point de terminaison REST unique que chaque fonction expose. Le code généré inclut la configuration de l’authentification à l’aide de l’ID Microsoft Entra et gère le flux de requête/réponse HTTP. Cela vous permet d’appeler vos fonctions Fabric à partir d’applications web, d’applications mobiles, de microservices ou de n’importe quel système en dehors de l’environnement Fabric.

1. Ouvrez votre élément Fonctions de données utilisateur dans le portail Fabric.

2. Sous l’onglet Accueil, sélectionnez Générer le code d'invocation>Client.

3. Sous Invocation de, sélectionnez l’application cliente dans la liste déroulante.

4. Sélectionnez le nom de la fonction que vous souhaitez appeler.

5. Choisissez votre langage de programmation :

   • Python
   • C#
   • Node.js

   

6. Copiez le code généré et ajoutez-le à votre application.

7. Passez en revue la structure du code :

   • Authentification : utilise InteractiveBrowserCredential pour acquérir un jeton (pour le développement/test uniquement)
   • URL du point de terminaison - Point de terminaison REST unique pour votre fonction spécifique
   • Corps de la demande : contient les paramètres d’entrée attendus par votre fonction

8. Mettez à jour la request_body section avec vos valeurs de paramètre réelles. Le code généré inclut un commentaire montrant où mettre à jour :

   # UPDATE HERE: Update the request body based on the inputs to your function 
   request_body = {
       "name": "string"
   }
   

9. Pour les applications de production, remplacez le code d’authentification par l’inscription d’application Microsoft Entra ID appropriée. Le code généré inclut un avertissement et un lien vers des instructions pour l’authentification de production.

Pour obtenir une procédure pas à pas complète, notamment la configuration de l’authentification de production, consultez Appeler des fonctions de données utilisateur à partir d’une application Python.

Générer une spécification OpenAPI

Lorsque vous devez intégrer vos fonctions à des plateformes de gestion des API, des agents IA ou générer des kits SDK clients pour les applications externes, utilisez cette option pour créer une spécification OpenAPI. La spécification OpenAPI fournit une description lisible par ordinateur des points de terminaison REST de votre fonction, ce qui permet aux outils et systèmes de découvrir et d’intégrer vos fonctions par programmation.

1. Ouvrez votre élément Fonctions de données utilisateur dans le portail Fabric.

2. Sous l'onglet Accueil, sélectionnez Générer le code d'appel>spécification OpenAPI.

3. Dans la boîte de dialogue Générer une spécification OpenAPI , sélectionnez votre format de sortie :

   • JSON
   • YAML

   

4. Copiez la spécification générée. La spécification inclut les éléments suivants :

   • Toutes les fonctions publiées dans l’élément Fonctions de données utilisateur
   • Schémas de demande et de réponse pour chaque fonction
   • Exigences d’authentification (jeton du porteur)
   • Réponses d’erreur HTTP standard (400, 401, 403, 408, 413, 500)
   • Résumés et descriptions des fonctions (à partir de docstrings)

Améliorer la sortie OpenAPI avec des docstrings

La qualité de votre spécification OpenAPI dépend de la documentation de votre code de fonction. Lorsque des systèmes comme Gestion des API Azure, les agents IA ou les outils de documentation d’API consomment votre spécification OpenAPI, ils s’appuient sur des descriptions claires pour comprendre ce que font vos fonctions.

Le générateur OpenAPI extrait automatiquement les informations de vos documents de fonction. Ajoutez ces propriétés à vos fonctions pour créer une documentation complète sur l’API :

• Résumé - Explication en une seule ligne qui apparaît dans les catalogues d’API et les vues de haut niveau
• Description - Explication détaillée de ce que fait la fonction, des entrées attendues et de ce qu’elle retourne

Exemple de fonction avec une documentation appropriée :

@udf.function()
def hello_fabric(name: str) -> str:
    """
    Summary: A Python function that prints your name and the time.
    Description: This function takes a string input and concatenates it with the current time 
    to give you a warm welcome to User Data Functions. Returns a string and provides a log entry.
    """
    logging.info('Python UDF trigger function processed a request.')
    return f"Welcome to Fabric Functions, {name}, at {datetime.datetime.now()}!"

Lorsque vous générez la spécification OpenAPI, ces valeurs de documentation remplissent les champs summary et description du schéma OpenAPI, ce qui facilite la compréhension de l’utilisation de vos fonctions par les développeurs et les systèmes.

Utilisations courantes du code généré

Une fois que vous avez généré votre code d’appel, vous pouvez l’utiliser pour intégrer vos fonctions dans différents scénarios :

Intégrations d’éléments de structure :

• Appeler des fonctions à partir de Notebooks pour le traitement des données, le Machine Learning et l’analyse exploratoire
• Orchestrer des fonctions dans les pipelines pour les flux de transformation de données
• Déclencher des fonctions à partir de règles d’activateur en réponse à des événements en temps réel

Intégrations d’applications externes :

• Appeler des fonctions à partir d’applications web, d’applications mobiles ou de microservices à l’aide du code de l’application cliente
• Importer des spécifications OpenAPI dans Gestion des API Azure ou d’autres passerelles d’API pour la gestion centralisée
• Générer des kits SDK clients à l’aide d’OpenAPI Generator pour une intégration cohérente entre plusieurs systèmes
• Configurer des agents IA pour découvrir et appeler vos fonctions à l’aide de la spécification OpenAPI
• Tester et valider des fonctions à l’aide d’outils tels que Postman ou Swagger UI

Contenu connexe

• Appeler des fonctions de données utilisateur à partir d’une application Python - Procédure pas à pas complète pour appeler des fonctions à partir d’applications Python externes
• Utilitaires Fabric Notebook - Informations de référence sur l’appel de fonctions à partir de notebooks
• Intégration avec les pipelines Fabric - Utilisez des fonctions dans les pipelines de données
• Modèle de programmation Python - Découvrez comment écrire des fonctions avec des docstrings appropriés