Översikt över programmeringsmodell för användardatafunktioner inom nätverksinfrastruktur

För programmeringsmodellen Fabric User-datafunktioners är en SDK som tillhandahåller den nödvändiga funktionaliteten för att skriva och publicera körbara funktioner i Fabric. Med SDK kan du också integrera sömlöst med andra objekt i Infrastruktur-ekosystemet, till exempel Infrastrukturdatakällor. Det här biblioteket är offentligt tillgängligt i PyPI- och är förinstallerat i dina användardatafunktioner.

SDK för användardatafunktioner

Ett användardatafunktionsobjekt innehåller en eller flera funktioner som du kan anropa från Infrastruktur-portalen, från ett annat infrastrukturobjekt eller från ett externt program med hjälp av den angivna REST-slutpunkten. Varje funktion är en metod i Python-skriptet som gör det möjligt att skicka parametrar och returnera utdata till anroparen. Programmeringsmodellen Användardatafunktioner innehåller följande komponenter:

fabric.functions-biblioteket innehåller den kod som du behöver för att skapa användardatafunktioner i Python. Du kan se att det här biblioteket importeras i din första funktionsmall när du skapar ett nytt användardatafunktionsobjekt.
Metoden fn.UserDataFunctions() tillhandahåller körningskontexten som finns i början av kodfilen inom alla nya användardatafunktioners objekt, före några funktionsdefinitioner.

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

