Prehľad programovacieho modelu používateľských dátových funkcií štruktúry

Model programovania dátových funkcií používateľa služby Fabric je súprava SDK, ktorá poskytuje potrebné funkcie na vytváranie a publikovanie runnable funkcií v službe Fabric. Súprava SDK vám tiež umožňuje bezproblémovú integráciu s inými položkami v ekosystéme služby Fabric, ako sú napríklad zdroje údajov služby Fabric. Táto knižnica je verejne dostupná v PyPI a je predinštalovaná v položkách údajových funkcií používateľa.

Súprava SDK funkcií údajov používateľov

Položka údajových funkcií používateľa obsahuje jednu alebo viacero funkcií, ktoré môžete vyvolať z portálu služby Fabric, z inej položky služby Fabric alebo z externej aplikácie pomocou uvedeného koncového bodu REST. Každá funkcia je metóda v skripte jazyka Python, ktorá umožňuje odovzdávanie parametrov a vrátenie výstupu do vyvolávača. Programovací model dátových funkcií používateľa obsahuje nasledujúce súčasti:

Knižnica fabric.functions poskytuje kód, ktorý potrebujete na vytvorenie používateľských údajových funkcií v jazyku Python. Keď vytvoríte novú položku údajových funkcií používateľa, táto knižnica sa importuje do vašej prvej šablóny funkcie.
Metóda fn.UserDataFunctions() poskytuje kontext spustenia, ktorý sa nachádza na začiatku súboru s kódom vo všetkých nových položkách údajových funkcií používateľa pred definíciami funkcie.

Príklad:
```
import datetime
import fabric.functions as fn
import logging

udf = fn.UserDataFunctions()
```
Každá funkcia je identifikovaná pomocou dekorátora @udf.function(). Tento dekorátor definuje, či je možné funkciu vyvolať individuálne z portálu alebo externého vyvolávača. Použitie tohto dekorátora tiež vyžaduje, aby funkcia mala vrátenú hodnotu. Funkcie s týmto dekorátorom majú prístup k objektom pripojenia označeným dekoratérom @udf.connection .

príklad invokable funkcie
```
# 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()}!"
```

Akékoľvek metódy jazyka Python bez dekorátora @udf.function() nie je možné priamo vyvolať. Môžu sa vyvolať iba z funkcií, ktoré obsahujú dekorátor, a môžu sa použiť ako pomocné funkcie.

príklad funkcie helper

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

Podporované typy vstupov

Môžete definovať vstupné parametre pre funkciu, ako sú napríklad primitívne typy údajov, ako napríklad str, int, float atď. Podporované typy vstupných údajov sú:

typu JSON	typ údajov jazyka Python
Povrázok	Str
reťazca datetime	Datetime
Boolean	Bool
Numbers	int, plavák
Pole	list[], príklad zoznamu[int]
objektu	Dict
objektu	Dátový rámec pandas
Objekt alebo pole objektov	séria pandas

Poznámka

Ak chcete používať pandas dataframe a typy radov, vyberte položku Správa knižníc na portáli služby Fabric pre svoju používateľskú údajovú funkciu a aktualizujte fabric-user-data-function verziu na 1.0.0.

Príklad textu požiadavky pre podporované typy vstupov:

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

Podporované typy výstupu

Podporované typy údajov výstupu sú:

typ údajov jazyka Python
Str
Datetime
Bool
int, plavák
list[data-type], napríklad list[int]
Dict
žiadne
séria pandas
Dátový rámec pandas

Ako napísať asynchrónne funkcie

Pridajte asynchrónny dekorátor s definíciou funkcie v kóde. Vďaka funkcii async môžete zlepšiť odozvu a efektivitu aplikácie spracovávaním viacerých úloh naraz. Sú ideálne na správu veľkého objemu vstupno-výstupných operácií. Funkcia v tomto príklade prečíta súbor CSV z jazera pomocou pandy. Funkcia použije názov súboru ako vstupný parameter.

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

Údajové pripojenia k zdrojom údajov služby Fabric

Tento modul vám umožňuje odkazovať na údajové pripojenia bez nutnosti zapisovania reťazcov pripojenia do kódu. Knižnica fabric.functions poskytuje dva spôsoby na spracovanie údajových pripojení:

fabric.functions.FabricSqlConnection: Umožňuje pracovať s databázami SQL v službe Fabric vrátane koncových bodov služby SQL Analytics a skladov služby Fabric.
fabric.functions.FabricLakehouseClient: Umožňuje vám pracovať s lakehouses, so spôsobom, ako sa pripojiť k obom lakehouse tabuliek a Lakehouse súbory.

