Partager via

Fabric Données utilisateur Fonctions de programmation Aperçu du modèle (préversion)

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. Elle est ajoutée 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(). Cet élément décoratif définit si votre fonction peut être appelée individuellement à partir du portail ou d’un appelant externe.

    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

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 (entier), float (flottant)
list[type de données], par exemple list[int]
dictionnaire
Aucun

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, le nom de la variable que la connexion utilisera 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

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.
  • Dictionnaire de propriétés qui seront retournées à l’application qui appelle cette fonction.

Étapes suivantes