Overzicht van programmeermodel voor fabric-gebruikersgegevensfuncties

Het programmeermodel voor fabricgebruikersgegevensfuncties definieert de patronen en concepten voor het ontwerpen van functies in Fabric.

De fabric-user-data-functions SDK implementeert dit programmeermodel en biedt de benodigde functionaliteit voor het ontwerpen en publiceren van uitvoerbare functies. Met de SDK kunt u ook naadloos integreren met andere items in het Fabric-ecosysteem, zoals Fabric-gegevensbronnen. Deze bibliotheek is openbaar beschikbaar in PyPI en is vooraf geïnstalleerd in de items van uw gebruikersgegevensfuncties.

In dit artikel wordt uitgelegd hoe u de SDK gebruikt om functies te bouwen die kunnen worden aangeroepen vanuit de Fabric-portal, andere Fabric-items of externe toepassingen met behulp van de REST API. U leert het programmeermodel en de belangrijkste concepten met praktische voorbeelden.

Aan de slag met de SDK

In deze sectie worden de belangrijkste onderdelen van de User Data Functions SDK geïntroduceerd en wordt uitgelegd hoe u uw functies kunt structuren. U leert over de vereiste import-, decorators en de typen invoer- en uitvoergegevens die door uw functies kunnen worden verwerkt.

SDK voor gebruikersgegevensfuncties

De fabric-user-data-functions SDK biedt de belangrijkste onderdelen die u nodig hebt om functies voor gebruikersgegevens te maken in Python.

Vereiste import en initialisatie

Elk bestand met gebruikersgegevensfuncties moet de fabric.functions module importeren en de uitvoeringscontext initialiseren:

import datetime
import fabric.functions as fn
import logging

udf = fn.UserDataFunctions()

De @udf.function() decorator

Functies die zijn gemarkeerd met de @udf.function() decorator, kunnen worden aangeroepen vanuit de Fabric-portal, een ander Fabric-item of een externe toepassing. Functies met deze decorator moeten een retourtype opgeven.

Voorbeeld:

@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()}!"

Ondersteunende functies

Python-methoden zonder de @udf.function() decorator kunnen niet rechtstreeks worden aangeroepen. Ze kunnen alleen worden aangeroepen vanuit gedecoreerde functies en dienen als hulpfuncties.

Voorbeeld:

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

Ondersteunde invoertypen

U kunt invoerparameters definiëren voor de functie, zoals primitieve gegevenstypen zoals str, int, float, enzovoort. De ondersteunde invoergegevenstypen zijn:

Voorbeeld van aanvraagbody voor ondersteunde invoertypen:

{
  "name": "Alice",                          // String (str)
  "signup_date": "2025-11-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-11-01": {"product": "A", "units": 10},
    "2025-11-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}
  ]
}

Ondersteunde uitvoertypen

De ondersteunde uitvoergegevenstypen zijn:

Functies schrijven

Syntaxisvereisten en -beperkingen

Bij het schrijven van gebruikersgegevensfuncties moet u specifieke syntaxisregels volgen om ervoor te zorgen dat uw functies correct werken.

Parameternaamgeving

• Gebruik camelCase: Parameternamen moeten de camelCase-naamconventie gebruiken en mogen geen onderstrepingstekens bevatten. Gebruik bijvoorbeeld productName in plaats van product_name.
• Gereserveerde trefwoorden: u kunt geen gereserveerde Python-trefwoorden of de volgende Fabric-specifieke trefwoorden gebruiken als parameternamen of functienamen: req, contexten reqInvocationId.

Parametervereisten

• Geen standaardwaarden: standaardparameterwaarden worden niet ondersteund. Alle parameters zijn vereist bij het aanroepen van een functie. Met de volgende functie wordt bijvoorbeeld een syntaxisfout gegenereerd:

  # The default value for the argument called 'name' is not supported and treated like a syntax error.
  @udf.function()
  def goodbye_fabric(name: str = "N/A") -> str:
      return f"Goodbye, {name}."
  

• Typeaantekeningen vereist: alle parameters moeten typeaantekeningen bevatten (bijvoorbeeld name: str).

Functievereisten