Ak chcete odkazovať na pripojenie k zdroju údajov, musíte použiť dekorátor @udf.connection. Môžete ju použiť v ktoromkoľvek z nasledujúcich formátov:

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

Argumenty pre @udf.connection sú:

argName, názov premennej, ktorá pripojenie používa vo vašej funkcii.
alias, alias pripojenia, ktoré ste pridali, pomocou ponuky Spravovať pripojenia.
Ak argName a alias majú rovnakú hodnotu, môžete použiť @udf.connection("<alias and argName for the data connection>").

Prí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:
  # 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

Všeobecné pripojenia pre položky služby Fabric alebo prostriedky Azure

Všeobecné pripojenia umožňujú vytvárať pripojenia k položkám služby Fabric alebo prostriedkom Azure pomocou identity vlastníka položky funkcie používateľských údajov. Táto funkcia generuje token Microsoft Entra ID s identitou vlastníka položky a zadaným typom cieľovej skupiny. Tento token sa používa na overenie pomocou položiek služby Fabric alebo prostriedkov Azure, ktoré podporujú daný typ cieľovej skupiny. Tento proces vám poskytne podobné programovacie prostredie ako pri používaní spravovaných objektov pripojení z funkcie Spravovať pripojenia , ale iba pre zadaný typ cieľovej skupiny v pripojení.

Táto funkcia @udf.generic_connection() používa dekoratér s nasledujúcimi parametrami:

Parameter	Popis	Value
`argName`	Názov premennej, ktorá sa odovzdáva funkcii. Používateľ musí špecifikovať túto premennú v argumentoch svojej funkcie a použiť pre ňu typ `fn.FabricItem`	Ak by napríklad funkcia `argName=CosmosDb`mala obsahovať tento argument `cosmosDb: fn.FabricItem`
`audienceType`	Typ cieľovej skupiny, pre ktorú je pripojenie vytvorené. Tento parameter je priradený k typu položky Fabric alebo služby Azure a určuje klienta použitého pre pripojenie.	Povolené hodnoty pre tento parameter sú `CosmosDb` alebo `KeyVault`.

Pripojenie ku kontajneru služby Fabric Cosmos DB pomocou všeobecného pripojenia

Všeobecné pripojenia podporujú natívne položky služby Fabric Cosmos DB pomocou CosmosDB typu cieľovej skupiny. Zahrnutá súprava User Data Functions SDK poskytuje pomocnú metódu s názvom get_cosmos_client Helper, ktorá načíta jedného klienta Cosmos DB pre každé vyvolanie.

K položke služby Fabric Cosmos DB sa môžete pripojiť pomocou všeobecného pripojenia podľa týchto krokov:

V položke Fabric User Data Functions nainštalujte knižnicu azure-cosmos pomocou prostredia Správa knižnice.
Prejdite do nastavení položiek služby Fabric Cosmos DB .
Načítajte URL adresu koncového bodu služby Fabric Cosmos DB.

Prejdite na položku Funkcie používateľských údajov. Pomocou nasledujúceho vzorového kódu sa pripojte ku kontajneru služby Fabric Cosmos DB a spustite dotaz na čítanie pomocou vzorovej množiny údajov služby Cosmos DB. Nahraďte hodnoty nasledujúcich premenných:

COSMOS_DB_URI s koncovým bodom služby Fabric Cosmos DB.
DB_NAME s názvom položky služby 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 alebo spustite túto funkciu zadaním názvu kategórie, napríklad Accessory v parametroch vyvolania.

Poznámka

Tieto kroky môžete použiť aj na pripojenie k databáze služby Azure Cosmos DB pomocou URL adresy konta a názvov databázy. Konto vlastníka funkcie používateľských údajov bude potrebovať prístupové povolenia k tomuto kontu služby Azure Cosmos DB.

Pripojenie k Azure Key Vault pomocou všeobecného pripojenia

Všeobecné pripojenia podporujú pripojenie k Azure Key Vault pomocou KeyVault typu cieľovej skupiny. Tento typ pripojenia vyžaduje, aby vlastník služieb Fabric User Data Functions mal povolenia na pripojenie k Azure Key Vault. Toto pripojenie môžete použiť na načítanie kľúčov, tajných kódov alebo certifikátov podľa názvu.

Môžete sa pripojiť k Azure Key Vault a načítať tajný kľúč klienta na volanie rozhrania API pomocou všeobecného pripojenia podľa týchto krokov:

