Vue d’ensemble du modèle de programmation des fonctions de données utilisateur Fabric

Le modèle de programmation des fonctions de données utilisateur Fabric est un SDK qui fournit les fonctionnalités nécessaires pour créer et publier des fonctions exécutables dans Fabric. Le Kit de développement logiciel (SDK) vous permet également d’intégrer en toute transparence d’autres éléments dans l’écosystème Fabric, tels que des sources de données Fabric. Cette bibliothèque est disponible publiquement dans pyPI et préinstallée dans vos éléments de fonctions de données utilisateur.

Fonctions de données utilisateur SDK

Un élément de fonctions de données utilisateur contient une ou plusieurs fonctions que vous pouvez appeler à partir du portail Fabric, d’un autre élément Fabric ou d’une application externe à l’aide du point de terminaison REST fourni. Chaque fonction est une méthode dans votre script Python qui permet de transmettre des paramètres et de retourner une sortie à l’appelant. Le modèle de programmation des fonctions de données utilisateur contient les composants suivants :

La bibliothèque fabric.functions fournit le code dont vous avez besoin pour créer des fonctions de données utilisateur dans Python. Vous pouvez voir cette bibliothèque importée dans votre premier modèle de fonction lorsque vous créez un élément de fonctions de données utilisateur.
La méthode fn.UserDataFunctions() fournit le contexte d’exécution trouvé au début du fichier de code dans tous les nouveaux éléments de fonctions de données utilisateur, avant toutes les définitions de fonction.

Exemple :
```
import datetime
import fabric.functions as fn
import logging

udf = fn.UserDataFunctions()
```
Chaque fonction est identifiée par un décorateur @udf.function(). Ce décorateur définit si votre fonction peut être appelée individuellement à partir du portail ou d’un appelant externe. L’utilisation de ce décorateur nécessite également que la fonction ait une valeur de retour. Les fonctions avec ce décorateur peuvent accéder aux objets de connexion désignés par le décorateur @udf.connection.

Exemple de fonction invoque
```
# This is a hello fabric function sample that can be invoked from the Fabric portal, another Fabric item, or an external application.

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

    return f"Welcome to Fabric Functions, {name}, at {datetime.datetime.now()}!"
```
Toutes les méthodes Python sans le décorateur @udf.function() ne peuvent pas être appelées directement. Elles ne peuvent être appelées qu’à partir de fonctions qui contiennent le décorateur et peuvent être utilisées comme fonctions d’assistance.

Exemple de fonction d'aide
```
# This is a helper function that can be invoked from other functions, but can't be invoked or run directly because it doesn't have the @udf.function() decorator

def uppercase_name(name: str) -> str:
    return name.upper()
```

Types d’entrée pris en charge

Vous pouvez définir des paramètres d'entrée pour la fonction, tels que des types de données primitives comme str, int, float, etc. Les types de données d'entrée pris en charge sont les suivants :

Type JSON	Type de données Python
Chaîne	Str
Chaîne Date/Heure	date et heure
Booléen	Bool
Nombres	int, float
Tableau	list[], exemple de liste[int]
Objet	dictionnaire
Objet	DataFrame pandas
Objet ou tableau d’objets	Pandas Series

Remarque

Pour utiliser les types DataFrame et Série pandas, sélectionnez Gestion des bibliothèques dans le portail Fabric pour votre fonction de données utilisateur et mettez à jour fabric-user-data-function la version vers la version 1.0.0.

Exemple de corps de requête pour les types d’entrée pris en charge :

{
  "name": "Alice",                          // String (str)
  "signup_date": "2025-07-08T13:44:40Z",    // Datetime string (datetime)
  "is_active": true,                        // Boolean (bool)
  "age": 30,                                // Number (int)
  "height": 5.6,                            // Number (float)
  "favorite_numbers": [3, 7, 42],           // Array (list[int])
  "profile": {                              // Object (dict)
    "email": "alice@example.com",
    "location": "Sammamish"
  },
  "sales_data": {                           // Object (pandas DataFrame)
    "2025-07-01": {"product": "A", "units": 10},
    "2025-07-02": {"product": "B", "units": 15}
  },
  "weekly_scores": [                        // Object or Array of Objects (pandas Series)
    {"week": 1, "score": 88},
    {"week": 2, "score": 92},
    {"week": 3, "score": 85}
  ]
}

Types de sortie pris en charge

Les types de données de sortie pris en charge sont les suivants :

Type de données Python
Str
date et heure
Bool
int, float
list[type de données], par exemple list[int]
dictionnaire
Aucun
Pandas Series
DataFrame pandas

Comment écrire une fonction asynchrone