udf = fn.UserDataFunctions()
```

Varje funktion identifieras med en @udf.function() dekorator. Den här dekoratören definierar om din funktion kan anropas individuellt från portalen eller en extern anropare. Om du använder den här dekoratören måste funktionen också ha ett returvärde. Funktioner med @udf.connection-dekoratören kan komma åt de anslutningsobjekt som anges av dekoratören.

Exempel på anropbar funktion

# 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 utan @udf.function() dekoratör kan inte anropas direkt. De kan bara anropas från funktioner som innehåller dekoratören och kan användas som hjälpfunktioner.

hjälpfunktionsexempel

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

Indatatyper som stöds

Du kan definiera indataparametrar för funktionen, till exempel primitiva datatyper som str, int, float osv. De indatatyper som stöds är:

JSON-typ	Python-datatyp
Sträng	Str
Datum och tid-sträng	tidpunkt
Boolesk	Bool
Tal	int, float
Array	list[], exempellista[int]
Objekt	Dict
Objekt	Pandas DataFrame
Objekt eller matris med objekt	Pandas-serien

Anmärkning

Om du vill använda pandas DataFrame- och serietyper väljer du Bibliotekshantering i Infrastrukturportalen för din användardatafunktion och uppdaterar fabric-user-data-function version till 1.0.0.

Exempel på begärandetext för indatatyper som stöds:

{
  "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öds

De utdatatyper som stöds är:

Python-datatyp
Str
tidpunkt
Bool
int, float
list[data-type], till exempel list[int]
Dict
Ingen
Pandas-serien
Pandas DataFrame

Så här skriver du en asynkron funktion

Lägg till async-dekoratör i din funktionsdefinition i koden. Med en async funktion kan du förbättra svarstiden och effektiviteten i ditt program genom att hantera flera uppgifter samtidigt. De är idealiska för att hantera stora volymer av I/O-bundna åtgärder. Den här exempelfunktionen läser en CSV-fil från ett lakehouse-system med pandas. Funktionen tar filnamnet som en indataparameter.

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

Dataanslutningar till Fabric-datakällor

Med den här modulen kan du referera till dataanslutningar utan att behöva skriva anslutningssträngar i koden. I fabric.functions-biblioteket finns två sätt att hantera dataanslutningar:

fabric.functions.FabricSqlConnection: Gör att du kan arbeta med SQL-databaser i Fabric, inklusive SQL Analytics-slutpunkter och Fabric-lager.
fabric.functions.FabricLakehouseClient: Låter dig arbeta med Lakehouses, med ett sätt att ansluta till både Lakehouse-tabeller och Lakehouse-filer.

Om du vill referera till en anslutning till en datakälla måste du använda @udf.connection dekorator. Du kan använda den i något av följande format:

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

Argumenten för @udf.connection är:

argName, namnet på variabeln som anslutningen använder i din funktion.
alias, aliaset för anslutningen som du lade till med menyn Hantera anslutningar.
Om argName och alias har samma värde kan du använda @udf.connection("<alias and argName for the data connection>").

Exempel

# 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

Generiska anslutningar för Fabric-komponenter eller Azure-resurser

Med allmänna anslutningar kan du skapa anslutningar till Fabric-objekt eller Azure-resurser med hjälp av användardatafunktionernas ägaridentitet. Den här funktionen genererar en Microsoft Entra-ID-token med objektägarens identitet och en angivet målgruppstyp. Den här token används för att autentisera med Infrastrukturobjekt eller Azure-resurser som stöder den målgruppstypen. Den här processen ger dig en liknande programmeringsupplevelse som att använda hanterade anslutningsobjekt från funktionen Hantera anslutningar , men bara för den angivna målgruppstypen i anslutningen.

Den här funktionen använder dekoratören @udf.generic_connection() med följande parametrar:

Parameter	Beskrivning	Värde
`argName`	Namnet på variabeln som skickas till funktionen. Användaren måste ange den här variabeln i argumenten för sin funktion och använda typen av `fn.FabricItem` för den	Om till exempel `argName=CosmosDb`, ska funktionen innehålla det här argumentet `cosmosDb: fn.FabricItem`
`audienceType`	Den typ av målgrupp som anslutningen skapas för. Den här parametern är associerad med typen av Fabric-objekt eller Azure-tjänst och avgör vilken klient som används för anslutningen.	De tillåtna värdena för den här parametern är `CosmosDb` eller `KeyVault`.

Ansluta till Cosmos DB-container med en generisk anslutning

Allmänna anslutningar stöder interna Fabric Cosmos DB-objekt med hjälp av målgruppstypen CosmosDB . Den inkluderade SDK:t för användardatafunktioner innehåller en hjälpmetod som heter get_cosmos_client som hämtar en singleton Cosmos DB-klient för varje anrop.

Du kan ansluta till ett Fabric Cosmos DB-objekt med hjälp av en allmän anslutning genom att följa dessa steg:

I din Fabric-användardatafunktionspost installerar du azure-cosmos-biblioteket med hjälp av bibliotekshanteringsmiljön.
Gå till inställningarna för Fabric Cosmos DB-objekt .
Hämta Fabric Cosmos DB-slutpunktens URL.

Gå till objektet Användardatafunktioner. Använd följande exempelkod för att ansluta till din Fabric Cosmos DB-container och köra en läsfråga med hjälp av Cosmos DB-exempeldatauppsättningen. Ersätt värdena för följande variabler:

COSMOS_DB_URI med din Fabric Cosmos DB-slutpunkt.
DB_NAME med namnet på ditt Fabric Cosmos DB-objekt.

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)

Testa eller kör den här funktionen genom att ange ett kategorinamn, till exempel Accessory i anropsparametrarna.

Anmärkning

Du kan också använda de här stegen för att ansluta till en Azure Cosmos DB-databas med hjälp av konto-URL:en och databasnamnen. Användardatafunktionernas ägarkonto skulle behöva åtkomstbehörigheter till det Azure Cosmos DB-kontot.

Ansluta till Azure Key Vault med en allmän anslutning

Allmänna anslutningar stöder anslutning till ett Azure Key Vault med hjälp av målgruppstypen KeyVault . Den här typen av anslutning kräver att ägaren av Användardatafunktioner för infrastrukturresurser har behörighet att ansluta till Azure Key Vault. Du kan använda den här anslutningen för att hämta nycklar, hemligheter eller certifikat efter namn.

Du kan ansluta till Azure Key Vault för att hämta en klienthemlighet för att anropa ett API med hjälp av en allmän anslutning genom att följa dessa steg:

I ditt Fabric-användardatafunktioner-objekt installerar du requests och azure-keyvault-secrets biblioteken med hjälp av upplevelsen för bibliotekshantering.
Gå till din Azure Key Vault-resurs och hämta Vault URI och namnet på din nyckel, hemlighet eller certifikat.

Gå tillbaka till Fabric Användardatafunktioner och använd det här exemplet. I det här exemplet hämtar vi en hemlighet från Azure Key Vault för att ansluta till ett offentligt API. Ersätt värdet för följande variabler:

KEY_VAULT_URL med det Vault URI hämtade i föregående steg.
KEY_VAULT_SECRET_NAME med namnet på din hemlighet.
API_URL variabel med URL:en för det API som du vill ansluta till. Det här exemplet förutsätter att du ansluter till ett offentligt API som accepterar GET-begäranden och tar följande parametrar api-key och 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}"

Testa eller kör den här funktionen genom att ange en begärandetext i koden.

Hämta anropsegenskaper med hjälp av `UserDataFunctionContext`

Programmeringsmodellen innehåller även UserDataFunctionContext-objektet. Det här objektet innehåller funktionens anropsmetadata och kan användas för att skapa specifik applogik för vissa anropsmekanismer.

I följande tabell visas egenskaperna för UserDataFunctionContext-objektet:

Egenskapsnamn	Datatyp	Beskrivning
Anrops-ID	sträng	Den unika identifieraren (GUID) som är kopplad till anropet av objektet för användardatafunktionerna.
Exekverande användare	objekt	Metadata för användarens information som används för att auktorisera anropet.

Objektet ExecutingUser innehåller följande information:

Egenskapsnamn	Datatyp	Beskrivning
Oid	sträng (GUID)	Användarens objekt-ID, som är en oföränderlig identifierare för beställaren. Det här är den verifierade identiteten för användaren eller tjänstens huvudnamn som används för att anropa den här funktionen i olika program.
Hyresgäst-ID	sträng (GUID)	ID:t för den klientorganisation som användaren är inloggad på.
FöredragetAnvändarnamn	sträng	Det föredragna användarnamnet för den anropande användaren enligt användarens inställning. Det här värdet kan ändras.

Om du vill komma åt parametern UserDataFunctionContext måste du använda följande dekoratör överst i funktionsdefinitionen: @udf.context(argName="<parameter name>")

Exempel

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

Kastar ett hanterat fel med `UserThrownError`

När du utvecklar din funktion kan du utlösa ett förväntat felsvar med hjälp av den UserThrownError metod som är tillgänglig i Python-programmeringsmodellen. Ett användningsområde för denna metod är att hantera fall där användarindata inte uppfyller affärsreglerna.

Exempel

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

Den här UserThrownError metoden tar två parametrar:

Message: Den här strängen returneras som felmeddelande till programmet som anropar den här funktionen.
En ordlista med egenskaper returneras till programmet som anropar den här funktionen.

Hämta variabler från Fabric-variabelbibliotek

Ett Fabric-variabelbibliotek i Microsoft Fabric är en centraliserad lagringsplats för hantering av variabler som kan användas över olika objekt i en arbetsyta. Det gör att utvecklare kan anpassa och dela objektkonfigurationer effektivt.

Lägg till en anslutning till ett variabelbibliotek med hantera anslutningar och hämta aliaset för variabelbiblioteksobjektet.
Lägg till en anslutningsdekoratör @udf.connection(argName="varLib", alias="<My Variable Library Alias>") för att referera till aliaset för variabelbiblioteksobjektet.
I funktionsdefinitionen inkluderar du ett argument med typen fn.FabricVariablesClient. Den här klienten innehåller metoder som du behöver för att arbeta med biblioteksobjektet variabler. Till exempel: def standardize_date(rawDate: str, varLib: fn.FabricVariablesClient) -> str:
Använd getVariables() metoden för att hämta alla variabler från variabelbiblioteket.

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

1 Om du vill läsa värdena för variablerna använder du antingen ["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")

Feedback

Var den här sidan till hjälp?

Last updated on 2025-11-10