Panoramica del modello di programmazione delle funzioni dei dati utente Fabric

Il modello di programmazione delle funzioni dati utente Fabric definisce i modelli e i concetti per autoria delle funzioni in Fabric.

L'SDK fabric-user-data-functions implementa questo modello di programmazione, fornendo le funzionalità necessarie per creare e pubblicare funzioni eseguibili. L'SDK consente anche di integrarsi facilmente con altri elementi nell'ecosistema Fabric, come le fonti di dati di Fabric. Questa libreria è disponibile pubblicamente in PyPI ed è preinstallata negli elementi delle funzioni dati utente.

Questo articolo illustra come usare l'SDK per creare funzioni che possono essere richiamate dal portale di Fabric, da altri elementi di Fabric o da applicazioni esterne usando l'API REST. Si apprenderà il modello di programmazione e i concetti chiave con esempi pratici.

Suggerimento

Per informazioni dettagliate su tutte le classi, i metodi e i parametri, vedere la documentazione di riferimento dell'SDK.

Introduzione all'SDK

Questa sezione introduce i componenti principali dell'SDK delle funzioni dati utente e spiega come strutturare le tue funzioni. Impari le informazioni sugli import, i decorator e i tipi di dati di input e output che le tue funzioni possono gestire.

SDK per le funzioni dei dati utente

L'SDK fabric-user-data-functions fornisce i componenti di base necessari per creare funzioni dati utente in Python.

Importazioni e inizializzazione richieste

Ogni file di funzioni dati utente deve importare il fabric.functions modulo e inizializzare il contesto di esecuzione:

import datetime
import fabric.functions as fn
import logging

udf = fn.UserDataFunctions()

Il decorator @udf.function()

Le funzioni contrassegnate con il decoratore @udf.function() possono essere richiamate dal portale di Fabric, da un altro elemento Fabric o da un'applicazione esterna. Le funzioni con questo decoratore devono specificare un tipo di ritorno.

Esempio:

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

Funzioni di supporto

I metodi Python senza @udf.function() decorator non possono essere richiamati direttamente. Possono essere chiamati solo da funzioni decorate e fungono da funzioni di supporto.

Esempio:

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

Tipi di input supportati

È possibile definire parametri di input per la funzione, ad esempio tipi di dati primitivi come str, int, float e così via. I tipi di dati di input supportati sono:

Tipo JSON Tipo di dati Python
Stringa Str
Stringa Datetime data e ora
Booleano Bool
Numeri inte, galleggia
Array lista[], esempio di lista[int]
oggetto dizionario
oggetto DataFrame pandas
Oggetto o matrice di oggetti Serie pandas

Annotazioni

Per usare i tipi DataFrame e Series di pandas, passare al portale di Fabric, trovare l'area di lavoro e aprire l'elemento delle funzioni dati dell'utente. Selezionare Gestione librerie, cercare il fabric-user-data-functions pacchetto e aggiornarlo alla versione 1.0.0 o successiva.

Esempio di corpo della richiesta per i tipi di input supportati:

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

Tipi di output supportati

I tipi di dati di output supportati sono:

Tipo di dati Python
Str
data e ora
Bool
inte, galleggia
list[data-type], ad esempio list[int]
dizionario
Nessuno
Serie pandas
DataFrame pandas

Scrittura di funzioni

Requisiti e limitazioni della sintassi

Quando scrivi funzioni sui dati utente, segui regole sinattiche specifiche per assicurarti che le tue funzioni funzionino correttamente.

Denominazione dei parametri

  • Usare camelCase: i nomi dei parametri devono usare la convenzione di denominazione camelCase e non possono contenere caratteri di sottolineatura. Ad esempio, usare productName anziché product_name.
  • Parole chiave riservate: non è possibile usare parole chiave Python riservate o le parole chiave specifiche dell'infrastruttura seguenti come nomi di parametri o nomi di funzione: req, contexte reqInvocationId.