Ajoutez un décorateur asynchrone avec votre définition de fonction dans votre code. Avec une async fonction, vous pouvez améliorer la réactivité et l’efficacité de votre application en gérant plusieurs tâches à la fois. Elles sont idéales pour gérer des volumes élevés d’opérations liées aux E/S. Cet exemple de fonction lit un fichier CSV à partir d’un entrepôt de données en utilisant pandas. La fonction prend le nom de fichier comme paramètre d’entrée.

import pandas as pd 

# Replace the alias "<My Lakehouse alias>" with your connection alias.
@udf.connection(argName="myLakehouse", alias="<My Lakehouse alias>")
@udf.function()
async def read_csv_from_lakehouse(myLakehouse: fn.FabricLakehouseClient, csvFileName: str) -> str:

    # Connect to the Lakehouse
    connection = myLakehouse.connectToFilesAsync()   

    # Download the CSV file from the Lakehouse
    csvFile = connection.get_file_client(csvFileName)

    downloadFile = await csvFile.download_file()
    csvData = await downloadFile.readall()
    
    # Read the CSV data into a pandas DataFrame
    from io import StringIO
    df = pd.read_csv(StringIO(csvData.decode('utf-8')))

    # Display the DataFrame    
    result="" 
    for index, row in df.iterrows():
        result=result + "["+ (",".join([str(item) for item in row]))+"]"
    
    # Close the connection
    csvFile.close()
    connection.close()

    return f"CSV file read successfully.{result}"

Connexions de données aux sources de données Fabric

Ce module vous permet de référencer les connexions de données sans avoir besoin d’écrire des chaînes de connexion dans votre code. La bibliothèque fabric.functions fournit deux façons de gérer les connexions de données :

fabric.functions.FabricSqlConnection : vous permet d’utiliser des bases de données SQL dans Fabric, notamment des points de terminaison SQL Analytics et des entrepôts Fabric.
fabric.functions.FabricLakehouseClient : vous permet d’utiliser Lakehouses, avec un moyen de se connecter aux tables Lakehouse et aux fichiers Lakehouse.

Pour référencer une connexion à une source de données, vous devez utiliser le décorateur @udf.connection. Vous pouvez l'appliquer dans l'un des formats suivants :

@udf.connection(alias="<alias for data connection>", argName="sqlDB")
@udf.connection("<alias for data connection>", "<argName>")
@udf.connection("<alias for data connection>")

Les arguments pour @udf.connection sont :

argName, nom de la variable utilisée par la connexion dans votre fonction.
alias, alias de la connexion que vous avez ajoutée avec le menu Gérer les connexions.
Si argName et alias ont la même valeur, vous pouvez utiliser @udf.connection("<alias and argName for the data connection>").

Exemple :

# Where demosqldatabase is the argument name and the alias for my data connection used for this function
@udf.connection("demosqldatabase")
@udf.function()
def read_from_sql_db(demosqldatabase: fn.FabricSqlConnection)-> list:
  # Replace with the query you want to run
  query = "SELECT * FROM (VALUES ('John Smith', 31), ('Kayla Jones', 33)) AS Employee(EmpName, DepID);"

  # [...] Here is where the rest of your SqlConnection code would be.

  return results

Connexions génériques pour les éléments Fabric ou les ressources Azure

Les connexions génériques vous permettent de créer des connexions à des éléments Fabric ou des ressources Azure à l’aide de votre identité de propriétaire d’élément User Data Functions. Cette fonctionnalité génère un jeton d’ID Microsoft Entra avec l’identité du propriétaire de l’élément et un type d’audience fourni. Ce jeton est utilisé pour s’authentifier auprès d’éléments Fabric ou de ressources Azure qui prennent en charge ce type d’audience. Ce processus vous donnera une expérience de programmation similaire à l’utilisation d’objets de connexions managées à partir de la fonctionnalité Gérer les connexions , mais uniquement pour le type d’audience fourni dans la connexion.

Cette fonctionnalité utilise le @udf.generic_connection() décorateur avec les paramètres suivants :

Paramètre	Descriptif	Valeur
`argName`	Nom de la variable transmise à la fonction. L’utilisateur doit spécifier cette variable dans les arguments de sa fonction et utiliser le type de celui-ci `fn.FabricItem`	Par exemple, si `argName=CosmosDb`, alors la fonction doit contenir l'argument `cosmosDb: fn.FabricItem`
`audienceType`	Type d’audience pour lequel la connexion est créée. Ce paramètre est associé au type d’élément Fabric ou au service Azure et détermine le client utilisé pour la connexion.	Les valeurs autorisées pour ce paramètre sont `CosmosDb` ou `KeyVault`.

Se connecter au conteneur Fabric Cosmos DB à l’aide d’une connexion générique

