Fabric User data functions programozási modell áttekintése

A Fabric User adatfüggvény-programozási modell egy SDK, amely biztosítja a futtatható függvények létrehozásához és közzétételéhez szükséges funkciókat a Fabricben. Az SDK-val zökkenőmentesen integrálható a Fabric-ökoszisztéma más elemeivel, például a Fabric-adatforrásokkal. Ez a kódtár nyilvánosan elérhető a PyPI, és előre telepítve van a felhasználói adatfüggvények elemeiben.

Felhasználói adatkezelő SDK

A felhasználói adatfüggvények egy vagy több függvényt tartalmaznak, amelyeket meghívhat a Háló portálról, egy másik Hálóelemből vagy egy külső alkalmazásból a megadott REST-végpont használatával. Minden függvény egy metódus a Python-szkriptben, amely lehetővé teszi a paraméterek átadását és a kimenet visszaadását a meghívónak. A Felhasználói adatfüggvények programozási modellje a következő összetevőket tartalmazza:

A fabric.functions kódtár tartalmazza a felhasználói adatfüggvények Pythonban való létrehozásához szükséges kódot. Új felhasználói adatfüggvény-elem létrehozásakor láthatja, hogy ez a kódtár az első függvénysablonban lesz importálva.
A metódus fn.UserDataFunctions() a kódfájl elején található végrehajtási környezetet biztosítja az összes új felhasználói adatfüggvény-elemben, a függvénydefiníciók előtt.

példa:
```
import datetime
import fabric.functions as fn
import logging

udf = fn.UserDataFunctions()
```
Minden függvényt egy @udf.function() decoratorral azonosítanak. Ez a díszítő eldönti, hogy a függvényt önállóan lehet-e meghívni a portálról vagy egy külső meghívó által. A dekoratőr használatához a függvénynek visszatérési értékkel is rendelkeznie kell. Az ezzel a dekoratőrrel rendelkező függvények hozzáférhetnek a dekorátor által @udf.connection kijelölt kapcsolati objektumokhoz.

Hívható függvény példa
```
# 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()}!"
```
A @udf.function() dekoratőr nélküli Python-metódusok közvetlenül nem hívhatók meg. Ezek csak a dekoratőrt tartalmazó függvényekből hívhatók meg, és segédfüggvényekként is használhatók.

Segítő függvény példa
```
# 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()
```

Támogatott bemeneti típusok

Megadhat bemeneti paramétereket a függvényhez, például primitív adattípusokat, például str, int, float stb. A támogatott bemeneti adattípusok a következők:

JSON-típus	Python-adattípus
Karakterlánc	Str
Időpont-szöveg	datetime
Boolean	bool
Számok	int, float
Tömb	list[], példalista[int]
objektum	szótár
objektum	pandas DataFrame
Objektum vagy objektumtömb	pandas Series

Megjegyzés:

A pandas DataFrame és Series típusok használatához válassza ki a Könyvtárkezelés opciót a Fabric Portalon a felhasználói adatfüggvényekhez, és frissítse a fabric-user-data-function verziót 1.0.0-ra.

Példa a támogatott bemeneti típusok kérelemtörzsére:

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

Támogatott kimeneti típusok

A támogatott kimeneti adattípusok a következők:

Python-adattípus
Str
datetime
bool
int, float
list[adat-típus], például list[egész szám]
szótár
Egyik sem
pandas Series
pandas DataFrame

Aszinkron függvény írása

Adjon hozzá aszinkron dekorátort a kódban lévő függvénydefiníciójához. async Egy funkcióval több feladat egyidejű kezelésével javíthatja az alkalmazás válaszkészségét és hatékonyságát. Ideálisak nagy mennyiségű I/O-kötött művelet kezeléséhez. Ez a példafüggvény egy CSV-fájlt olvas be egy lakehouse-ból pandas használatával. A függvény bemeneti paraméterként a fájlnevet veszi fel.

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

Adatkapcsolatok Fabric-adatforrásokkal

Ez a modul lehetővé teszi, hogy a adatkapcsolatokra hivatkozzon anélkül, hogy kapcsolati sztringeket kellene írnia a kódban. A fabric.functions kódtár két módon kezeli az adatkapcsolatokat:

fabric.functions.FabricSqlConnection: Lehetővé teszi az SQL-adatbázisok használatát a Fabricben, beleértve az SQL Analytics-végpontokat és a Fabric-raktárakat.
fabric.functions.FabricLakehouseClient: Lehetővé teszi a Lakehouse-okkal való munkát, és lehetővé teszi a Lakehouse-táblákhoz és a Lakehouse-fájlokhoz való csatlakozást.

