Megjegyzés
Az oldalhoz való hozzáféréshez engedély szükséges. Megpróbálhat bejelentkezni vagy módosítani a címtárat.
Az oldalhoz való hozzáféréshez engedély szükséges. Megpróbálhatja módosítani a címtárat.
A Hálófelhasználó adatfüggvények programozási modellje határozza meg a fabrici függvények készítésének mintáit és fogalmait.
Az fabric-user-data-functions SDK implementálja ezt a programozási modellt, amely biztosítja a futtatható függvények létrehozásához és közzétételéhez szükséges funkciókat. Az SDK-val zökkenőmentesen integrálható a Fabric-ökoszisztéma más elemeivel, például a Fabric-adatforrásokkal.
A kódtár nyilvánosan elérhető a PyPI-ban és előre telepítve van a felhasználói adatfüggvények elemeiben.
Ez a cikk bemutatja, hogyan hozhat létre olyan függvényeket az SDK használatával, amelyek meghívhatók a Fabric portálról, más Fabric-elemekből vagy külső alkalmazásokból a REST API használatával. Gyakorlati példákkal megismerheti a programozási modellt és a fő fogalmakat.
Jótanács
Az összes osztályra, metódusra és paraméterre vonatkozó részletes információkért tekintse meg az SDK referenciadokumentációját.
Az SDK-val való kezdés
Ez a szakasz bemutatja a User Data Functions SDK alapvető összetevőit, és ismerteti a függvények strukturálását. Megismerheti a szükséges importokat, dekorátorokat, valamint a függvények által kezelhető bemeneti és kimeneti adatok típusait.
Felhasználói adatkezelő SDK
Az fabric-user-data-functions SDK biztosítja a felhasználói adatfüggvények Pythonban való létrehozásához szükséges alapvető összetevőket.
Szükséges importálás és inicializálás
Minden felhasználói adatfüggvényfájlnak importálnia kell a modult fabric.functions , és inicializálnia kell a végrehajtási környezetet:
import datetime
import fabric.functions as fn
import logging
udf = fn.UserDataFunctions()
A @udf.function() dekoratőr
A dekoratőrrel @udf.function() megjelölt függvények meghívhatók a Háló portálról, egy másik Hálóelemből vagy egy külső alkalmazásból. Az ezzel a dekoratőrrel rendelkező függvénynek meg kell adnia egy visszatérési típust.
példa:
@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()}!"
Segítő függvények
A @udf.function() dekoratőr nélküli Python-metódusok nem hívhatók meg közvetlenül. Csak díszített függvényekből hívhatók, és segédfunkciókként szolgálnak.
példa:
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 sorozat (Series) |
Megjegyzés:
A pandas DataFrame és series típusok használatához nyissa meg a Fabric portált, keresse meg a munkaterületet, és nyissa meg a felhasználói adatfüggvény-elemet. Válassza az Erőforrástár kezelése lehetőséget, keresse meg a fabric-user-data-functions csomagot, és frissítse az 1.0.0-s vagy újabb verzióra.
Példa a támogatott bemeneti típusok kérelemtörzsére:
{
"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}
]
}
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 sorozat (Series) |
| pandas DataFrame |
Függvények írása
Szintaktikai követelmények és korlátozások
A Felhasználói adatfüggvények írásakor meghatározott szintaxisi szabályokat kell követnie, hogy a függvények megfelelően működjenek.
Paraméter elnevezése
-
A camelCase használata: A paraméterneveknek camelCase elnevezési konvenciót kell használniuk, és nem tartalmazhatnak aláhúzásjeleket. Használjon például
productNameproduct_namehelyett. -
Fenntartott kulcsszavak: Nem használhat fenntartott Python-kulcsszavakat vagy a következő Fabric-specifikus kulcsszavakat paraméternévként vagy függvénynévként:
req,contextésreqInvocationId.
Paraméterkövetelmények
-
Szükség van típusjegyzetekre: Minden paraméternek tartalmaznia kell a típusjegyzeteket (például
name: str). -
Alapértelmezett értékek: Az alapértelmezett paraméterértékek támogatottak. A Fabric felhasználói adatfüggvényeiben megadhat alapértelmezett argumentumokat, hogy a kód könnyebben meghívható és karbantartható legyen. Az alapértelmezett értékek támogatják a JSON-szerializálható típusokat, beleértve a sztringeket, logikai értékeket, számokat (int, float), tömböket (listákat) és objektumokat (szótárakat).
Syntax
Vegye figyelembe, hogy az alapértelmezett értéknek JSON szerializálhatónak kell lennie. Például a beágyazott listák, például az [1, 2, [3]] engedélyezettek, míg a beágyazott készletek vagy a halmazok nem támogatottak. A lista vagy szótár alapértelmezett értékeinek beállításához használja a None értéket a függvény szignatúrájában, és rendelje hozzá a tényleges alapértelmezett értéket a függvényen belül.@udf.function() def function_name(param1: type = value1, param2: type = value2, listparam: list | None = None, ...) -> output_type: # function body
Függvénykövetelmények
-
Visszatérési típus megadása kötelező: A
@udf.function()dekoratőrrel rendelkező függvényeknek meg kell adniuk a visszatérési típus megjegyzését (például-> str). -
Szükséges importálás: A
import fabric.functions as fnfüggvények működéséhez az utasítás ésudf = fn.UserDataFunctions()az inicializálás szükséges.
Példa a helyes szintaxisra
@udf.function()
def process_order(orderNumber: int, customerName: str, orderDate: str) -> dict:
return {
"order_id": orderNumber,
"customer": customerName,
"date": orderDate,
"status": "processed"
}
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}"
Adatok használata
Adatkapcsolatok Fabric-adatforrásokkal
Az SDK lehetővé teszi az adatkapcsolatok hivatkozását 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ésaliasugyanaz 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:
# 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
Általános kapcsolatok Fabric elemek vagy Azure-erőforrások esetén
Az SDK olyan általános kapcsolatokat támogat, amelyek lehetővé teszik a Fabric-elemekhez vagy Azure erőforrásokhoz való kapcsolódást a User Data Functions elem tulajdonosi identitásával. Ez a funkció létrehoz egy Microsoft Entra ID jogkivonatot az elem tulajdonosának identitásával és egy megadott célközönségtípussal. Ez a jogkivonat a Fabric elemekkel vagy olyan Azure-erőforrásokkal való hitelesítésre szolgál, amelyek támogatják ezt a célközönségtípust. Ez a megközelítés 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 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:
Nyissa meg a Fabric portált, keresse meg a munkaterületét, és nyissa meg a felhasználói adatfüggvény elemet. Válassza a Library management lehetőséget, keresse meg a
azure-cosmoskönyvtárat, és telepítse. További információ: Kódtárak kezelése.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_URIa Fabric Cosmos DB-végponttal. -
DB_NAMEa(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
Accessorya meghívási paraméterekben.
Megjegyzés:
Ezekkel a lépésekkel Azure Cosmos DB-adatbázishoz is csatlakozhat a fiók URL-címével és adatbázisneveivel. A User Data Functions tulajdonosi fiókjának access engedélyre lenne szüksége ahhoz a Azure Cosmos DB-fiókhoz.
Csatlakozás Azure Key Vault általános kapcsolat használatával
Az általános kapcsolatok az KeyVault audienciatípus használatával támogatják az Azure Key Vaulthoz való csatlakozást. Ehhez a kapcsolattípushoz a Háló felhasználói adatfüggvények tulajdonosának engedélyekkel kell rendelkeznie a Azure Key Vault 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 a Azure Key Vault-hez, hogy lekérjen egy ügyfélkulcsot egy API általános kapcsolat használatával történő meghívásához:
Nyissa meg a Fabric portált, keresse meg a munkaterületét, és nyissa meg a felhasználói adatfüggvény elemet. Válassza a Library management lehetőséget, majd keresse meg és telepítse a
requestsésazure-keyvault-secretskódtárakat. További információ: Kódtárak kezelése.Lépjen az Azure Key Vault erőforrásra az Azure portálon, és kérje le a
Vault URIértéket, valamint a kulcs, jelszó vagy tanúsítvány nevét.Menjen vissza a Fabric User Data Functions elemhez, és használja fel ezt a mintát. Ebben a mintában lekérünk egy titkos kulcsot Azure Key Vault egy nyilvános API-hoz való csatlakozáshoz. Cserélje le a következő változók értékét:
-
KEY_VAULT_URLaz előző lépésben lekértVault URI-vel. -
KEY_VAULT_SECRET_NAMEtitkod nevével. -
API_URLvá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étereketapi-keyésrequest-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.
Speciális funkciók
A programozási modell speciális mintákat határoz meg, amelyek nagyobb ellenőrzést biztosítanak a függvények felett. Az SDK ezeket a mintákat osztályokkal és metódusokkal valósítja meg, amelyek lehetővé teszik, hogy:
- Tekintse meg a hívási metaadatokat arról, hogy ki hívta meg a függvényt, és hogyan.
- Egyéni hibaforgatókönyvek kezelése strukturált hibaválaszokkal
- Integrálás Fabric változókódtárakkal központosított konfigurációkezeléshez
Megjegyzés:
A User Data Functions szolgáltatáskorlátokkal rendelkezik a kérések méretére, a végrehajtási időtúllépésre és a válaszméretre vonatkozóan. A korlátozásokról és azok kikényszerítésének módjáról a Szolgáltatás részletei és korlátozásai című témakörben tájékozódhat.
A meghívási tulajdonságok lekérése UserDataFunctionContext
Az SDK tartalmazza az UserDataFunctionContext objektumot. Ez az objektum tartalmazza a függvényhívás metaadatait, és a különböző meghívási mechanizmusokhoz (például a portálhíváshoz és a REST API-híváshoz) használható alkalmazáslogika létrehozásához.
Az alábbi táblázat a UserDataFunctionContext objektum tulajdonságait mutatja be:
| Tulajdonság neve | Adattípus | Leírás |
|---|---|---|
| invocation_id | 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 executing_user 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 access 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 = {myContext.executing_user['Oid']}, TenantId = {myContext.executing_user['TenantId']}, PreferredUsername = {myContext.executing_user['PreferredUsername']}, InvocationId = {myContext.invocation_id}"
Dobjon egy kezelt hibát a UserThrownError használatával
A függvény fejlesztésekor a várt hibaválaszt az UserThrownError SDK-ban elérhető osztály használatával adhatja meg. Az osztály egyik használata 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()}!"
Az UserThrownError osztálykonstruktor két paramétert vesz igénybe:
-
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 afabric változótár egy központosított adattár, amely a munkaterület különböző elemei között használható változókat kezeli. Lehetővé teszi a fejlesztők számára az elemkonfigurációk hatékony testreszabását és megosztását. Ha még nem rendelkezik változótárval, tekintse meg a változótárak létrehozását és kezelését.
Ha változótárat szeretne használni a függvényekben, a felhasználói adatfüggvények eleméből hozzá kell adnia egy kapcsolatot. A változó kódtárak a OneLake katalógusban az olyan adatforrások mellett jelennek meg, mint az SQL-adatbázisok és a lakehouse-ok.
A változókódtárak függvényekben való használatához kövesse az alábbi lépéseket:
- A felhasználói adatfüggvények elemében adjon hozzá egy kapcsolatot a változótárhoz. A OneLake katalógusban keresse meg és válassza ki a változótárat, majd válassza a Csatlakozás lehetőséget. Vegye figyelembe a Fabric által a kapcsolathoz létrehozott aliast.
- Adjon hozzá egy kapcsolati dekorátort a változótárelemhez. Például
@udf.connection(argName="varLib", alias="<My Variable Library Alias>")cserélje le az aliast a változótárelem újonnan hozzáadott kapcsolatára. - 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. - Metódus használatával
getVariables()lekérheti az összes változót a változótárból. - A változók értékeinek olvasásához használja vagy
["variable-name"], vagy.get("variable-name").
Példa
Ebben a példában szimulálunk egy konfigurációs forgatókönyvet a termelési és a fejlesztési környezet számára. Ez a függvény egy storage elérési utat állít be a kiválasztott környezettől függően a változótárból lekért érték használatával. A változótár tartalmaz egy változót, amelynek az a neve, ENV hogy a felhasználók beállíthatnak egy értéket dev vagy 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"