Overzicht van programmeermodel voor fabric-gebruikersgegevensfuncties

Het programmeermodel voor fabricgebruikersgegevensfuncties is een SDK die de benodigde functionaliteit biedt voor het ontwerpen en publiceren van uitvoerbare functies in Fabric. 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.

SDK voor gebruikersgegevensfuncties

Een item met gebruikersgegevensfuncties bevat een of veel functies die u kunt aanroepen vanuit de Fabric-portal, vanuit een ander Fabric-item of vanuit een externe toepassing met behulp van het opgegeven REST-eindpunt. Elke functie is een methode in uw Python-script waarmee parameters kunnen worden doorgegeven en een uitvoer naar de aanroeper kan worden geretourneerd. Het programmeermodel voor gebruikersgegevensfuncties bevat de volgende onderdelen:

De fabric.functions-bibliotheek bevat de code die je nodig hebt om gebruikersdatafuncties te maken in Python. U kunt zien dat deze bibliotheek wordt geïmporteerd in uw eerste functiesjabloon wanneer u een nieuw item voor gebruikersgegevensfuncties maakt.
De methode fn.UserDataFunctions() biedt de uitvoeringscontext aan het begin van het codebestand in alle nieuwe items voor gebruikersgegevensfuncties, vóór eventuele functiedefinities.

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

udf = fn.UserDataFunctions()
```
Elke functie wordt geïdentificeerd met een @udf.function()-decorator. Met deze decorator wordt gedefinieerd of uw functie afzonderlijk kan worden aangeroepen vanuit de portal of een externe aanroeper. Als u deze decorator gebruikt, moet de functie ook een retourwaarde hebben. Functies met deze decorator hebben toegang tot de verbindingsobjecten die worden aangeduid door de @udf.connection decorator.

Voorbeeld van aanroepbare functie
```
# 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()}!"
```
Python-methoden zonder de @udf.function() decorator kunnen niet direct worden aangeroepen. Ze kunnen alleen worden aangeroepen vanuit functies die de decorator bevatten en kunnen worden gebruikt als helperfuncties.

Voorbeeld van Helper-functie
```
# 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()
```

Ondersteunde invoertypen

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

JSON-type	Python gegevenstype
String	Str
Datum-tijdreeks	datum/tijd
Booleaans	bool
Getallen	int, float
Array	lijst[], voorbeeld lijst[int]
Object	Woordenboek
Object	Pandas DataFrame
Object of matrix van objecten	pandas-serie

Opmerking

Als u pandas DataFrame- en Series-typen wilt gebruiken, selecteert u Bibliotheekbeheer in de Fabric-portal voor uw gebruikersgegevensfunctie en werkt fabric-user-data-function u versie bij naar 1.0.0.

Voorbeeld van aanvraagbody voor ondersteunde invoertypen:

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

Ondersteunde uitvoertypen

De ondersteunde uitvoergegevenstypen zijn:

Python gegevenstype
Str
datum/tijd
bool
int, float
list[data-type], bijvoorbeeld list[int]
Woordenboek
Geen
pandas-serie
Pandas DataFrame

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

Gegevensverbindingen met Fabric-gegevensbronnen

Met deze module kunt u refereren naar de gegevensverbindingen zonder verbindingsreeksen in uw code te hoeven schrijven. 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:
  # 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

Algemene verbindingen voor Fabric-items of Azure-resources

Met algemene verbindingen kunt u verbindingen 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. Dit proces biedt u een vergelijkbare programmeerervaring voor 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:

Kenmerk	Beschrijving	Waarde
`argName`	De naam van de variabele die wordt doorgegeven aan de functie. De gebruiker moet deze variabele opgeven in de argumenten van de functie en het type `fn.FabricItem` hiervoor gebruiken	Als de `argName=CosmosDb`functie bijvoorbeeld dit argument bevat, moet de functie dit argument bevatten `cosmosDb: fn.FabricItem`
`audienceType`	Het type doelgroep waarvoor de verbinding wordt gemaakt. Deze parameter is gekoppeld aan het type Fabric-item of de Azure-service en bepaalt de client die voor de verbinding wordt gebruikt.	De toegestane waarden voor deze parameter zijn `CosmosDb` of `KeyVault`.

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:

Installeer de azure-cosmos bibliotheek in het item User Data Functions van fabric met behulp van de bibliotheekbeheerervaring.
Ga naar de iteminstellingen van Fabric Cosmos DB .
Haal de URL van uw Fabric Cosmos DB-eindpunt op.

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)

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

Opmerking

U kunt deze stappen ook gebruiken om verbinding te maken met een Azure Cosmos DB-database met behulp van de account-URL en databasenamen. Het eigenaaraccount van User Data Functions heeft toegangsmachtigingen nodig voor dat Azure Cosmos DB-account.

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:

Installeer in het item User Data Functions van Fabric de requests bibliotheken en de azure-keyvault-secrets bibliotheken met behulp van de bibliotheekbeheerervaring.
Ga naar uw Azure Key Vault-resource en haal de Vault URI en de naam van uw sleutel, geheim of certificaat op.

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

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

Aanroepeigenschappen ophalen met behulp van `UserDataFunctionContext`

Het programmeermodel bevat ook het UserDataFunctionContext object. Dit object bevat de metagegevens van de functie-aanroep en kan worden gebruikt om specifieke app-logica te maken voor bepaalde aanroepmechanismen.

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

Naam van propertie	Gegevenssoort	Beschrijving
Aanroep-id	touw	De unieke GUID die is gekoppeld aan de aanroep van functies voor gebruikersgegevens van het item.
UitvoerendeGebruiker	Voorwerp	Metagegevens van de gegevens van de gebruiker die worden gebruikt om de aanroep te autoriseren.

Het ExecutingUser-object bevat de volgende informatie:

Naam van propertie	Gegevenssoort	Beschrijving
Oid	tekenreeks (GUID)	De object-id van de gebruiker, een onveranderbare id voor de aanvrager. Dit is de geverifieerde identiteit van de gebruiker of service-principal die wordt gebruikt om deze functie aan te roepen in toepassingen.
huurder-ID	tekenreeks (GUID)	De id van de tenant waarmee de gebruiker is aangemeld.
PreferredUsername	touw	De gewenste gebruikersnaam van de aanroepende gebruiker, zoals ingesteld door de gebruiker. Deze waarde is veranderlijk.

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

Gooi een afgehandelde fout met `UserThrownError`

Bij het ontwikkelen van je functie kun je een verwachte foutreactie werpen met behulp van de UserThrownError methode die beschikbaar is in het Python-programmeermodel. Een toepassing van deze methode is het beheren van gevallen waarin de door de gebruiker verstrekte invoer niet slaagt voor de bedrijfsvalidatieregels.

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

Deze UserThrownError methode 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 in verschillende items binnen een werkruimte. Hiermee kunnen ontwikkelaars itemconfiguraties efficiënt aanpassen en delen.

Voeg een verbinding met een variabelebibliotheek toe met behulp van Verbindingen beheren en haal de alias op voor het item van de variabele bibliotheek.
Voeg een verbindingsdecorator @udf.connection(argName="varLib", alias="<My Variable Library Alias>") toe om te verwijzen naar de alias van het item van de variabele bibliotheek.
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. Bijvoorbeeld def standardize_date(rawDate: str, varLib: fn.FabricVariablesClient) -> str:
Gebruik getVariables() de methode om alle variabelen op te halen uit de variabelebibliotheek.

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

1 Gebruik om de waarden van de variabelen te lezen, ofwel ["variable-name"] of .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")

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

Feedback

Is deze pagina nuttig?

Last updated on 2025-11-10