• Retourtype vereist: Functies met de @udf.function() decorator moeten een aantekening van het retourtype opgeven (bijvoorbeeld -> str).
• Vereiste importbewerkingen: de import fabric.functions as fn instructie en udf = fn.UserDataFunctions() initialisatie zijn vereist om uw functies te laten werken.

Voorbeeld van de juiste syntaxis

@udf.function()
def process_order(orderNumber: int, customerName: str, orderDate: str) -> dict:
    return {
        "order_id": orderNumber,
        "customer": customerName,
        "date": orderDate,
        "status": "processed"
    }

Een asynchrone functie schrijven

Voeg asynchrone decorator toe met uw functiedefinitie in uw code. Met een async functie kunt u de reactiesnelheid en efficiëntie van uw toepassing verbeteren door meerdere taken tegelijk te verwerken. Ze zijn ideaal voor het beheren van grote hoeveelheden I/O-gebonden bewerkingen. Deze voorbeeldfunctie leest een CSV-bestand uit een lakehouse met behulp van pandas. De functie gebruikt de bestandsnaam als invoerparameter.

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

Werken met gegevens

Gegevensverbindingen met Fabric-gegevensbronnen

Met de SDK kunt u verwijzen naar gegevensverbindingen zonder dat u verbindingsreeksen hoeft te schrijven in uw code. De fabric.functions-bibliotheek biedt twee manieren om gegevensverbindingen af te handelen.

• fabric.functions.FabricSqlConnection: Hiermee kunt u werken met SQL-databases in Fabric, waaronder SQL Analytics-eindpunten en Fabric-warehouses.
• fabric.functions.FabricLakehouseClient: Hiermee kunt u werken met Lakehouses, voor het verbinden met zowel Lakehouse-tabellen als -bestanden.

Om te verwijzen naar een verbinding met een gegevensbron, moet u de @udf.connection decorator gebruiken. U kunt deze toepassen in een van de volgende indelingen:

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

De argumenten voor @udf.connection zijn:

• argName, de naam van de variabele die de verbinding gebruikt in uw functie.
• alias, de alias van de verbinding die u hebt toegevoegd met het Manage connections menu.
• Als argName en alias dezelfde waarde hebben, kunt u gebruiken @udf.connection("<alias and argName for the data connection>").

Voorbeeld

# 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:
  # Connect to the SQL database
  connection = demosqldatabase.connect()
  cursor = connection.cursor()
  
  # Replace with the query you want to run
  query = "SELECT * FROM (VALUES ('John Smith', 31), ('Kayla Jones', 33)) AS Employee(EmpName, DepID);"
  
  # Execute the query
  cursor.execute(query)
  
  # Fetch all results
  results = cursor.fetchall()
  
  # Close the cursor and connection
  cursor.close()
  connection.close()
  
  return results

Algemene verbindingen voor Fabric-items of Azure-resources

De SDK biedt ondersteuning voor algemene verbindingen waarmee u verbindingen kunt maken met Fabric-items of Azure-resources met behulp van de identiteit van de eigenaar van uw User Data Functions-item. Met deze functie wordt een Microsoft Entra ID-token gegenereerd met de identiteit van de itemeigenaar en een opgegeven doelgroeptype. Dit token wordt gebruikt voor verificatie met Fabric-items of Azure-resources die ondersteuning bieden voor dat doelgroeptype. Deze benadering biedt een vergelijkbare programmeerervaring als het gebruik van beheerde verbindingsobjecten via de functie Verbindingen beheren , maar alleen voor het opgegeven doelgroeptype in de verbinding.

Deze functie gebruikt de @udf.generic_connection() decorator met de volgende parameters:

Verbinding maken met Fabric Cosmos DB-container met behulp van een generieke verbinding

Algemene verbindingen ondersteunen systeemeigen Fabric Cosmos DB-items met behulp van het CosmosDB doelgroeptype. De meegeleverde User Data Functions SDK biedt een helpermethode get_cosmos_client die een Singleton Cosmos DB-client ophaalt voor elke aanroep.

U kunt verbinding maken met een Fabric Cosmos DB-item met behulp van een algemene verbinding door de volgende stappen uit te voeren:

