Panoramica del modello di programmazione delle funzioni dati utente di Fabric

Il modello di programmazione delle funzioni dati utente di Fabric è un SDK che fornisce le funzionalità necessarie per creare e pubblicare funzioni eseguibili in Fabric. 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.

SDK per le funzioni dei dati utente

Un elemento delle funzioni dati utente contiene una o più funzioni che è possibile richiamare dal portale di Fabric, da un altro elemento di Fabric o da un'applicazione esterna usando l'endpoint REST fornito. Ogni funzione è un metodo nello script Python che consente di passare parametri e restituire un output al invoker. Il modello di programmazione Funzioni dati utente contiene i componenti seguenti:

La fabric.functions libreria fornisce il codice necessario per creare funzioni dati utente in Python. Questa libreria viene importata nel primo modello di funzione quando si crea un nuovo elemento di funzioni dati utente.
Il metodo fn.UserDataFunctions() fornisce il contesto di esecuzione trovato all'inizio del file di codice in tutti i nuovi elementi delle funzioni dati utente, prima di qualsiasi definizione di funzione.

Esempio:
```
import datetime
import fabric.functions as fn
import logging

udf = fn.UserDataFunctions()
```
Ogni funzione viene identificata con un @udf.function() decoratore. Questo decoratore definisce se la tua funzione può essere richiamata singolarmente dal portale o da un richiamatore esterno. L'uso di questo decorator richiede anche che la funzione abbia un valore di ritorno. Le funzioni con questo decoratore possono accedere agli oggetti di connessione indicati dal decoratore @udf.connection.

Esempio di funzione richiamabile
```
# 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()}!"
```
Tutti i metodi Python senza decorator @udf.function() non possono essere richiamati direttamente. Possono essere richiamati solo da funzioni che contengono il decoratore e possono essere usati come funzioni helper.

Esempio di funzione 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()
```

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	int, float
Array	lista[], esempio di lista[int]
oggetto	dizionario
oggetto	pandas DataFrame
Oggetto o matrice di oggetti	Serie pandas

Annotazioni

Per utilizzare i tipi DataFrame e Series di pandas, selezionare Gestione librerie nel portale Fabric per la funzione dati utente e aggiornare la versione a 1.0.0.

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

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

Tipi di output supportati

I tipi di dati di output supportati sono:

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

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

Connessioni dati a origini dati di Fabric

Questo modulo 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:
  # 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

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

Le connessioni generice consentono di creare connessioni agli elementi di Infrastruttura o alle risorse di Azure usando l'identità del proprietario dell'elemento di Funzioni dati utente. Questa funzionalità genera un token ID Microsoft Entra con l'identità del proprietario dell'elemento e un tipo di gruppo di destinatari specificato. Questo token viene usato per eseguire l'autenticazione con gli elementi di Fabric o le risorse di Azure che supportano il tipo di gruppo di destinatari. Questo processo offrirà 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 di Infrastruttura o al servizio di Azure e determina il client usato per la connessione.	I valori consentiti per questo parametro sono `CosmosDb` o `KeyVault`.

Connettersi al contenitore Cosmos DB di Fabric usando una connessione generica

Le connessioni generiche supportano elementi nativi di Cosmos DB di Fabric usando il CosmosDB tipo di gruppo di destinatari. L'SDK delle Funzioni per i dati utente incluso offre un metodo di supporto denominato get_cosmos_client che recupera un cliente singolo di Cosmos DB per ogni chiamata.

È possibile connettersi a un elemento di Fabric Cosmos DB usando una connessione generica attenendosi alla procedura seguente:

Nell'elemento Funzioni dati utente di Fabric installare la azure-cosmos libreria usando l'esperienza di gestione delle librerie.
Vai alle impostazioni del Elemento di Fabric Cosmos DB.
Recupera l'URL dell'endpoint di Cosmos DB di Fabric.

Passare all'elemento Funzioni dati utente. Usare il codice di esempio seguente per connettersi al contenitore Cosmos DB di Fabric ed eseguire una query di lettura usando il set di dati di esempio di Cosmos DB. Sostituire i valori delle variabili seguenti:

COSMOS_DB_URI con l'endpoint di Fabric Cosmos DB.
DB_NAME con il nome dell'elemento di Cosmos DB di Fabric.

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)

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 dell'utente avrebbe bisogno di autorizzazioni di accesso per l'account Azure Cosmos DB.

Connettersi ad Azure Key Vault usando una connessione generica

Le connessioni generiche supportano la connessione a un Azure Key Vault utilizzando il tipo di pubblico KeyVault. Questo tipo di connessione richiede che il proprietario di Funzioni dati utente di Fabric disponga delle autorizzazioni per connettersi ad Azure Key Vault. È possibile usare questa connessione per recuperare chiavi, segreti o certificati in base al nome.

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

Nell'elemento Funzioni dati utente di Fabric, installare le requests e le azure-keyvault-secrets librerie usando l'esperienza di gestione delle librerie.
Passare alla risorsa di Azure Key Vault e recuperare il Vault URI e il nome della chiave, del segreto o del certificato.

Tornare all'elemento Funzioni dati utente di Fabric e usare questo esempio. In questo esempio viene recuperato un segreto da Azure Key Vault per connettersi 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}"

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

Ottenere le proprietà di invocazione utilizzando `UserDataFunctionContext`

Il modello di programmazione include anche l'oggetto UserDataFunctionContext . Questo oggetto contiene i metadati di chiamata della funzione e può essere usato per creare una logica dell'app specifica per determinati meccanismi di chiamata.

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

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

L'oggetto ExecutingUser contiene le informazioni seguenti:

Nome della proprietà	Tipo di dati	Descrizione
Oid	string (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	string (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 UserDataFunctionContext parametro, è necessario usare l'elemento Decorator seguente nella parte superiore della 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 = {context.executing_user['Oid']}, TenantId = {context.executing_user['TenantId']}, PreferredUsername = {context.executing_user['PreferredUsername']}, InvocationId = {context.invocation_id}"

Generare un errore gestito con `UserThrownError`

Quando si sviluppa la funzione, è possibile generare una risposta di errore prevista usando il UserThrownError metodo disponibile nel modello di programmazione Python. Un uso di questo metodo 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()}!"

Questo UserThrownError metodo 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 Fabric Variable Library in Microsoft Fabric è un repository centralizzato per la gestione delle variabili che possono essere usate tra elementi diversi all'interno di un'area di lavoro. Consente agli sviluppatori di personalizzare e condividere in modo efficiente le configurazioni degli elementi.

Aggiungere una connessione a una libreria di variabili usando Gestisci connessioni e ottenere l'alias per l'elemento della libreria di variabili.
Aggiungere un decoratore di connessione, @udf.connection(argName="varLib", alias="<My Variable Library Alias>"), per fare riferimento all'alias dell'elemento della libreria di variabili.
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. Ad esempio, def standardize_date(rawDate: str, varLib: fn.FabricVariablesClient) -> str:
Usare getVariables() il metodo per ottenere tutte le variabili dalla libreria di variabili.

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

1 Per leggere i valori delle variabili, usare sia ["variable-name"] sia .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")

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-11-10