Az adatforráshoz való kapcsolódáshoz a @udf.connection dekorátort kell használnia. A következő formátumok bármelyikében alkalmazhatja:

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

A @udf.connection argumentumai a következők:

argName, annak a változónak a neve, amelyet a kapcsolat használ a függvényben.
aliasa Kapcsolatok kezelése menüben hozzáadott kapcsolat aliasa.
Ha argName és alias ugyanaz az érték, használhatja a @udf.connection("<alias and argName for the data connection>").

Példa

# 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

Általános kapcsolatok Fabric-elemekhez vagy Azure-erőforrásokhoz

Az általános kapcsolatok lehetővé teszik, hogy a User Data Functions-elem tulajdonosi identitásával kapcsolatot hozzon létre Fabric-elemekhez vagy Azure-erőforrásokhoz. Ez a funkció létrehoz egy Microsoft Entra-azonosító jogkivonatot az elem tulajdonosának identitásával és egy megadott célközönségtípussal. Ez a token a Fabric-elemek vagy Azure-erőforrások hitelesítésére szolgál, amelyek támogatják az adott célcsoporttípust. Ez a folyamat hasonló programozási élményt nyújt a felügyelt kapcsolatok objektumainak a Kapcsolatok kezelése funkcióból való használatához, de csak a kapcsolat megadott célközönségtípusához.

Ez a funkció a @udf.generic_connection() dekorátort használja a következő paraméterekkel:

Paraméter	Leírás	Érték
`argName`	A függvénynek átadott változó neve. A felhasználónak meg kell adnia ezt a változót a függvény argumentumaiban, és használnia `fn.FabricItem` kell annak típusát	Ha például a `argName=CosmosDb`, akkor a függvénynek tartalmaznia kell ezt az argumentumot `cosmosDb: fn.FabricItem`
`audienceType`	A kapcsolat által létrehozott célközönség típusa. Ez a paraméter a Fabric-elem vagy az Azure-szolgáltatás típusához van társítva, és meghatározza a kapcsolathoz használt ügyfelet.	Ennek a paraméternek az engedélyezett értékei a következők `CosmosDb` : vagy `KeyVault`.

Csatlakozás Fabric Cosmos DB-tárolóhoz általános kapcsolat használatával

A generikus csatlakozások a CosmosDB nézőtípus segítségével támogatják a natív Fabric Cosmos DB-elemeket. A mellékelt User Data Functions SDK egy olyan segédmetódust get_cosmos_client biztosít, amely minden híváshoz lekéri a singleton Cosmos DB-ügyfelet.

A Fabric Cosmos DB-elemhez általános kapcsolattal csatlakozhat az alábbi lépések végrehajtásával:

A Fabric User Data Functions elemben telepítse a tárat a azure-cosmosKönyvtárkezelés felület használatával.
Nyissa meg a Fabric Cosmos DB elembeállításait .
Kérje le a Fabric Cosmos DB-végpont URL-címét.

Nyissa meg a Felhasználói adatfüggvények elemet. Az alábbi mintakód használatával csatlakozzon a Fabric Cosmos DB-tárolóhoz, és futtasson egy olvasási lekérdezést a Cosmos DB mintaadatkészlet használatával. Cserélje le a következő változók értékeit:

COSMOS_DB_URI a Fabric Cosmos DB-végponttal.
DB_NAME a(z) Fabric Cosmos DB-elem nevével.

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)

Tesztelje vagy futtassa ezt a függvényt egy kategórianév megadásával, például Accessory a meghívási paraméterekben.

Megjegyzés:

Ezekkel a lépésekkel csatlakozhat egy Azure Cosmos DB-adatbázishoz a fiók URL-címével és adatbázisneveivel. A User Data Functions tulajdonosi fiókjának hozzáférési engedélyekre lenne szüksége ahhoz az Azure Cosmos DB-fiókhoz.

Csatlakozás az Azure Key Vaulthoz általános kapcsolat használatával

Az általános kapcsolatok támogatják az Azure Key Vaulttal való csatlakozást az KeyVault megjelenítési típusnak megfelelően. Ez a kapcsolattípus megköveteli, hogy a Háló felhasználói adatfüggvények tulajdonosa rendelkezik engedélyekkel az Azure Key Vaulthoz való csatlakozáshoz. Ezzel a kapcsolattal név szerint lekérheti a kulcsokat, titkos kulcsokat vagy tanúsítványokat.