1. Ga naar de Fabric-portal, zoek uw werkruimte en open het item met functies voor gebruikersgegevens. Selecteer Bibliotheekbeheer, zoek de azure-cosmos bibliotheek en installeer deze. Zie Bibliotheken beheren voor meer informatie.

2. Ga naar de iteminstellingen van Fabric Cosmos DB .

   

3. Haal de URL van uw Fabric Cosmos DB-eindpunt op.

   

4. Ga naar je User Data Functions-item. Gebruik de volgende voorbeeldcode om verbinding te maken met uw Fabric Cosmos DB-container en voer een leesquery uit met behulp van de Cosmos DB-voorbeeldgegevensset. Vervang de waarden van de volgende variabelen:

   • COSMOS_DB_URI met uw Fabric Cosmos DB-eindpunt.
   • DB_NAME met de naam van uw Fabric Cosmos DB-item.

   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)
   

5. Test of voer deze functie uit door een categorienaam op te geven, zoals Accessory in de aanroepparameters.

Verbinding maken met Azure Key Vault met behulp van een algemene verbinding

Algemene verbindingen ondersteunen het maken van verbinding met een Azure Key Vault met behulp van het KeyVault doelgroeptype. Voor dit type verbinding is vereist dat de eigenaar van de infrastructuurgebruikersgegevensfuncties machtigingen heeft om verbinding te maken met Azure Key Vault. U kunt deze verbinding gebruiken om sleutels, geheimen of certificaten op naam op te halen.

U kunt verbinding maken met Azure Key Vault om een clientgeheim op te halen om een API aan te roepen met behulp van een algemene verbinding door de volgende stappen uit te voeren:

1. Ga naar de Fabric-portal, zoek uw werkruimte en open het item met functies voor gebruikersgegevens. Selecteer Bibliotheekbeheer en zoek en installeer de requests en azure-keyvault-secrets bibliotheken. Zie Bibliotheken beheren voor meer informatie.

2. Ga naar uw Azure Key Vault-resource in Azure Portal en haal de Vault URI en de naam van uw sleutel, geheim of certificaat op.

   

3. Ga terug naar het item Fabric User Data Functions en gebruik dit voorbeeld. In dit voorbeeld halen we een geheim op uit Azure Key Vault om verbinding te maken met een openbare API. Vervang de waarde van de volgende variabelen:

   • KEY_VAULT_URL met de Vault URI gegevens die u in de vorige stap hebt opgehaald.
   • KEY_VAULT_SECRET_NAME met de naam van uw geheim.
   • API_URL variabele met de URL van de API waarmee u verbinding wilt maken. In dit voorbeeld wordt ervan uitgegaan dat u verbinding maakt met een openbare API die GET-aanvragen accepteert en de volgende parameters api-key accepteert en 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}"
   

4. Test of voer deze functie uit door een aanvraagbody in uw code op te geven.

Geavanceerde functies

Het programmeermodel definieert geavanceerde patronen die u meer controle geven over uw functies. De SDK implementeert deze patronen via klassen en methoden waarmee u het volgende kunt doen:

• Toegang tot aanroepmetagegevens over wie uw functie heeft aangeroepen en hoe
• Aangepaste foutscenario's verwerken met gestructureerde foutreacties
• Integreren met Fabric-variabelenbibliotheken voor gecentraliseerd configuratiebeheer

Aanroepeigenschappen ophalen met behulp van UserDataFunctionContext

De SDK bevat het UserDataFunctionContext object. Dit object bevat de metagegevens van de functie-aanroep en kan worden gebruikt om specifieke app-logica te maken voor verschillende aanroepmechanismen (zoals aanroep van de portal versus REST API-aanroep).

De volgende tabel toont de eigenschappen voor het UserDataFunctionContext-object.

Het executing_user-object bevat de volgende informatie:

Als u toegang wilt krijgen tot de UserDataFunctionContext parameter, moet u de volgende decorator boven aan de functiedefinitie gebruiken: @udf.context(argName="<parameter name>")

Voorbeeld

@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 = {myContext.executing_user['Oid']}, TenantId = {myContext.executing_user['TenantId']}, PreferredUsername = {myContext.executing_user['PreferredUsername']}, InvocationId = {myContext.invocation_id}"

