Introducción al modelo de programación de funciones de datos de usuario de Fabric

El modelo de programación de funciones de datos de usuario de Fabric es un SDK que proporciona la funcionalidad necesaria para crear y publicar funciones ejecutables en Fabric. El SDK también le permitirá integrarse sin problemas con otros elementos del ecosistema de Fabric, como orígenes de datos de Fabric. Esta biblioteca está disponible públicamente en PyPI y se encuentra preinstalada en los elementos de funciones de datos de usuario.

SDK de funciones de datos de usuario

Un elemento de funciones de datos de usuario contiene una o varias funciones que se invocan desde el portal de Fabric, desde otro elemento de Fabric o desde una aplicación externa mediante el punto de conexión de REST proporcionado. Cada función es un método en el script de Python que permite pasar parámetros y devolver una salida al invocador. El modelo de programación de funciones de datos de usuario contiene los siguientes componentes:

La biblioteca fabric.functions proporciona el código necesario para crear funciones de datos de usuario en Python. Verá que esta biblioteca se importa en la primera plantilla de funciones al crear un nuevo elemento de funciones de datos de usuario.
El método fn.UserDataFunctions() proporciona el contexto de ejecución que se encuentra al principio del archivo de código en todos los nuevos elementos de funciones de datos de usuario, antes de cualquier definición de función.

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