Requisiti dei parametri

  • Annotazioni di tipo obbligatorie: tutti i parametri devono includere annotazioni di tipo (ad esempio, name: str).

  • Valori predefiniti: sono supportati i valori dei parametri predefiniti. È possibile definire gli argomenti predefiniti nelle funzioni dati utente di Fabric per semplificare la chiamata e la gestione del codice. I parametri con valori predefiniti sono facoltativi in fase di chiamata; sono necessari parametri senza valori predefiniti. I tipi seguenti sono supportati come valori predefiniti:

    Tipo predefinito Notes
    Stringa Qualsiasi stringa serializzabile JSON.
    Stringa Data e ora Specificare come stringa nella firma della funzione. Il runtime analizza la stringa in datetime al momento dell'invocazione. Usare il formato ISO 8601 (ad esempio , 2025-12-31T23:59:59Z) per l'analisi coerente e non ambigua.
    Booleano True o False.
    Integer Qualsiasi valore intero.
    Galleggiare Qualsiasi valore a virgola mobile.
    List Deve essere serializzabile in JSON. Preferisce None nella firma e assegnare il valore predefinito reale all'interno della funzione per evitare valori predefiniti modificabili condivisi.
    Dizionario Deve essere serializzabile in JSON. Preferisci None nella firma e assegna il valore predefinito reale all'interno della funzione.
    DataFrame pandas Fornito come oggetto JSON convertito dall'SDK in un tipo pandas. Richiede fabric-user-data-functions la versione 1.0.0 o successiva.
    Serie pandas Fornito come matrice JSON di oggetti che l'SDK converte in un tipo pandas. Richiede fabric-user-data-functions la versione 1.0.0 o successiva.

    Syntax

    @udf.function()
def function_name(
    requiredParam: str,
    optionalStr: str = "hello",
    optionalDate: datetime.datetime = "2025-01-01T00:00:00Z",  # specify as a string; the runtime parses it to datetime at invocation time
    optionalBool: bool = True,
    optionalInt: int = 10,
    optionalFloat: float = 1.5,
    optionalList: list | None = None,   # assign real default inside the function
    optionalDict: dict | None = None,   # assign real default inside the function
) -> dict:
    optionalList = optionalList or [1, 2, 3]
    optionalDict = optionalDict or {"key": "value"}
    return {"param": requiredParam}

    Le impostazioni predefinite devono essere serializzabili in JSON (i set e le tuple non sono supportati). Per le impostazioni predefinite per l'elenco o il dizionario, usare None nella firma e assegnare il valore predefinito reale all'interno della funzione per evitare valori predefiniti modificabili condivisi. Usare il formato ISO 8601 ,ad esempio 2025-12-31T23:59:59Z, per le impostazioni predefinite datetime. L'uso di pandas DataFrame o Series come impostazione predefinita richiede fabric-user-data-functions la versione 1.0.0 o successiva.

Requisiti della funzione

  • Tipo restituito obbligatorio: le funzioni con decorator @udf.function() devono specificare un'annotazione del tipo restituito , ad esempio -> str.
  • Importazioni obbligatorie: Le istruzioni import fabric.functions as fn e le inizializzazioni udf = fn.UserDataFunctions() sono necessarie affinché le tue funzioni funzionino.

Esempio di sintassi corretta

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

Come scrivere una funzione asincrona

Aggiungi il decoratore asincrono alla definizione della tua funzione nel codice. Con una async funzione è possibile migliorare la velocità di risposta e l'efficienza dell'applicazione gestendo più attività contemporaneamente. Sono ideali per la gestione di volumi elevati di operazioni associate a I/O. Questa funzione di esempio legge un file CSV da una lakehouse usando pandas. La funzione accetta il nome del file come parametro di input.

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

Uso dei dati

Connessioni dati a origini dati di Fabric

L'SDK consente di fare riferimento alle connessioni dati senza la necessità di scrivere stringhe di connessione nel codice. La fabric.functions libreria offre due modi per gestire le connessioni dati:

  • fabric.functions.FabricSqlConnection: Consente di usare i database SQL in Fabric, inclusi gli endpoint di Analisi SQL e i magazzini Fabric.
  • fabric.functions.FabricLakehouseClient: Consente di lavorare con Lakehouses, con un modo per connettersi sia alle tabelle Lakehouse che ai file Lakehouse.

Per fare riferimento a una connessione a un'origine dati, è necessario usare l'elemento @udf.connection decoratore. È possibile applicarlo in uno dei formati seguenti:

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

Gli argomenti per @udf.connection sono:

  • argName, il nome della variabile usata dalla connessione nella funzione.
  • alias, l'alias della connessione aggiunta con il menu Gestisci connessioni .
  • Se argName e alias hanno lo stesso valore, è possibile usare @udf.connection("<alias and argName for the data connection>").

Esempio

# 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

Connessioni generice per gli elementi dell'infrastruttura o le risorse di Azure

L'SDK supporta connessioni generiche che puoi usare per creare connessioni con elementi Fabric o risorse Azure utilizzando l'identità del proprietario dell'elemento delle funzioni dati dell'utente. Questa funzionalità genera un token Microsoft Entra ID con l'identità del proprietario dell'elemento e un tipo di gruppo di destinatari fornito. Usa questo token per autenticarti con gli elementi Fabric o le risorse Azure che supportano quel tipo di pubblico. Questo approccio offre un'esperienza di programmazione simile all'uso di oggetti connessioni gestite dalla funzionalità Gestisci connessioni , ma solo per il tipo di gruppo di destinatari specificato nella connessione.

