Přehled programovacího modelu datových funkcí Fabric User

Programovací model uživatelských datových funkcí Fabric definuje vzory a koncepty pro vytváření funkcí ve Fabric.

Sada fabric-user-data-functions SDK implementuje tento programovací model, který poskytuje nezbytné funkce pro vytváření a publikování spustitelných funkcí. Sada SDK také umožňuje bezproblémovou integraci s dalšími prvky v ekosystému Fabric, jako jsou zdroje dat Fabric. Tato knihovna je veřejně dostupná v PyPI a je předinstalovaná v položkách uživatelských datových funkcí.

Tento článek vysvětluje, jak pomocí sady SDK sestavovat funkce, které je možné vyvolat z portálu Fabric, dalších položek infrastruktury nebo externích aplikací pomocí rozhraní REST API. S praktickými příklady se seznámíte s programovacím modelem a klíčovými koncepty.

Návod

Úplné podrobnosti o všech třídách, metodách a parametrech najdete v referenční dokumentaci k sadě SDK.

Začněme s SDK

Tato část představuje základní komponenty sady SDK služby User Data Functions a vysvětluje, jak strukturovat funkce. Dozvíte se o požadovaných importech, dekorátorech a typech vstupních a výstupních dat, která vaše funkce dokážou zpracovat.

Sada SDK pro funkce uživatelských dat

Sada fabric-user-data-functions SDK poskytuje základní komponenty, které potřebujete k vytvoření funkcí uživatelských dat v Pythonu.

Požadované importy a inicializace

Každý soubor uživatelských datových funkcí musí importovat fabric.functions modul a inicializovat kontext spuštění:

import datetime
import fabric.functions as fn
import logging

udf = fn.UserDataFunctions()

Dekorátor @udf.function()

Funkce označené dekorátorem @udf.function() se dají vyvolat z portálu Fabric, z jiné položky Fabric nebo z externí aplikace. Funkce s tímto dekorátorem musí určovat návratový typ.

Příklad:

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

Pomocné funkce

Metody Pythonu bez dekorátoru @udf.function() nelze vyvolat přímo. Mohou být volány pouze ze dekorovaných funkcí a slouží jako pomocných funkcí.

Příklad:

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

Podporované vstupní typy

Můžete definovat vstupní parametry pro funkci, jako jsou primitivní datové typy, jako je str, int, float atd. Podporované vstupní datové typy jsou:

Typ JSON	Datový typ Python
Řetězec	Str
řetězec data a času	datetime
Booleova logika	Booleova hodnota
Čísla	int (celé číslo), float (desetinné číslo)
Pole	seznam[], příklad seznam[celočíselný]
Objekt	slovník
Objekt	Datový rámec pandas
Objekt nebo pole objektů	Pandas Series

Poznámka:

Pokud chcete použít datový rámec pandas a typy řad, přejděte na portál Fabric, vyhledejte pracovní prostor a otevřete položku funkcí uživatelských dat. Vyberte správu knihovny, vyhledejte fabric-user-data-functions balíček a aktualizujte ho na verzi 1.0.0 nebo novější.

Příklad textu požadavku pro podporované typy vstupu:

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

Podporované typy výstupu

Podporované výstupní datové typy jsou:

Datový typ Python
Str
datetime
Booleova hodnota
int (celé číslo), float (desetinné číslo)
list[datový typ], například list[int]
slovník
Žádný
Pandas Series
Datový rámec pandas

Psaní funkcí

Požadavky na syntaxi a omezení

Při psaní funkcí uživatelských dat musíte postupovat podle konkrétních pravidel syntaxe, abyste měli jistotu, že vaše funkce fungují správně.

Pojmenování parametrů

Použití camelCase: Názvy parametrů musí používat konvenci pojmenování camelCase a nesmí obsahovat podtržítka. Například použijte productName místo product_name.
Vyhrazená klíčová slova: Nemůžete použít vyhrazená klíčová slova Pythonu nebo následující klíčová slova specifická pro Fabric jako názvy parametrů nebo názvy funkcí: req, context a reqInvocationId.

Požadavky na parametry

Žádné výchozí hodnoty: Výchozí hodnoty parametrů nejsou podporovány. Při vyvolání funkce jsou vyžadovány všechny parametry. Například následující funkce vyvolá chybu syntaxe:

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

Povinné poznámky typu: Všechny parametry musí obsahovat poznámky typu (například name: str).