V položke Fabric User Data Functions nainštalujte knižnice requests a knižnice azure-keyvault-secrets pomocou prostredia Správa knižnice.
Prejdite do prostriedku Azure Key Vault a načítajte Vault URI a názov kľúča, tajného kľúča alebo certifikátu.

Vráťte sa k položke Fabric User Data Functions a použite túto ukážku. V tejto ukážke načítame tajný kľúč z Azure Key Vault na pripojenie k verejnému rozhraniu API. Nahraďte hodnotu nasledujúcich premenných:

KEY_VAULT_URL s možnosťou, ktorú Vault URI ste načítali v predchádzajúcom kroku.
KEY_VAULT_SECRET_NAME s názvom vášho tajomstva.
API_URL s URL adresou rozhrania API, ku ktorému sa chcete pripojiť. V tejto ukážke sa predpokladá, že sa pripájate k verejnému rozhraniu API, ktoré prijíma požiadavky GET a preberá nasledujúce parametre 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 alebo spustite túto funkciu zadaním tela požiadavky v kóde.

Získanie vlastností vyvolania pomocou `UserDataFunctionContext`

Programovací model obsahuje aj objekt UserDataFunctionContext. Tento objekt obsahuje metaúdaje vyvolania funkcie a možno ho použiť na vytvorenie špecifickej logiky aplikácie pre určité mechanizmy vyvolania.

Nasledujúca tabuľka zobrazuje vlastnosti pre UserDataFunctionContext objekt:

Názov vlastnosti	Typ údajov	Popis
ID vyvolania	reťazec	Jedinečný identifikátor GUID zviazaný s vyvolanie položky údajových funkcií používateľa.
ExecutingUser (VykonávajúciPouýšer)	objekt	Metaúdaje informácií o používateľovi použité na overenie vyvolania.

Objekt ExecutingUser obsahuje nasledujúce informácie:

Názov vlastnosti	Typ údajov	Popis
Oid	Reťazec (GUID)	ID objektu používateľa, ktoré je nemenným identifikátorom žiadateľa. Ide o overenú identitu používateľa alebo objektu služby, ktorá sa použila na vyvolanie tejto funkcie v rámci aplikácií.
ID nájomníka	Reťazec (GUID)	ID nájomníka, do ktorému je používateľ prihlásený.
PreferredUsername	reťazec	Preferované meno používateľa na vyvolanie, ako je nastavené používateľom. Táto hodnota je mutable.

Ak chcete získať prístup k parametru UserDataFunctionContext, musíte použiť nasledujúci dekorátor v hornej časti definície funkcie: @udf.context(argName="<parameter name>")

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

Hodiť spracovanú chybu s `UserThrownError`

Pri vývoji funkcie môžete hodiť očakávanú chybovú odpoveď pomocou metódy UserThrownError, ktorá je k dispozícii v programovacom modeli jazyka Python. Jednou z použitia tejto metódy je spravovanie prípadov, keď vstupy poskytnuté používateľom neprejdú pravidlami podnikovej overenia.

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

Táto UserThrownError metóda má dva parametre:

Message: Tento reťazec sa vráti ako chybové hlásenie aplikácii, ktorá vyvoláva túto funkciu.
Slovník vlastností sa vráti do aplikácie, ktorá vyvoláva túto funkciu.

Získanie premenných z knižníc premenných štruktúry

Knižnica premenných štruktúry v službe Microsoft Fabric je centralizované odkladacie zariadenie na správu premenných, ktoré možno použiť v rôznych položkách v rámci pracovného priestoru. Umožňuje vývojárom efektívne prispôsobovať a zdieľať konfigurácie položiek.

Pridajte pripojenie ku knižnici premenných pomocou možnosti Spravovať pripojenia a získajte alias pre položku knižnice premenných.
Pridajte dekorátor pripojenia, @udf.connection(argName="varLib", alias="<My Variable Library Alias>") ktorý bude odkazovať na alias položky knižnice premenných.
Do definície funkcie zahrňte argument s typom fn.FabricVariablesClient. Tento klient poskytuje metódy, ktoré potrebujete na prácu s položkou knižnice premenných. Napríklad def standardize_date(rawDate: str, varLib: fn.FabricVariablesClient) -> str:
Použite getVariables() metódu na získanie všetkých premenných z knižnice premenných.

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

1 Na čítanie hodnôt premenných použite buď ["variable-name"] alebo .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")

Spätná väzba

Bola táto stránka užitočná?

Last updated on 2025-11-10