Questa funzionalità usa il decoratore @udf.generic_connection() con i seguenti parametri:

Parametro Descrizione Value
argName Nome della variabile passata alla funzione. L'utente deve specificare questa variabile negli argomenti della funzione e usare il tipo di fn.FabricItem per esso Ad esempio, se argName=CosmosDb, allora la funzione deve contenere questo argomento cosmosDb: fn.FabricItem
audienceType Tipo di gruppo di destinatari per cui viene creata la connessione. Questo parametro è associato al tipo di elemento fabric o al servizio Azure e determina il client usato per la connessione. I valori consentiti per questo parametro sono CosmosDb o KeyVault.

Collegati a Cosmos DB nel container Fabric usando una connessione generica

Le connessioni generiche supportano database nativi Cosmos DB in Fabric utilizzando il tipo di CosmosDB pubblico. L'SDK delle funzioni dati utente incluso fornisce un metodo helper chiamato get_cosmos_client che recupera un client Cosmos DB singleton per ogni invocazione.

Puoi collegarti a un database Cosmos DB in Fabric usando una connessione generica seguendo questi passaggi:

  1. Vai al portale Fabric, trova l'area di lavoro e apri l'elemento delle funzioni dei dati utente. Selezionare Gestione libreria, cercare la libreria azure-cosmos e installarla. Per altre informazioni, vedere Gestire le librerie.

  2. Vai nella tua base di dati Cosmos nelle impostazioni oggetti Fabric.

    Screenshot che mostra il database Cosmos nella posizione dei tasti delle impostazioni di Fabric.

  3. Recupera il tuo database Cosmos nell'URL dell'endpoint Fabric.

    Screenshot che mostra il database Cosmos nell'URL dell'endpoint Fabric.

  4. Vai all'elemento delle funzioni dati utente. Usa il seguente codice di esempio per connetterti al tuo Cosmos DB nel contenitore Fabric ed esegui una query di lettura usando il dataset di esempio Cosmos DB. Sostituire i valori delle variabili seguenti:

    • COSMOS_DB_URIcon il tuo database Cosmos nell'endpoint Fabric.
    • DB_NAME con il nome dell'elemento del database Cosmos.
    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)

  5. Testare o eseguire questa funzione specificando un nome di categoria, ad esempio Accessory nei parametri di chiamata.

Annotazioni

È anche possibile usare questi passaggi per connettersi a un database di Azure Cosmos DB usando l'URL dell'account e i nomi di database. L'account proprietario delle funzioni dati utente necessita dei permessi di accesso a quell'account Azure Cosmos DB.

Connettersi a Azure Key Vault usando una connessione generica

Le connessioni generice supportano la connessione a un Azure Key Vault usando il tipo di gruppo di destinatari KeyVault. Questo tipo di connessione richiede che il proprietario delle funzioni dati utente Fabric abbia i permessi di connettersi a Azure Key Vault. È possibile usare questa connessione per recuperare chiavi, segreti o certificati in base al nome.

È possibile connettersi a Azure Key Vault per recuperare un segreto client per chiamare un'API usando una connessione generica seguendo questa procedura:

  1. Vai al portale Fabric, trova l'area di lavoro e apri l'elemento delle funzioni dei dati utente. Selezionare Gestione libreria, quindi cercare e installare le librerie requests e azure-keyvault-secrets. Per altre informazioni, vedere Gestire le librerie.

  2. Passare alla risorsa Azure Key Vault nel Azure portal e recuperare il Vault URI e il nome della chiave, del segreto o del certificato.

    Screenshot che mostra l'URL dell'endpoint Azure Key Vault e i valori.

  3. Torna al tuo elemento di funzioni dati utente Fabric e usa questo esempio. In questo esempio, recuperi un segreto da Azure Key Vault per collegarlo a un'API pubblica. Sostituire il valore delle variabili seguenti:

    • KEY_VAULT_URL con il Vault URI recuperato nel passaggio precedente.
    • KEY_VAULT_SECRET_NAME con il nome della chiave.
    • API_URL variabile con l'URL dell'API a cui ci si vuole connettere. Questo esempio presuppone che ci si connetta a un'API pubblica che accetta le richieste GET e prende i seguenti parametri api-key e 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}"

  4. Testare o eseguire questa funzione fornendo un corpo della richiesta nel codice.

Funzionalità avanzate

