Oversigt over programmeringsmodel for Fabric Brugerdatafunktioner

Programmeringsmodellen for Fabric User-datafunktioner er et SDK, der giver den nødvendige funktionalitet til at oprette og publicere runnable funktioner i Fabric. SDK'et giver dig også mulighed for problemfrit at integrere med andre elementer i Fabric-økosystemet, f.eks. Fabric-datakilder. Dette bibliotek er offentligt tilgængeligt i PyPI- og er forudinstalleret i elementer i dine brugerdatafunktioner.

SDK til brugerdatafunktioner

Et element med brugerdatafunktioner indeholder en eller flere funktioner, som du kan aktivere fra Fabric-portalen, fra et andet Fabric-element eller fra et eksternt program ved hjælp af det angivne REST-slutpunkt. Hver funktion er en metode i Python-scriptet, der gør det muligt at overføre parametre og returnere et output til aktiveringsfunktionen. Programmeringsmodellen Brugerdatafunktioner indeholder følgende komponenter:

Biblioteket fabric.functions indeholder den kode, du skal bruge for at oprette brugerdatafunktioner i Python. Du kan se, at dette bibliotek importeres i din første funktionsskabelon, når du opretter et nyt element til brugerdatafunktioner.
Metoden fn.UserDataFunctions() leverer den udførelseskontekst, der blev fundet i starten af kodefilen i alle nye elementer i brugerdatafunktioner før nogen funktionsdefinitioner.

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

udf = fn.UserDataFunctions()
```
Hver funktion identificeres med en @udf.function() dekoratør. Denne dekoratør definerer, om din funktion kan aktiveres individuelt fra portalen eller en ekstern invoker. Brug af denne dekoratør kræver også, at funktionen har en returværdi. Funktioner med denne dekoratør kan få adgang til de forbindelsesobjekter, der er angivet af dekoratøren @udf.connection .

eksempel på funktionen Invokable
```
# 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-metoder uden @udf.function() dekoratøren kan ikke aktiveres direkte. De kan kun aktiveres fra funktioner, der indeholder dekoratøren, og kan bruges som hjælpefunktioner.

eksempel på hjælpefunktion

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

Understøttede inputtyper

Du kan definere inputparametre for funktionen, f.eks. primitive datatyper som str, int, float osv. De understøttede inputdatatyper er:

JSON-type	Python-datatype
Streng	Str
datetime-streng	datetime
Boolesk	Bool
tal	int, flyde
Array	list[], eksempelliste[int]
objekt	Dict
objekt	pandaer DataFrame
Objekt eller matrix af objekter	pandas-serien

Notat

Hvis du vil bruge pandas DataFrame- og Series-typer, skal du vælge Biblioteksadministration i Fabric-portalen for din brugerdatafunktion og opdatere fabric-user-data-function versionen til 1.0.0.

Eksempel på anmodningsbrødtekst for understøttede inputtyper:

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

Understøttede outputtyper

De understøttede outputdatatyper er:

Python-datatype
Str
datetime
Bool
int, flyde
list[data-type], f.eks. list[int]
Dict
Ingen
pandas-serien
pandaer DataFrame

Sådan skriver du en asynkron funktion

Tilføj asynkron dekoratør med din funktionsdefinition i din kode. Med en async funktion kan du forbedre svartid og effektivitet i dit program ved at håndtere flere opgaver på én gang. De er ideelle til styring af store mængder I/O-bundne operationer. Denne eksempelfunktion læser en CSV-fil fra et lakehouse ved hjælp af pandas. Funktionen bruger filnavnet som inputparameter.

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

Dataforbindelser til Fabric-datakilder

I dette modul kan du referere til dataforbindelser uden at skulle skrive forbindelsesstrenge i din kode. Biblioteket fabric.functions indeholder to måder at håndtere dataforbindelser på:

fabric.functions.FabricSqlConnection: Giver dig mulighed for at arbejde med SQL-databaser i Fabric, herunder SQL Analytics-slutpunkter og Fabric warehouses.
fabric.functions.FabricLakehouseClient: Giver dig mulighed for at arbejde med Lakehouses, så du kan oprette forbindelse til både Lakehouse-tabeller og Lakehouse-filer.