Požadavky na funkce

Povinný návratový typ: Funkce s dekorátorem @udf.function() musí určovat návratovou poznámku typu (například -> str).
Požadované importy: Příkaz import fabric.functions as fn a udf = fn.UserDataFunctions() inicializace jsou vyžadovány pro fungování vašich funkcí.

Příklad správné syntaxe

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

Jak napsat asynchronní funkci

Přidejte asynchronní dekorátor s definicí funkce v kódu. async Díky funkci můžete zlepšit rychlost odezvy a efektivitu aplikace tím, že budete zpracovávat více úloh najednou. Jsou ideální pro správu velkých objemů vstupně-výstupních operací. Tato ukázková funkce načte soubor CSV z datového jezera pomocí knihovny pandas. Funkce přebírá název souboru jako vstupní parametr.

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

Práce s daty

Datová připojení ke zdrojům dat Fabric

Sada SDK umožňuje odkazovat na datová připojení bez nutnosti psaní připojovacích řetězců v kódu. Knihovna fabric.functions nabízí dva způsoby správy datových připojení:

fabric.functions.FabricSqlConnection: Umožňuje pracovat s databázemi SQL v Fabric, včetně koncových bodů SQL Analytics a Fabric skladů.
cs-CZ: fabric.functions.FabricLakehouseClient: Umožňuje pracovat s Lakehouses a zároveň poskytuje možnost připojení k tabulkám Lakehouse i souborům Lakehouse.

Pokud chcete odkazovat na připojení ke zdroji dat, musíte použít dekorátor @udf.connection. Můžete ho použít v některém z následujících formátů:

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

Argumenty k @udf.connection jsou:

argName, název proměnné, která připojení používá ve vaší funkci.
alias, alias připojení, které jste přidali pomocí nabídky Spravovat připojení.
Pokud argName a alias mají stejnou hodnotu, můžete použít @udf.connection("<alias and argName for the data connection>").

Příklad

# 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

Obecná připojení pro položky služby Fabric nebo prostředky Azure

Sada SDK podporuje obecná připojení, která umožňují vytvářet připojení k položkám infrastruktury nebo prostředkům Azure pomocí identity vlastníka položky služby User Data Functions. Tato funkce vygeneruje token ID Microsoft Entra s identitou vlastníka položky a zadaným typem cílové skupiny. Tento token se používá k ověřování pomocí položek infrastruktury nebo prostředků Azure, které podporují tento typ cílové skupiny. Tento přístup poskytuje podobné programovací prostředí, jako je použití objektů spravovaných připojení z funkce Spravovat připojení , ale pouze pro zadaný typ cílové skupiny v připojení.

Tato funkce používá @udf.generic_connection() dekorátor s následujícími parametry:

Parameter	Popis	Hodnota
`argName`	Název proměnné, která je předána funkci. Uživatel musí tuto proměnnou zadat v argumentech své funkce a použít pro ni typ.`fn.FabricItem`	Pokud `argName=CosmosDb`by například funkce měla tento argument obsahovat. `cosmosDb: fn.FabricItem`
`audienceType`	Typ cílové skupiny, pro kterou je připojení vytvořeno. Tento parametr je přidružený k typu položky Infrastruktury nebo služby Azure a určuje klienta, který se pro připojení používá.	Povolené hodnoty pro tento parametr jsou `CosmosDb` nebo `KeyVault`.

Připojení ke kontejneru Fabric Cosmos DB pomocí obecného připojení

Obecná připojení podporují nativní položky služby Fabric Cosmos DB díky použití typu CosmosDB audience. Zahrnutá sada SDK pro uživatelské datové funkce poskytuje pomocnou metodu nazvanou get_cosmos_client, která načítá klienta typu singleton pro Cosmos DB při každém vyvolání.

K položce služby Fabric Cosmos DB se můžete připojit pomocí obecného připojení pomocí následujícího postupu:

Přejděte na portál Fabric, vyhledejte pracovní prostor a otevřete položku funkcí uživatelských dat. Vyberte správu knihovny, vyhledejte knihovnu azure-cosmos a nainstalujte ji. Další informace najdete v tématu Správa knihoven.
Přejděte do nastavení položek služby Fabric Cosmos DB .
Načtěte adresu URL koncového bodu služby Fabric Cosmos DB.