Il modello di programmazione definisce modelli avanzati che offrono maggiore controllo sulle funzioni. L'SDK implementa questi modelli tramite classi e metodi che consentono di:

  • Accedi ai metadati di invocazione per sapere chi e come ha chiamato la tua funzione
  • Gestire scenari di errore personalizzati con risposte di errore strutturate
  • Integrazione con librerie di variabili di Fabric per la gestione centralizzata della configurazione

Annotazioni

Le funzioni dati utente hanno limiti di servizio per la dimensione della richiesta, il timeout di esecuzione e la dimensione della risposta. Per informazioni dettagliate su questi limiti e su come vengono applicati, vedere Dettagli e limitazioni del servizio.

Ottenere le proprietà di invocazione utilizzando UserDataFunctionContext

L'SDK include l'oggetto UserDataFunctionContext . Questo oggetto contiene i metadati di chiamata della funzione e può essere usato per creare una logica dell'app specifica per meccanismi di chiamata diversi, ad esempio la chiamata al portale e la chiamata all'API REST.

La tabella seguente illustra le proprietà per l'oggetto UserDataFunctionContext :

Nome della proprietà Tipo di dati Descrizione
invocation_id corda GUID univoco associato alla chiamata dell'elemento delle funzioni dati utente.
utente_esecutore oggetto Metadati delle informazioni dell'utente usate per autorizzare la chiamata.

L'oggetto executing_user contiene le informazioni seguenti:

Nome della proprietà Tipo di dati Descrizione
Oid stringa (GUID) ID oggetto dell'utente, che è un identificatore non modificabile per il richiedente. Si tratta dell'identità verificata dell'utente o dell'entità servizio usata per richiamare questa funzione tra le applicazioni.
ID del Tenant stringa (GUID) ID del tenant a cui l'utente ha eseguito l'accesso.
Nome utente preferito corda Nome utente preferito dell'utente chiamante, impostato dall'utente. Questo valore è modificabile.

Per accedere al parametro UserDataFunctionContext, è necessario usare il decoratore seguente in cima alla definizione della funzione: @udf.context(argName="<parameter name>")

Esempio

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

Generare un errore gestito con UserThrownError

Quando si sviluppa la funzione, è possibile generare una risposta di errore prevista usando la UserThrownError classe disponibile nell'SDK. Un uso di questa classe consiste nella gestione dei casi in cui gli input forniti dall'utente non superano le regole di convalida business.

Esempio

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

Il UserThrownError costruttore della classe accetta due parametri:

  • Message: questa stringa viene restituita come messaggio di errore all'applicazione che richiama questa funzione.
  • Un dizionario di proprietà viene restituito all'applicazione che richiama questa funzione.

Ottenere variabili dalle librerie di variabili di Fabric

Una libreria di variabili in Fabric è un repository centralizzato per gestire variabili che puoi utilizzare tra diversi elementi all'interno di uno spazio di lavoro. Consente agli sviluppatori di personalizzare e condividere in modo efficiente le configurazioni degli elementi. Se non si ha ancora una libreria di variabili, vedere Creare e gestire librerie di variabili.

Per usare una libreria di variabili nelle tue funzioni, aggiungi una connessione ad essa dall'elemento delle funzioni dei tuoi dati utente. Le librerie di variabili vengono visualizzate nel catalogo di OneLake insieme a origini dati come database SQL e lakehouse.

Seguire questa procedura per usare le librerie di variabili nelle funzioni:

  1. Nell'elemento delle funzioni dati utente aggiungere una connessione alla libreria di variabili. Nel catalogo OneLake trovare e selezionare la libreria di variabili e quindi selezionare Connetti. Si noti l'alias generato da Fabric per la connessione.
  2. Aggiungere un decoratore di connessione per l'oggetto della libreria di variabili. Ad esempio, @udf.connection(argName="varLib", alias="<My Variable Library Alias>") e sostituire l'alias con la connessione appena aggiunta per l'elemento variabile della libreria.
  3. Nella definizione della funzione includere un argomento con tipo fn.FabricVariablesClient. Questo client fornisce i metodi necessari per lavorare con l'elemento della libreria di variabili.
  4. Usare getVariables() il metodo per ottenere tutte le variabili dalla libreria di variabili.
  5. Per leggere i valori delle variabili, usa ["variable-name"] o .get("variable-name").

Esempio

In questo esempio, si simula uno scenario di configurazione per un ambiente di produzione e uno di sviluppo. Questa funzione stabilisce un percorso di archiviazione a seconda dell'ambiente selezionato utilizzando un valore recuperato dalla libreria variabile. La libreria di variabili contiene una variabile chiamata ENV dove gli utenti possono impostare un valore di dev o 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"

Contenuti correlati

  • Last updated on