Stoff Oversikt over programmeringsmodell for brukerdatafunksjoner

Programmeringsmodellen for Fabric User-datafunksjoner er en SDK som gir den nødvendige funksjonaliteten til å redigere og publisere kjørbare funksjoner i Fabric. SDK lar deg også sømløst integrere med andre elementer i Fabric-økosystemet, for eksempel Fabric-datakilder. Dette biblioteket er offentlig tilgjengelig i PyPI- og er forhåndsinstallert i elementene for brukerdatafunksjoner.

SDK for brukerdatafunksjoner

Et element for brukerdatafunksjoner inneholder én eller mange funksjoner du kan aktivere fra Stoff-portalen, fra et annet stoffelement eller fra et eksternt program ved hjelp av det angitte REST-endepunktet. Hver funksjon er en metode i Python-skriptet som gjør det mulig å sende parametere og returnere utdata til aktiveringsprogrammet. Programmeringsmodellen for brukerdatafunksjoner inneholder følgende komponenter:

Biblioteket fabric.functions inneholder koden du trenger for å opprette brukerdatafunksjoner i Python. Du kan se at dette biblioteket importeres i den første funksjonsmalen når du oppretter et nytt element for brukerdatafunksjoner.
Metoden fn.UserDataFunctions() gir kjøringskonteksten som ble funnet i begynnelsen av kodefilen i alle nye elementer for brukerdatafunksjoner, før noen funksjonsdefinisjoner.

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