Les connexions génériques prennent en charge les éléments Fabric Cosmos DB natifs en utilisant le type d'audience CosmosDB. Le Kit de développement logiciel (SDK) User Data Functions inclus fournit une méthode d’assistance appelée get_cosmos_client qui extrait un client Singleton Cosmos DB pour chaque appel.

Vous pouvez vous connecter à un élément Fabric Cosmos DB à l’aide d’une connexion générique en procédant comme suit :

Dans votre élément Fabric User Data Functions, installez la azure-cosmos bibliothèque à l’aide de l’expérience gestion des bibliothèques.
Accédez aux paramètres de votre élément Fabric Cosmos DB.
Récupérez votre URL de point de terminaison Fabric Cosmos DB.

Accédez à votre élément Fonctions de données utilisateur. Utilisez l’exemple de code suivant pour vous connecter à votre conteneur Fabric Cosmos DB et exécuter une requête de lecture à l’aide de l’exemple de jeu de données Cosmos DB. Remplacez les valeurs des variables suivantes :

COSMOS_DB_URI avec le point de terminaison de votre Fabric Cosmos DB.
DB_NAME avec le nom de votre objet Fabric Cosmos DB.

from fabric.functions.cosmosdb import get_cosmos_client
import json

@udf.generic_connection(argName="cosmosDb", audienceType="CosmosDB")
@udf.function()
def get_product_by_category(cosmosDb: fn.FabricItem, category: str) -> list:

    COSMOS_DB_URI = "YOUR_COSMOS_DB_URL"
    DB_NAME = "YOUR_COSMOS_DB_NAME" # Note: This is the Fabric item name
    CONTAINER_NAME = "SampleData" # Note: This is your container name. In this example, we are using the SampleData container.

    cosmosClient = get_cosmos_client(cosmosDb, COSMOS_DB_URI)

    # Get the database and container
    database = cosmosClient.get_database_client(DB_NAME)
    container = database.get_container_client(CONTAINER_NAME)

    query = 'select * from c WHERE c.category=@category' #"select * from c where c.category=@category"
    parameters = [
        {
            "name": "@category", "value": category
        }
    ]
    results = container.query_items(query=query, parameters=parameters)
    items = [item for item in results]

    logging.info(f"Found {len(items)} products in {category}")

    return json.dumps(items)

Testez ou exécutez cette fonction en fournissant un nom de catégorie, par Accessory exemple dans les paramètres d’appel.

Remarque

Vous pouvez également utiliser ces étapes pour vous connecter à une base de données Azure Cosmos DB à l’aide de l’URL du compte et des noms de base de données. Le compte propriétaire user Data Functions doit disposer des autorisations d’accès à ce compte Azure Cosmos DB.

Se connecter à Azure Key Vault à l’aide d’une connexion générique

Les connexions génériques prennent en charge la connexion à Azure Key Vault en utilisant le type d'audience KeyVault. Ce type de connexion nécessite que le propriétaire fabric User Data Functions dispose des autorisations nécessaires pour se connecter à Azure Key Vault. Vous pouvez utiliser cette connexion pour récupérer des clés, des secrets ou des certificats par nom.

Vous pouvez vous connecter à Azure Key Vault pour récupérer une clé secrète client pour appeler une API à l’aide d’une connexion générique en procédant comme suit :

Dans votre élément Fabric User Data Functions, installez la bibliothèque et la bibliothèque à l’aide de l’expérience de gestion des bibliothèques .
Accédez à votre ressource Azure Key Vault et récupérez le Vault URI nom de votre clé, secret ou certificat.

Revenez à votre élément Fabric User Data Functions et utilisez cet exemple. Dans cet exemple, nous récupérons un secret d’Azure Key Vault pour nous connecter à une API publique. Remplacez la valeur des variables suivantes :

KEY_VAULT_URL avec le Vault URI récupéré à l’étape précédente.
KEY_VAULT_SECRET_NAME avec le nom de votre secret.
API_URL variable avec l’URL de l’API à laquelle vous souhaitez vous connecter. Cet exemple part du principe que vous vous connectez à une API publique qui accepte les requêtes GET et accepte les paramètres api-key suivants et request-body.

from azure.keyvault.secrets import SecretClient
from azure.identity import DefaultAzureCredential
import requests

@udf.generic_connection(argName="keyVaultClient", audienceType="KeyVault")
@udf.function()
def retrieveNews(keyVaultClient: fn.FabricItem, requestBody:str) -> str:
    KEY_VAULT_URL = 'YOUR_KEY_VAULT_URL'
    KEY_VAULT_SECRET_NAME= 'YOUR_SECRET'
    API_URL = 'YOUR_API_URL'

    credential = keyVaultClient.get_access_token()

    client = SecretClient(vault_url=KEY_VAULT_URL, credential=credential)

    api_key = client.get_secret(KEY_VAULT_SECRET_NAME).value

    api_url = API_URL
    params = {
        "api-key": api_key,
        "request-body": requestBody
    }

    response = requests.get(api_url, params=params)

    data = "" 

    if response.status_code == 200:
        data = response.json()
    else:
        print(f"Error {response.status_code}: {response.text}")

    return f"Response: {data}"