Přejděte na položku Funkce uživatelských dat. Pomocí následujícího ukázkového kódu se připojte ke kontejneru Služby Fabric Cosmos DB a spusťte dotaz pro čtení pomocí ukázkové datové sady Cosmos DB. Nahraďte hodnoty následujících proměnných:

COSMOS_DB_URI s koncovým bodem služby Fabric Cosmos DB.
DB_NAME s názvem položky Fabric Cosmos DB.

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)

Otestujte nebo spusťte tuto funkci zadáním názvu kategorie, například Accessory v parametrech vyvolání.

Poznámka:

Pomocí těchto kroků se také můžete připojit k databázi Azure Cosmos DB pomocí adresy URL účtu a názvů databází. Účet vlastníka služby User Data Functions by potřeboval přístupová oprávnění k danému účtu služby Azure Cosmos DB.

Připojení ke službě Azure Key Vault pomocí obecného připojení

Obecná připojení podporují připojení ke službě Azure Key Vault s využitím audience type KeyVault. Tento typ připojení vyžaduje, aby vlastník služby Fabric User Data Functions má oprávnění k připojení ke službě Azure Key Vault. Pomocí tohoto připojení můžete načíst klíče, tajné kódy nebo certifikáty podle názvu.

Pomocí následujícího postupu se můžete připojit ke službě Azure Key Vault a načíst tajný klíč klienta pro volání rozhraní API pomocí obecného připojení:

Přejděte na portál Fabric, vyhledejte pracovní prostor a otevřete položku funkcí uživatelských dat. Vyberte Správa knihovny a pak vyhledejte a nainstalujte requestsazure-keyvault-secrets knihovny. Další informace najdete v tématu Správa knihoven.
Přejděte k prostředku služby Azure Key Vault v Azure portálu a zjistěte název vašeho klíče, tajného klíče nebo certifikátu.

Vraťte se k položce Funkce uživatelských dat Fabric a použijte tuto ukázku. V této ukázce načteme tajný kód ze služby Azure Key Vault pro připojení k veřejnému rozhraní API. Nahraďte hodnotu následujících proměnných:

Nahraďte KEY_VAULT_URL hodnotou Vault URI, kterou jste načetli v předchozím kroku.
KEY_VAULT_SECRET_NAME s názvem tvého tajemství.
API_URL proměnná s adresou URL rozhraní API, ke kterému se chcete připojit. Tato ukázka předpokládá, že se připojujete k veřejnému rozhraní API, které přijímá požadavky GET, a přijímá následující parametry api-key a 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}"

Otestujte nebo spusťte tuto funkci tak, že do kódu poskytnete text požadavku.

Rozšířené funkce

Programovací model definuje pokročilé vzory, které poskytují větší kontrolu nad vašimi funkcemi. Sada SDK implementuje tyto vzory prostřednictvím tříd a metod, které umožňují:

Přístup k metadatům volání o tom, kdo volal vaši funkci a jak
Zpracování vlastních chybových scénářů pomocí strukturovaných chybových odpovědí
Integrace s knihovnami proměnných Fabric pro centralizovanou správu konfigurace

Poznámka:

Služba User Data Functions má omezení služby pro velikost požadavku, časový limit pro spuštění a velikost odpovědi. Podrobnosti o těchto omezeních a jejich vynucení najdete v tématu Podrobnosti o službě a omezení.

Získání vlastností vyvolání pomocí `UserDataFunctionContext`

Sada SDK obsahuje UserDataFunctionContext objekt. Tento objekt obsahuje metadata volání funkce a lze ji použít k vytvoření konkrétní logiky aplikace pro různé mechanismy vyvolání (například vyvolání portálu a vyvolání rozhraní REST API).

Následující tabulka ukazuje vlastnosti objektu UserDataFunctionContext:

Název vlastnosti	Datový typ	Popis
identifikátor_vyvolání	řetězec	Jedinečný identifikátor GUID svázaný s vyvoláním položky funkcí uživatelských dat.
provádějící_uživatel	objekt	Metadata informací uživatele použitých k autorizaci vyvolání

Objekt executing_user obsahuje následující informace:

Název vlastnosti	Datový typ	Popis
Oid	řetězec (GUID)	ID objektu uživatele, což je neměnný identifikátor žadatele. Jedná se o ověřenou identitu uživatele nebo instančního objektu použitého k vyvolání této funkce napříč aplikacemi.
Id nájemníka	řetězec (GUID)	ID tenanta, ke kterému je uživatel přihlášený.
Preferované uživatelské jméno	řetězec	Upřednostňované uživatelské jméno uživatele, který akci vyvolává, jak je nastaveno samotným uživatelem. Tato hodnota je proměnlivá.