udf = fn.UserDataFunctions()
```
Hver funksjon identifiseres med en @udf.function() dekoratør. Denne dekoratøren definerer om funksjonen kan aktiveres individuelt fra portalen eller en ekstern aktivering. Bruk av denne dekoratøren krever også at funksjonen har en returverdi. Funksjoner med denne dekoratøren kan få tilgang til tilkoblingsobjektene som er angitt av dekoratøren @udf.connection .

eksempel på aktiverbar funksjon
```
# 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()}!"
```

Alle Python-metoder uten @udf.function()-dekoratøren kan ikke aktiveres direkte. De kan bare aktiveres fra funksjoner som inneholder dekoratøren, og kan brukes som hjelpefunksjoner.

eksempel på hjelpefunksjon

# 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()

Støttede inndatatyper

Du kan definere inndataparametere for funksjonen, for eksempel primitive datatyper som str, int, float osv. Datatypene for inndata som støttes, er:

JSON-type	Python-datatype
Streng	Str
Datetime-streng	datetime
Boolsk	Bool
tall	int, flyt
Matrise	list[], eksempelliste[int]
objekt	Diktering
objekt	pandaer DataFrame
Objekt eller matrise av objekter	pandas-serien

Merk deg

Hvis du vil bruke pandas DataFrame- og Serietyper, velger du Bibliotekadministrasjon i Fabric-portalen for brukerdatafunksjonen og oppdaterer fabric-user-data-function versjon til 1.0.0.

Eksempel på forespørselstekst for inndatatyper som støttes:

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

Utdatatyper som støttes

Datatypene for utdata som støttes, er:

Python-datatype
Str
datetime
Bool
int, flyt
list[datatype], for eksempel liste[int]
Diktering
Ingen
pandas-serien
pandaer DataFrame

Slik skriver du en asynkrone funksjon

Legg til asynkron dekoratør med funksjonsdefinisjonen i koden. Med en async funksjon kan du forbedre respons og effektivitet i programmet ved å håndtere flere oppgaver samtidig. De er ideelle for å håndtere store volumer av I/O-bundne operasjoner. Denne eksempelfunksjonen leser en CSV-fil fra et lakehouse ved hjelp av pandaer. Funksjonen tar filnavn som inndataparameter.

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

Datatilkoblinger til Fabric-datakilder

Med denne modulen kan du referere til datatilkoblinger uten behov for å skrive tilkoblingsstrenger i koden. Biblioteket fabric.functions inneholder to måter å håndtere datatilkoblinger på:

fabric.functions.FabricSqlConnection: Lar deg arbeide med SQL-databaser i Fabric, inkludert SQL Analytics-endepunkter og Fabric-lagre.
fabric.functions.FabricLakehouseClient: Lar deg jobbe med Lakehouses, med en måte å koble til både Lakehouse-bord og Lakehouse-filer.

Hvis du vil referere til en tilkobling til en datakilde, må du bruke @udf.connection-dekoratøren. Du kan bruke den i et av følgende formater:

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

Argumentene for @udf.connection er:

argName, navnet på variabelen som tilkoblingen bruker i funksjonen.
alias, aliaset for tilkoblingen du la til med Behandle tilkoblinger-menyen.
Hvis argName og alias har samme verdi, kan du bruke @udf.connection("<alias and argName for the data connection>").

Eksempel

# 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

Generelle tilkoblinger for Fabric-elementer eller Azure-ressurser

Generiske tilkoblinger lar deg opprette tilkoblinger til Fabric-elementer eller Azure-ressurser ved hjelp av eieridentiteten for User Data Functions-elementet. Denne funksjonen genererer et Microsoft Entra ID-token med elementeierens identitet og en angitt målgruppetype. Dette tokenet brukes til å godkjenne med Fabric-elementer eller Azure-ressurser som støtter denne målgruppetypen. Denne prosessen vil gi deg en lignende programmeringsopplevelse som å bruke forvaltede tilkoblingsobjekter fra funksjonen Behandle tilkoblinger , men bare for den angitte målgruppetypen i tilkoblingen.

Denne funksjonen bruker dekoratøren @udf.generic_connection() med følgende parametere:

Parameter	Beskrivelse	Verdi
`argName`	Navnet på variabelen som sendes til funksjonen. Brukeren må spesifisere denne variabelen i argumentene til funksjonen og bruke typen `fn.FabricItem` for den	Hvis for eksempel `argName=CosmosDb`, skal funksjonen inneholde dette argumentet `cosmosDb: fn.FabricItem`
`audienceType`	Målgruppetypen som tilkoblingen er opprettet for. Denne parameteren er knyttet til typen Fabric-element eller Azure-tjeneste og bestemmer klienten som brukes for tilkoblingen.	De tillatte verdiene for denne parameteren er `CosmosDb` eller `KeyVault`.

Koble til Fabric Cosmos DB-beholder ved hjelp av en generisk tilkobling

Generelle tilkoblinger støtter opprinnelige Fabric Cosmos DB-elementer ved hjelp av målgruppetypen CosmosDB . Den inkluderte SDK-en for brukerdatafunksjoner gir en hjelpemetode kalt get_cosmos_client som henter en singleton Cosmos DB-klient for hvert anrop.

Du kan koble til et Fabric Cosmos DB-element ved hjelp av en generisk tilkobling ved å følge disse trinnene:

I Fabric User Data Functions-elementet installerer azure-cosmos du biblioteket ved hjelp av bibliotekadministrasjonsopplevelsen.
Gå til elementinnstillingene for Fabric Cosmos DB .
Hent URL-adressen for Fabric Cosmos DB-endepunktet.

Gå til elementet Brukerdatafunksjoner. Bruk følgende eksempelkode til å koble til Fabric Cosmos DB-beholderen og kjøre en lesespørring ved hjelp av Cosmos DB-eksempeldatasettet. Erstatt verdiene for følgende variabler:

COSMOS_DB_URI med Fabric Cosmos DB-endepunktet.
DB_NAME med navnet på Fabric Cosmos DB-varen din.

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 eller kjør denne funksjonen ved å angi et kategorinavn, for eksempel Accessory i aktiveringsparameterne.

Merk deg

Du kan også bruke disse trinnene til å koble til en Azure Cosmos DB-database ved hjelp av nettadressen for kontoen og databasenavnene. User Data Functions-eierkontoen trenger tilgangstillatelser til den Azure Cosmos DB-kontoen.

Koble til Azure Key Vault ved hjelp av en generisk tilkobling

Generelle tilkoblinger støtter tilkobling til et Azure Key Vault ved hjelp av målgruppetypen KeyVault . Denne typen tilkobling krever at eieren av Fabric User Data Functions har tillatelse til å koble til Azure Key Vault. Du kan bruke denne tilkoblingen til å hente nøkler, hemmeligheter eller sertifikater etter navn.

Du kan koble til Azure Key Vault for å hente en klienthemmelighet for å kalle en API ved hjelp av en generell tilkobling ved å følge denne fremgangsmåten:

I elementet Fabric User Data Functions installerer requests du bibliotekene og bibliotekene azure-keyvault-secrets ved hjelp av bibliotekadministrasjonsopplevelsen.
Gå til Azure Key Vault-ressursenVault URI og hent og navnet på nøkkelen, hemmeligheten eller sertifikatet.

Gå tilbake til Fabric User Data Functions-elementet , og bruk dette eksemplet. I dette eksemplet henter vi en hemmelighet fra Azure Key Vault for å koble til en offentlig API. Erstatt verdien av følgende variabler:

KEY_VAULT_URL med du Vault URI hentet i forrige trinn.
KEY_VAULT_SECRET_NAME med navnet på hemmeligheten din.
API_URL variabelen med nettadressen til API-et du vil koble til. Dette eksemplet forutsetter at du kobler til en offentlig API som godtar GET-forespørsler og tar følgende parametere api-key og 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 eller kjør denne funksjonen ved å angi en forespørselstekst i koden.

Hent aktiveringsegenskaper ved hjelp av `UserDataFunctionContext`

Programmeringsmodellen inkluderer også objektet UserDataFunctionContext. Dette objektet inneholder funksjonsmetadata og kan brukes til å opprette spesifikk applogikk for bestemte aktiveringsmekanismer.

Tabellen nedenfor viser egenskapene for objektet UserDataFunctionContext:

Egenskapsnavn	Datatype	Beskrivelse
Aktiverings-ID	streng	Den unike GUID-en som er knyttet til aktiveringen av elementet for brukerdatafunksjoner.
ExecutingUser	objekt	Metadata for brukerens informasjon som brukes til å godkjenne aktiveringen.

Objektet ExecutingUser inneholder følgende informasjon:

Egenskapsnavn	Datatype	Beskrivelse
Oid	streng (GUID)	Brukerens objekt-ID, som er en uforanderlig identifikator for anmoderen. Dette er den bekreftede identiteten til brukeren eller tjenestekontohaveren som brukes til å aktivere denne funksjonen på tvers av programmer.
TenantId	streng (GUID)	ID-en til leieren som brukeren er logget på.
PreferredUsername	streng	Foretrukket brukernavn for den påkallende brukeren, som angitt av brukeren. Denne verdien kan dempes.

Hvis du vil ha tilgang til UserDataFunctionContext-parameteren, må du bruke følgende dekoratør øverst i funksjonsdefinisjonen: @udf.context(argName="<parameter name>")

Eksempel

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

Kast en håndtert feil med `UserThrownError`

Når du utvikler funksjonen, kan du sende et forventet feilsvar ved hjelp av UserThrownError metoden som er tilgjengelig i Python-programmeringsmodellen. Én bruk av denne metoden er å administrere tilfeller der inndataene fra brukeren ikke klarer å sende forretningsvalideringsregler.

Eksempel

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

Denne UserThrownError metoden tar to parametere:

Message: Denne strengen returneres som feilmelding til programmet som aktiverer denne funksjonen.
En ordliste med egenskaper returneres til programmet som aktiverer denne funksjonen.

Hent variabler fra Fabric-variabelbiblioteker

Et Fabric Variable Library i Microsoft Fabric er et sentralisert repositorium for administrasjon av variabler som kan brukes på tvers av ulike elementer i et arbeidsområde. Det lar utviklere tilpasse og dele varekonfigurasjoner effektivt.

Legg til en tilkobling til et variabelbibliotek ved hjelp av Administrer tilkoblinger , og få aliaset for det variable bibliotekelementet.
Legg til en tilkoblingsdekorator @udf.connection(argName="varLib", alias="<My Variable Library Alias>") for å referere til aliaset for det variable bibliotekelementet.
I funksjonsdefinisjonen tar du med et argument med typen fn.FabricVariablesClient. Denne klienten inneholder metoder du trenger for å arbeide med variabelbibliotekelementet. For eksempel def standardize_date(rawDate: str, varLib: fn.FabricVariablesClient) -> str:
Bruk getVariables() metoden for å hente alle variablene fra variabelbiblioteket.

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

1 For å lese verdiene til variablene, bruk enten ["variable-name"] eller .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")

Tilbakemeldinger

Var denne siden nyttig?

Last updated on 2025-11-10