Gooi een afgehandelde fout met UserThrownError

Bij het ontwikkelen van uw functie kunt u een verwachte foutreactie genereren met behulp van de UserThrownError klasse die beschikbaar is in de SDK. Een toepassing van deze klasse is het beheren van situaties waarin de gebruikersinvoer niet aan de bedrijfsvalidatieregels voldoet.

Voorbeeld

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

De UserThrownError klasseconstructor heeft twee parameters:

• Message: Deze tekenreeks wordt geretourneerd als het foutbericht aan de toepassing die deze functie aanroept.
• Er wordt een woordenlijst met eigenschappen geretourneerd naar de toepassing die deze functie aanroept.

Variabelen ophalen uit Fabric-variabelenbibliotheken

Een Fabric-variabelebibliotheek in Microsoft Fabric is een centrale opslagplaats voor het beheren van variabelen die kunnen worden gebruikt voor verschillende items in een werkruimte. Hiermee kunnen ontwikkelaars itemconfiguraties efficiënt aanpassen en delen. Zie Variabelenbibliotheken maken en beheren als u nog geen variabelebibliotheek hebt.

Als u een variabelebibliotheek in uw functies wilt gebruiken, voegt u er een verbinding aan toe vanuit het item gebruikersgegevensfuncties. Variabelenbibliotheken worden weergegeven in de OneLake-catalogus naast gegevensbronnen zoals SQL-databases en lakehouses.

Volg deze stappen om variabelenbibliotheken in uw functies te gebruiken:

1. Voeg in het item gebruikersgegevensfuncties een verbinding toe met uw variabelebibliotheek. Zoek en selecteer uw variabelebibliotheek in de OneLake-catalogus en klik vervolgens op Verbinding maken. Let op de Alias die Fabric genereert voor de verbinding.
2. Voeg een verbindingsdecorator toe voor het item van de variabelenbibliotheek. En vervang bijvoorbeeld @udf.connection(argName="varLib", alias="<My Variable Library Alias>") de alias naar de zojuist toegevoegde verbinding voor het item van de variabele bibliotheek.
3. Neem in de functiedefinitie een argument op met het type fn.FabricVariablesClient. Deze client biedt methoden die u nodig hebt om te werken met het bibliotheekitem voor variabelen.
4. Gebruik getVariables() de methode om alle variabelen op te halen uit de variabelebibliotheek.
5. Om de waarden van de variabelen te lezen, gebruikt u ofwel ["variable-name"] of .get("variable-name").

Voorbeeld

In dit voorbeeld simuleren we een configuratiescenario voor een productie- en ontwikkelomgeving. Met deze functie wordt een opslagpad ingesteld, afhankelijk van de geselecteerde omgeving met behulp van een waarde die is opgehaald uit de variabelebibliotheek. De variabelebibliotheek bevat een variabele die wordt aangeroepen ENV waar gebruikers een waarde van dev of prodkunnen instellen.

@udf.connection(argName="varLib", alias="<My Variable Library Alias>")
@udf.function()
def get_storage_path(dataset: str, varLib: fn.FabricVariablesClient) -> str:
    """
    Description: Determine storage path for a dataset based on environment configuration from Variable Library.
    
    Args:
        dataset_name (str): Name of the dataset to store.
        varLib (fn.FabricVariablesClient): Fabric Variable Library connection.
    
    Returns:
        str: Full storage path for the dataset.
    """
    # Retrieve variables from Variable Library
    variables = varLib.getVariables()
    
    # Get environment and base paths
    env = variables.get("ENV")    
    dev_path = variables.get("DEV_FILE_PATH")
    prod_path = variables.get("PROD_FILE_PATH")
    
    # Apply environment-specific logic
    if env.lower() == "dev":
        return f"{dev_path}{dataset}/"
    elif env.lower() == "prod":
        return f"{prod_path}{dataset}/"
    else:
        return f"incorrect settings define for ENV variable"

Verwante inhoud

• Referentie-API-documentatie
• Maak een Fabric User Data Functie-item aan
• voorbeelden van gebruikersgegevensfuncties