Testez ou exécutez cette fonction en fournissant un corps de requête dans votre code.

Obtenir des propriétés d’appel à l’aide de `UserDataFunctionContext`

Le modèle de programmation inclut également l’objet UserDataFunctionContext. Cet objet contient les métadonnées d’appel de fonction et peut être utilisé pour créer une logique d’application spécifique pour certains mécanismes d’appel.

Le tableau suivant présente les propriétés de l'objet UserDataFunctionContext :

Nom de la propriété	Type de données	Descriptif
ID d’appel	ficelle	GUID unique lié à l’appel de l’élément de fonctions de données utilisateur.
UtilisateurExécutant	objet	Métadonnées des informations de l’utilisateur utilisées pour autoriser l’appel.

L’objet ExecutingUser contient les information suivantes :

Nom de la propriété	Type de données	Descriptif
Oid	Chaîne (UUID)	ID d’objet de l’utilisateur(-trice), qui est un identificateur immuable pour le demandeur. Il s’agit de l’identité vérifiée de l’utilisateur(-trice) ou du principal de service utilisé pour appeler cette fonction entre les applications.
ID de locataire	Chaîne (UUID)	ID du locataire auquel l’utilisateur(-trice) est connecté(e).
NomD'utilisateurPréféré	ficelle	Nom d’utilisateur préféré de l’utilisateur(-trice) appelant, tel que défini par l’utilisateur(-trice). Cette valeur est mutable.

Pour accéder au paramètre UserDataFunctionContext, vous devez utiliser le décorateur suivant en haut de la définition de fonction : @udf.context(argName="<parameter name>")

Exemple

@udf.context(argName="myContext")
@udf.function()
def getContext(myContext: fabric.functions.UserDataFunctionContext)-> str:
    logging.info('Python UDF trigger function processed a request.')
    return f"Hello oid = {context.executing_user['Oid']}, TenantId = {context.executing_user['TenantId']}, PreferredUsername = {context.executing_user['PreferredUsername']}, InvocationId = {context.invocation_id}"

Lever une erreur gérée avec `UserThrownError`

Lors du développement de votre fonction, vous pouvez lever une réponse d’erreur attendue à l’aide de la méthode UserThrownError disponible dans le modèle de programmation Python. L’une des utilisations de cette méthode consiste à gérer les cas où les entrées fournies par l’utilisateur(-trice) ne réussissent pas les règles de validation métier.

Exemple

import datetime

@udf.function()
def raise_userthrownerror(age: int)-> str:
    if age < 18:
        raise fn.UserThrownError("You must be 18 years or older to use this service.", {"age": age})

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

Cette méthode UserThrownError accepte deux paramètres :

Message: cette chaîne est retournée en tant que message d’erreur à l’application qui appelle cette fonction.
Un dictionnaire de propriétés est retourné à l’application qui appelle cette fonction.

Obtenir des variables à partir de bibliothèques de variables Fabric

Une bibliothèque de variables Fabric dans Microsoft Fabric est un référentiel centralisé pour la gestion des variables qui peuvent être utilisées dans différents éléments au sein d’un espace de travail. Il permet aux développeurs de personnaliser et de partager efficacement les configurations d’éléments.

Ajoutez une connexion à une bibliothèque de variables à l’aide de Gérer les connexions et obtenez l’alias de l’élément de bibliothèque de variables.
Ajoutez un décorateur de connexion, @udf.connection(argName="varLib", alias="<My Variable Library Alias>"), pour que l'alias de l'élément de la bibliothèque des variables soit référencé.
Dans la définition de fonction, incluez un argument de type fn.FabricVariablesClient. Ce client fournit des méthodes dont vous avez besoin pour travailler avec l’élément de bibliothèque de variables. Par exemple, def standardize_date(rawDate: str, varLib: fn.FabricVariablesClient) -> str:
Utilisez getVariables() la méthode pour obtenir toutes les variables de la bibliothèque de variables.

    # Get all variables from the variable library item
    variables = varLib.getVariables()

1 Pour lire les valeurs des variables, utilisez soit ["variable-name"] soit .get("variable-name").

  # Get desired format from environment or use default
  date_format = variables["DATE_FORMAT"]
  # Another way to get the variable
  # date_format= variables.get("DATE_FORMAT")

Commentaires

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

Last updated on 2025-11-10