Az Alábbi lépések végrehajtásával csatlakozhat az Azure Key Vaulthoz , hogy lekérjen egy ügyfélkulcsot egy API általános kapcsolat használatával történő meghívásához:

A Fabric User Data Functions elemben telepítse a requests és a azure-keyvault-secrets könyvtárakat a Könyvtárkezelés felületen használatával.
Nyissa meg az Azure Key Vault-erőforrást , és kérje le a Vault URI kulcs, titkos kulcs vagy tanúsítvány nevét.

Térjen vissza a Fabric User Data Functions elemhez , és használja ezt a mintát. Ebben a mintában lekérünk egy titkos kulcsot az Azure Key Vaultból egy nyilvános API-hoz való csatlakozáshoz. Cserélje le a következő változók értékét:

KEY_VAULT_URL az előző lépésben lekért Vault URI-vel.
KEY_VAULT_SECRET_NAME titkod nevével.
API_URL változót annak az API-nak az URL-címével, amelyhez csatlakozni szeretne. Ez a minta feltételezi, hogy olyan nyilvános API-hoz csatlakozik, amely fogadja a GET kéréseket, és a következő paramétereket api-key és 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}"

A függvény teszteléséhez vagy futtatásához adjon meg egy kéréstörzset a kódban.

A meghívási tulajdonságok lekérése `UserDataFunctionContext`

A programozási modell tartalmazza a UserDataFunctionContext objektumot is. Ez az objektum tartalmazza a függvényhívás metaadatait, és adott alkalmazáslogika létrehozásához használható bizonyos meghívási mechanizmusokhoz.

Az alábbi táblázat a UserDataFunctionContext objektum tulajdonságait mutatja be:

Tulajdonság neve	Adattípus	Leírás
Meghívás azonosítója	karakterlánc	A felhasználói adatfüggvényelem meghívásához kapcsolódó egyedi GUID.
VégrehajtóFelhasználó	objektum	A meghívás engedélyezéséhez használt felhasználói adatok metaadatai.

A ExecutingUser objektum a következő információkat tartalmazza:

Tulajdonság neve	Adattípus	Leírás
Oid	karakterlánc (GUID)	A felhasználó objektumazonosítója, amely a kérelmező nem módosítható azonosítója. Ez annak a felhasználónak vagy szolgáltatásnévnek az igazolt identitása, amelyet a függvény alkalmazások közötti meghívásához használnak.
BérlőAzonosító	karakterlánc (GUID)	Annak a bérlőnek az azonosítója, amelybe a felhasználó bejelentkezett.
PreferáltFelhasználónév	karakterlánc	Az invokáló felhasználó előnyben részesített felhasználóneve, a felhasználó által megadott módon. Ez az érték nem módosítható.

A UserDataFunctionContext paraméter eléréséhez a függvénydefiníció tetején található alábbi dekorátort kell használnia: @udf.context(argName="<parameter name>")

példa

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

Dobjon egy kezelt hibát a `UserThrownError` használatával

A függvény fejlesztésekor a Python programozási modellben elérhető UserThrownError metódussal várható hibaválaszt adhat meg. Ennek a módszernek az egyik módja az olyan esetek kezelése, amikor a felhasználó által megadott bemenetek nem adták át az üzleti érvényesítési szabályokat.

példa

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

Ez a UserThrownError metódus két paramétert használ:

Message: Ezt a sztringet a függvényt invesztő alkalmazás hibaüzeneteként adja vissza.
A függvényt megszólító alkalmazás visszaadja a tulajdonságok szótárát.

Változók lekérése Fabric-változótárakból

A Microsoft Fabric hálóváltozótára egy központosított adattár, amely a munkaterület különböző elemei között használható változók kezelésére szolgál. Lehetővé teszi a fejlesztők számára az elemkonfigurációk hatékony testreszabását és megosztását.

Adjon hozzá kapcsolatot egy változótárhoz a Kapcsolatok kezelése funkcióval, és kérje le a változótárelem aliasát .
Adjon hozzá egy kapcsolati dekorátort a @udf.connection(argName="varLib", alias="<My Variable Library Alias>") változótárelem aliasára való hivatkozáshoz.
A függvénydefinícióban adjon meg egy típussal rendelkező argumentumot fn.FabricVariablesClient. Ez az ügyfél olyan metódusokat biztosít, amelyekre szükség van a változók kódtárelemével való munkához. Például: def standardize_date(rawDate: str, varLib: fn.FabricVariablesClient) -> str:
Metódus használatával getVariables() lekérheti az összes változót a változótárból.

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

1 A változók értékeinek olvasásához használja ["variable-name"].get("variable-name")vagy .

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

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2025-11-10