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

Model pro programování datových funkcí uživatelů Fabric je SDK, které poskytuje nezbytnou funkcionalitu pro vytváření a publikování spustitelných funkcí ve Fabricu. 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í.

Sada SDK pro funkce uživatelských dat

Položka funkcí uživatelských dat obsahuje jednu nebo více funkcí, které můžete vyvolat z portálu Fabric, z jiné položky infrastruktury nebo z externí aplikace pomocí poskytnutého koncového bodu REST. Každá funkce je metoda ve skriptu Pythonu, která umožňuje předávat parametry a vracet výstup do invokeru. Programovací model uživatelských datových funkcí obsahuje následující komponenty:

Knihovna fabric.functions poskytuje kód, který potřebujete k vytváření funkcí pro práci s uživatelskými daty v Pythonu. Tuto knihovnu můžete vidět importovanou v první šabloně funkce, když vytvoříte novou položku uživatelské datové funkce.
Metoda fn.UserDataFunctions() poskytuje kontext spuštění nalezený na začátku souboru kódu ve všech nových položkách funkcí uživatelských dat před všemi definicemi funkce.

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

udf = fn.UserDataFunctions()
```
Každá funkce je identifikována pomocí dekorátoru @udf.function(). Tento dekorátor definuje, zda lze funkci vyvolat jednotlivě z portálu nebo externím vyvolávačem. Použití tohoto dekorátoru také vyžaduje, aby funkce měla návratovou hodnotu. Funkce s tímto dekorátorem mají přístup k objektům připojení označeným dekorátorem @udf.connection .

Příklad vyvolatelné funkce
```
# 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()}!"
```

Jakékoli metody Pythonu bez dekorátoru @udf.function() nelze vyvolat přímo. Lze je vyvolat pouze z funkcí, které obsahují dekorátor, a lze je použít jako pomocné funkce.

Příklad pomocné funkce

# 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é 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ámce pandas a typy řad, vyberte na portálu Fabric správu knihovny a aktualizujte fabric-user-data-function verzi na verzi 1.0.0.

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

{
  "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é 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

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

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

Tento modul vám umožní odkazovat na datová připojení, aniž by bylo nutné psát připojovací řetězce ve vašem 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:
  # 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

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

Obecná připojení 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 proces vám poskytne 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:

V položce Funkce uživatelských dat nainstalujte knihovnu azure-cosmos pomocí prostředí Správa knihovny.
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í:

V položce Funkce uživatelských dat Fabric nainstalujte requests a azure-keyvault-secrets knihovny pomocí rozhraní Správa knihoven.
Přejděte k prostředku služby Azure Key Vault a načtěte Vault URI, jakož i název svého klíče, tajemství 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.

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

Programovací model také zahrnuje objekt UserDataFunctionContext. Tento objekt obsahuje metadata volání funkce a lze ji použít k vytvoření konkrétní logiky aplikace pro určité mechanismy vyvolání.

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

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

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

Vyvolejte ošetřenou chybu s `UserThrownError`

Při vývoji funkce můžete vyvolat očekávanou chybovou odpověď pomocí UserThrownError metody dostupné v programovacím modelu Pythonu. Jedním z použití této metody je řešení případů, kdy vstupy poskytnuté uživatelem neprojdou pravidly obchodní validace.

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

Tato UserThrownError metoda bere 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žít v různých položkách v rámci pracovního prostoru. Umožňuje vývojářům efektivně přizpůsobovat a sdílet konfigurace položek.

Přidejte připojení k knihovně proměnných pomocí Spravovat připojení a získejte alias pro položku knihovny proměnných.
Přidejte dekorátor připojení, @udf.connection(argName="varLib", alias="<My Variable Library Alias>") který odkazuje na alias položky 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. Například def standardize_date(rawDate: str, varLib: fn.FabricVariablesClient) -> str:
Pomocí metody získejte getVariables() všechny proměnné z knihovny proměnných.

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

1 Chcete-li číst hodnoty proměnných, buď ["variable-name"] nebo .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")

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 2025-11-10