udf = fn.UserDataFunctions()
```
Cada función se identifica con un decorador @udf.function(). Este decorador define si la función se puede invocar individualmente desde el portal o un invocador externo. El uso de este decorador también requiere que la función tenga un valor devuelto. Las funciones con este decorador pueden acceder a los objetos de conexión indicados por el @udf.connection decorador.

Ejemplo de función invocable
```
# 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()}!"
```
Los métodos de Python sin el decorador @udf.function() no se pueden invocar directamente. Solo se pueden invocar desde funciones que contengan el decorador y se pueden usar como funciones auxiliares.

Ejemplo de función asistente
```
# 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()
```

Tipos de entrada admitidos

Es posible definir parámetros de entrada para la función, como tipos de datos primitivos como str, int, float, etc. Los tipos de datos de entrada admitidos son:

Tipo JSON	Tipo de datos de Python
Cuerda	Str
Cadena Fecha y hora	fecha y hora
Booleano	booleano
Números	entero, flotante
Matriz	list[], ejemplo list[int]
objeto	diccionario
objeto	DataFrame de Pandas
Objeto o matriz de objetos	Serie pandas

Nota:

Para usar tipos de dataframe y series de Pandas, seleccione Administración de bibliotecas en el portal de Fabric para la función de datos de usuario y actualice fabric-user-data-function la versión a 1.0.0.

Ejemplo de cuerpo de solicitud para los tipos de entrada admitidos:

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

Tipos de salida compatibles

Los tipos de datos de salida admitidos son:

Tipo de datos de Python
Str
fecha y hora
booleano
entero, flotante
list[data-type], por ejemplo list[int]
diccionario
Ninguno
Serie pandas
DataFrame de Pandas

Cómo escribir una función asincrónica

Agregue un decorador asincrónico con la definición de función en el código. Con una async función, puede mejorar la capacidad de respuesta y la eficacia de la aplicación mediante el control de varias tareas a la vez. Son ideales para administrar grandes volúmenes de operaciones dependientes de E/S. Esta función de ejemplo lee un archivo CSV desde un almacén de datos en lagos utilizando pandas. La función toma el nombre de archivo como parámetro de entrada.

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

Conexiones de datos a orígenes de datos de Fabric

Este módulo permite hacer referencia a las conexiones de datos sin necesidad de escribir cadenas de conexión en el código. La biblioteca fabric.functions proporciona dos maneras de controlar las conexiones de datos:

fabric.functions.FabricSqlConnection: permite trabajar con bases de datos SQL en Fabric, incluyendo los puntos de conexión de SQL Analytics y los almacenes de Fabric.
fabric.functions.FabricLakehouseClient: permite trabajar con almacenes de lago, con una manera de conectarse tanto a tablas de almacén de lago como a archivos de almacén de lago.

Para hacer referencia a una conexión a un origen de datos, es necesario usar el decorador @udf.connection. Aplíquelo en cualquiera de los siguientes formatos:

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

Los argumentos de @udf.connection son:

argName, el nombre de la variable que usa la conexión en la función.
alias, el alias de la conexión que agregó con el menú Administrar conexiones.
Si argName y alias tuvieran el mismo valor, use @udf.connection("<alias and argName for the data connection>").

Ejemplo

# 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

Conexiones genéricas para elementos de Fabric o recursos de Azure

Las conexiones genéricas permiten crear conexiones a elementos de Fabric o recursos de Azure mediante la identidad del propietario del elemento de User Data Functions. Esta función genera un token de identificación de Microsoft Entra con la identidad del propietario del elemento y un tipo de audiencia proporcionado. Este token se usa para autenticarse con elementos de Fabric o recursos de Azure que admiten ese tipo de audiencia. Este proceso le proporcionará una experiencia de programación similar al uso de objetos de conexiones administradas desde la característica Administrar conexiones , pero solo para el tipo de público proporcionado en la conexión.

Esta característica usa el @udf.generic_connection() decorador con los parámetros siguientes:

Parámetro	Descripción	Importancia
`argName`	Nombre de la variable que se pasa a la función. El usuario debe especificar esta variable en los argumentos de su función y usar el tipo de `fn.FabricItem` para ella.	Por ejemplo, si es `argName=CosmosDb`, la función debe contener este argumento. `cosmosDb: fn.FabricItem`
`audienceType`	Tipo de público para el que se crea la conexión. Este parámetro está asociado al tipo de elemento fabric o servicio de Azure y determina el cliente usado para la conexión.	Los valores permitidos para este parámetro son `CosmosDb` o `KeyVault`.

Conexión al contenedor de Cosmos DB de Fabric mediante una conexión genérica

Las conexiones genéricas admiten elementos nativos de Fabric Cosmos DB utilizando el tipo de audiencia CosmosDB. El SDK de Funciones de Datos de Usuario incluido proporciona un método auxiliar denominado get_cosmos_client que obtiene un cliente singleton de Cosmos DB para cada invocación.

Puede conectarse a un elemento de Fabric Cosmos DB mediante una conexión genérica siguiendo estos pasos:

En el elemento Funciones de datos de usuario de Fabric, instale la azure-cosmos biblioteca mediante la experiencia de administración de bibliotecas.
Vaya a la configuración del Fabric Cosmos DB elemento.
Recupere la dirección URL del punto de conexión de Fabric Cosmos DB.

Vaya al elemento Funciones de datos de usuario. Use el código de ejemplo siguiente para conectarse al contenedor de Fabric Cosmos DB y ejecutar una consulta de lectura mediante el conjunto de datos de ejemplo de Cosmos DB. Reemplace los valores de las variables siguientes:

COSMOS_DB_URI con tu punto de conexión de Fabric Cosmos DB.
DB_NAME con el nombre del elemento de 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)

Pruebe o ejecute esta función proporcionando un nombre de categoría, como Accessory en los parámetros de invocación.

Nota:

También puede usar estos pasos para conectarse a una base de datos de Azure Cosmos DB mediante la dirección URL de la cuenta y los nombres de base de datos. La cuenta de propietario de User Data Functions necesitaría permisos de acceso a esa cuenta de Azure Cosmos DB.

Conexión a Azure Key Vault mediante una conexión genérica

Las conexiones genéricas admiten la conexión a un Azure Key Vault mediante el tipo de audiencia KeyVault. Este tipo de conexión requiere que el propietario de Fabric User Data Functions tenga permisos para conectarse a Azure Key Vault. Puede usar esta conexión para recuperar claves, secretos o certificados por nombre.

Puede conectarse a Azure Key Vault para recuperar un secreto de cliente para llamar a una API mediante una conexión genérica siguiendo estos pasos:

En el elemento Funciones de datos de usuario de Fabric, instale las bibliotecas requests y azure-keyvault-secrets mediante la herramienta de administración de bibliotecas.
Vaya al recurso de Azure Key Vault y recupere el Vault URI, así como el nombre de su clave, secreto o certificado.

Vuelva al elemento Fabric User Data Functions y use este ejemplo. En este ejemplo, se recupera un secreto de Azure Key Vault para conectarse a una API pública. Reemplace el valor de las variables siguientes:

KEY_VAULT_URL con el Vault URI que recuperaste en el paso anterior.
KEY_VAULT_SECRET_NAME con el nombre de su secreto.
API_URL variable con la dirección URL de la API a la que desea conectarse. En este ejemplo se supone que se va a conectar a una API pública que acepta solicitudes GET y toma los siguientes parámetros api-key y 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}"

Pruebe o ejecute esta función proporcionando un cuerpo de solicitud en el código.

Obtención de propiedades de invocación mediante `UserDataFunctionContext`

El modelo de programación también incluye el objeto UserDataFunctionContext. Este objeto contiene los metadatos de invocación de funciones y se puede usar para crear una lógica de aplicación específica para determinados mecanismos de invocación.

En la tabla siguiente se muestran las propiedades del objeto UserDataFunctionContext:

Nombre de propiedad	Tipo de datos	Descripción
Id. de invocación	cuerda / cadena	GUID único asociado a la invocación del elemento de funciones de datos de usuario.
UsuarioEjecutor	objeto	Metadatos de la información del usuario utilizada para autorizar la invocación.

El objeto ExecutingUser contiene la siguiente información:

Nombre de propiedad	Tipo de datos	Descripción
OID	cadena (GUID)	Id. de objeto del usuario, que es un identificador inmutable para el solicitante. Esta es la identidad comprobada del usuario o la entidad de servicio que se usa para invocar esta función en todas las aplicaciones.
Id. de inquilino	cadena (GUID)	Id. del inquilino en el que el usuario inició sesión.
NombreDeUsuarioPreferido	cuerda / cadena	El nombre de usuario preferido del usuario que invoca, tal y como lo establece el usuario. Este valor es mutable.

Para acceder al parámetro UserDataFunctionContext, use el siguiente decorador en la parte superior de la definición de función: @udf.context(argName="<parameter name>")

Ejemplo

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

Iniciar un error controlado con `UserThrownError`

Al desarrollar la función, es posible producir una respuesta de error esperada con el método UserThrownError, disponible en el modelo de programación de Python. Un uso de este método consiste en administrar casos en los que las entradas proporcionadas por el usuario no superen las reglas de validación empresarial.

Ejemplo

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

Este método UserThrownError toma dos parámetros:

Message: esta cadena se devuelve como mensaje de error a la aplicación que invoca esta función.
Se devuelve un diccionario de propiedades a la aplicación que invoca esta función.

Obtención de variables de las bibliotecas de Fabric

Una biblioteca de variables de Fabric en Microsoft Fabric es un repositorio centralizado para administrar variables que se pueden usar en distintos elementos dentro de un área de trabajo. Permite a los desarrolladores personalizar y compartir configuraciones de elementos de forma eficaz.

Agregue una conexión a una biblioteca de variables mediante Administrar conexiones y obtenga el alias del elemento de biblioteca de variables.
Agregue un decorador @udf.connection(argName="varLib", alias="<My Variable Library Alias>") de conexión para hacer referencia al alias del elemento de biblioteca de variables.
En la definición de función, incluya un argumento con el tipo fn.FabricVariablesClient. Este cliente proporciona métodos que necesita para trabajar con el elemento de biblioteca de variables. Por ejemplo: def standardize_date(rawDate: str, varLib: fn.FabricVariablesClient) -> str:
Utilice el método getVariables() para obtener todas las variables de la biblioteca de variables.

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

1 Para leer los valores de las variables, use ["variable-name"] o .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")

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2025-11-10