Hvis du vil referere til en forbindelse til en datakilde, skal du bruge @udf.connection dekoratør. Du kan anvende den i et af 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>")

Argumenterne for @udf.connection er:

argName, navnet på den variabel, som forbindelsen bruger i din funktion.
alias, aliasset for den forbindelse, du har tilføjet med menuen Administrer forbindelser.
Hvis argName og alias har samme værdi, kan du bruge @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

Generiske forbindelser til Fabric-elementer eller Azure-ressourcer

Generiske forbindelser giver dig mulighed for at oprette forbindelser til Fabric-elementer eller Azure-ressourcer ved hjælp af din User Data Functions-elementejeridentitet. Denne funktion genererer et Microsoft Entra ID-token med elementejerens identitet og en angivet målgruppetype. Dette token bruges til at godkende med Fabric-elementer eller Azure-ressourcer, der understøtter den pågældende målgruppetype. Denne proces giver dig en programmeringsoplevelse, der minder om brugen af administrerede forbindelsesobjekter fra funktionen Administrer forbindelser , men kun for den angivne målgruppetype i forbindelsen.

Denne funktion bruger dekoratøren @udf.generic_connection() med følgende parametre:

Parameter	Beskrivelse	Værdi
`argName`	Navnet på den variabel, der overføres til funktionen. Brugeren skal angive denne variabel i argumenterne for deres funktion og bruge typen af `fn.FabricItem` for den	Hvis funktionen f.eks. `argName=CosmosDb`skal indeholde dette argument `cosmosDb: fn.FabricItem`
`audienceType`	Den type målgruppe, som forbindelsen er oprettet til. Denne parameter er knyttet til typen af Fabric-element eller Azure-tjeneste og bestemmer den klient, der bruges til forbindelsen.	De tilladte værdier for denne parameter er `CosmosDb` eller `KeyVault`.

Opret forbindelse til Fabric Cosmos DB-objektbeholder ved hjælp af en generisk forbindelse

Generiske forbindelser understøtter oprindelige Fabric Cosmos DB-elementer ved hjælp af målgruppetypen CosmosDB . Det medfølgende User Data Functions SDK indeholder en hjælpemetode, der kaldes get_cosmos_client , der henter en singleton Cosmos DB-klient for hvert kald.

Du kan oprette forbindelse til et Fabric Cosmos DB-element ved hjælp af en generisk forbindelse ved at følge disse trin:

I elementet Fabric User Data Functions skal du installere azure-cosmos biblioteket ved hjælp af biblioteksstyringsoplevelsen.
Gå til dine Fabric Cosmos DB-elementindstillinger .
Hent URL-adressen til dit Fabric Cosmos DB-slutpunkt.

Gå til dit element Brugerdatafunktioner. Brug følgende eksempelkode til at oprette forbindelse til din Fabric Cosmos DB-objektbeholder og køre en læseforespørgsel ved hjælp af Cosmos DB-eksempeldatasættet. Erstat værdierne for følgende variabler:

COSMOS_DB_URI med dit Fabric Cosmos DB-slutpunkt.
DB_NAME med navnet på din Fabric Cosmos DB-vare.

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 kør denne funktion ved at angive et kategorinavn, f.eks Accessory . i aktiveringsparametrene.

Notat

Du kan også bruge disse trin til at oprette forbindelse til en Azure Cosmos DB-database ved hjælp af kontoens URL-adresse og databasenavne. Ejerkontoen for brugerdatafunktioner skal have adgangstilladelser til den pågældende Azure Cosmos DB-konto.

Opret forbindelse til Azure Key Vault ved hjælp af en generisk forbindelse

Generiske forbindelser understøtter oprettelse af forbindelse til en Azure Key Vault ved hjælp af målgruppetypen KeyVault . Denne type forbindelse kræver, at ejeren af Fabric User Data Functions har tilladelse til at oprette forbindelse til Azure Key Vault. Du kan bruge denne forbindelse til at hente nøgler, hemmeligheder eller certifikater efter navn.

Du kan oprette forbindelse til Azure Key Vault for at hente en klienthemmelighed for at kalde en API ved hjælp af en generisk forbindelse ved at følge disse trin:

I elementet Fabric User Data Functions skal du installere requests bibliotekerne og bibliotekerne azure-keyvault-secrets ved hjælp af biblioteksstyringsoplevelsen.
Gå til din Azure Key Vault-ressource , og hent Vault URI og navnet på din nøgle, hemmelighed eller certifikat.

Gå tilbage til elementet Fabric User Data Functions , og brug dette eksempel. I dette eksempel henter vi en hemmelighed fra Azure Key Vault for at oprette forbindelse til en offentlig API. Erstat værdien af følgende variabler:

KEY_VAULT_URL med det Vault URI du hentede i det forrige trin.
KEY_VAULT_SECRET_NAME med navnet på din hemmelighed.
API_URL variabel med webadressen på den API, du vil oprette forbindelse til. I dette eksempel antages det, at du opretter forbindelse til en offentlig API, der accepterer GET-anmodninger og tager følgende parametre 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 kør denne funktion ved at angive en anmodningstekst i din kode.

Hent aktiveringsegenskaber ved hjælp af `UserDataFunctionContext`

Programmeringsmodellen indeholder også objektet UserDataFunctionContext. Dette objekt indeholder metadata for funktionsaktivering og kan bruges til at oprette specifik applogik for visse aktiveringsmekanismer.

I følgende tabel vises egenskaberne for det UserDataFunctionContext objekt:

Egenskabsnavn	Datatype	Beskrivelse
Aktiverings-id	streng	Det entydige GUID, der er knyttet til aktiveringen af elementet med brugerdatafunktioner.
Udfører bruger	objekt	Metadata for brugerens oplysninger, der bruges til at godkende aktiveringen.

Objektet ExecutingUser indeholder følgende oplysninger:

Egenskabsnavn	Datatype	Beskrivelse
Oid	streng (GUID)	Brugerens objekt-id, som er et uforanderligt id for anmoderen. Dette er den bekræftede identitet for den bruger eller tjenesteprincipal, der bruges til at aktivere denne funktion på tværs af programmer.
TenantId	streng (GUID)	Id'et for den lejer, som brugeren er logget på.
PreferredUsername	streng	Det foretrukne brugernavn for den bruger, der aktiverer, som angivet af brugeren. Denne værdi kan slås fra.

Hvis du vil have adgang til parameteren UserDataFunctionContext, skal du bruge følgende dekoratør øverst i funktionsdefinitionen: @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åndteret fejl med `UserThrownError`

Når du udvikler din funktion, kan du udløse et forventet fejlsvar ved hjælp af den UserThrownError metode, der er tilgængelig i Python-programmeringsmodellen. En måde at bruge denne metode på er at administrere tilfælde, hvor brugerindgivne input ikke kan bestå 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 metode tager to parametre:

Message: Denne streng returneres som fejlmeddelelse til det program, der aktiverer denne funktion.
En ordbog med egenskaber returneres til det program, der kalder denne funktion.

Hent variabler fra Fabric-variabelbiblioteker

Et Fabric Variable Library i Microsoft Fabric er et centraliseret lager til administration af variabler, der kan bruges på tværs af forskellige elementer i et arbejdsområde. Det giver udviklere mulighed for at tilpasse og dele varekonfigurationer effektivt.

Føj en forbindelse til et variabelbibliotek ved hjælp af Administrer forbindelser , og hent aliaset for det variable bibliotekselement.
Tilføj en forbindelsesdekorator @udf.connection(argName="varLib", alias="<My Variable Library Alias>") for at referere til aliaset for det variable bibliotekselement.
I funktionsdefinitionen skal du medtage et argument med typen fn.FabricVariablesClient. Denne klient indeholder de metoder, du skal bruge til at arbejde med variables library item. For eksempel def standardize_date(rawDate: str, varLib: fn.FabricVariablesClient) -> str:
Brug getVariables() metoden til at hente alle variablerne fra variabelbiblioteket.

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

1 For at læse værdierne af variablerne skal du bruge 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")

Reference-API-dokumentation
opret et element til fabric-brugerdatafunktioner
eksempler på brugerdatafunktioner

Feedback

Var denne side nyttig?

Last updated on 2025-11-10