Pokud chcete získat přístup k parametru UserDataFunctionContext , musíte v horní části definice funkce použít následující dekorátor: @udf.context(argName="<parameter name>")

Příklad

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

Vyvolejte ošetřenou chybu s `UserThrownError`

Při vývoji funkce můžete vyvolat očekávanou chybovou odpověď pomocí UserThrownError třídy dostupné v sadě SDK. Jedním z použití této třídy je řízení případů, kdy vstupy poskytnuté uživatelem neprojdou obchodními ověřovacími pravidly.

Příklad

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

Konstruktor UserThrownError třídy má dva parametry:

Message: Tento řetězec se vrátí jako chybová zpráva aplikace, která vyvolá tuto funkci.
Slovník vlastností se vrátí do aplikace, která tuto funkci vyvolá.

Získání proměnných z knihoven proměnných Fabric

Knihovna proměnných v Microsoft Fabric je centralizované úložiště pro správu proměnných, které lze používat napříč různými položkami v rámci pracovního prostoru. Umožňuje vývojářům efektivně přizpůsobovat a sdílet konfigurace položek. Pokud ještě knihovnu proměnných nemáte, přečtěte si téma Vytvoření a správa knihoven proměnných.

Chcete-li ve svých funkcích použít knihovnu proměnných, přidáte k ní připojení z položky funkcí uživatelských dat. Knihovny proměnných se zobrazují v katalogu OneLake společně se zdroji dat, jako jsou databáze SQL a datová jezírka.

Pokud chcete ve svých funkcích používat knihovny proměnných, postupujte takto:

V položce funkcí uživatelských dat přidejte připojení k knihovně proměnných. V katalogu OneLake vyhledejte a vyberte knihovnu proměnných a pak vyberte Připojit. Všimněte si Aliasu, který pro připojení generuje Fabric.
Přidejte dekorátor připojení pro položku v knihovně proměnných. Můžete například @udf.connection(argName="varLib", alias="<My Variable Library Alias>") nahradit alias nově přidaného připojení pro položku knihovny proměnných.
Do definice funkce zahrňte argument s typem fn.FabricVariablesClient. Tento klient poskytuje metody, které potřebujete pro práci s položkou knihovny proměnných.
Pomocí metody získejte getVariables() všechny proměnné z knihovny proměnných.
Ke čtení hodnot proměnných se používají buď ["variable-name"] nebo .get("variable-name").

Příklad

V tomto příkladu simulujeme scénář konfigurace pro produkční a vývojové prostředí. Tato funkce nastaví cestu k úložišti v závislosti na vybraném prostředí pomocí hodnoty načtené z knihovny proměnných. Knihovna proměnných obsahuje proměnnou s názvem ENV , ve které mohou uživatelé nastavit hodnotu dev nebo prod.

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

Referenční dokumentace k rozhraní API
Vytvořit položku funkce dat uživatele pro Fabric
Ukázky funkcí dat uživatelů

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-01-22

Sdílet prostřednictvím

Přehled programovacího modelu datových funkcí Fabric User

Začněme s SDK

Sada SDK pro funkce uživatelských dat

Požadované importy a inicializace

Dekorátor @udf.function()

Pomocné funkce

Podporované vstupní typy

Podporované typy výstupu

Psaní funkcí

Požadavky na syntaxi a omezení

Pojmenování parametrů

Požadavky na parametry

Požadavky na funkce

Příklad správné syntaxe

Jak napsat asynchronní funkci

Práce s daty

Datová připojení ke zdrojům dat Fabric

Příklad

Obecná připojení pro položky služby Fabric nebo prostředky Azure

Připojení ke kontejneru Fabric Cosmos DB pomocí obecného připojení

Připojení ke službě Azure Key Vault pomocí obecného připojení

Rozšířené funkce

Získání vlastností vyvolání pomocí UserDataFunctionContext

Vyvolejte ošetřenou chybu s UserThrownError

Získání proměnných z knihoven proměnných Fabric

Příklad

Související obsah

Váš názor

Další materiály

Získání vlastností vyvolání pomocí `UserDataFunctionContext`

Vyvolejte ošetřenou chybu s `UserThrownError`