Visão geral do modelo de programação de funções de dados do usuário do Fabric

O modelo de programação de funções de dados do Usuário do Fabric define os padrões e conceitos para funções de criação no Fabric.

O fabric-user-data-functions SDK implementa esse modelo de programação, fornecendo a funcionalidade necessária para criar e publicar funções executáveis. O SDK também permite a integração perfeita com outros itens no ecossistema do Fabric, como fontes de dados do Fabric. Essa biblioteca está disponível publicamente no PyPI e é pré-instalada nos itens de funções de dados do usuário.

Este artigo explica como usar o SDK para criar funções que podem ser invocadas do portal do Fabric, de outros itens do Fabric ou de aplicativos externos usando a API REST. Você aprende o modelo de programação e os principais conceitos com exemplos práticos.

Dica

Para obter detalhes completos sobre todas as classes, métodos e parâmetros, consulte a documentação de referência do SDK.

Introdução ao SDK

Esta seção apresenta os principais componentes do SDK do User Data Functions e explica como estruturar suas funções. Você aprenderá sobre as importações, decoradores e os tipos de dados de entrada e saída necessários que suas funções podem lidar.

Funções de dados do usuário SDK

O fabric-user-data-functions SDK fornece os principais componentes necessários para criar funções de dados do usuário no Python.

Importações e inicialização necessárias

Cada arquivo de funções de dados do usuário deve importar o fabric.functions módulo e inicializar o contexto de execução:

import datetime
import fabric.functions as fn
import logging

udf = fn.UserDataFunctions()

O @udf.function() decorador

As funções marcadas com o @udf.function() decorador podem ser invocadas no portal do Fabric, em outro item do Fabric ou em um aplicativo externo. As funções com esse decorador devem especificar um tipo de retorno.

Exemplo:

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

Funções auxiliares

Métodos python sem o @udf.function() decorador não podem ser invocados diretamente. Eles só podem ser chamados a partir de funções decoradas e servem como funções auxiliares.

Exemplo:

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

Tipos de entrada com suporte

Você pode definir parâmetros de entrada para a função, como tipos de dados primitivos como str, int, float, etc. Os tipos de dados de entrada suportados são:

Tipo JSON	Tipo de dados do Python
Cadeia de caracteres	Str
Cadeia de caracteres de data e hora	datetime
Booleano	Bool
Números	int, float
Matriz	list[], exemplo list[int]
do objeto	dicionário
do objeto	DataFrame do pandas
Objeto ou matriz de objetos	Série pandas

Observação

Para usar os tipos Pandas DataFrame e Series, acesse o portal do Fabric, localize seu workspace e abra o item de funções de dados do usuário. Selecione o gerenciamento de biblioteca, pesquise o pacote e atualize-o fabric-user-data-functions para a versão 1.0.0 ou posterior.

Exemplo do corpo da solicitação para tipos de entrada com suporte:

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

Tipos de saída compatíveis

Os tipos de dados de saída suportados são:

Tipo de dados do Python
Str
datetime
Bool
int, float
list[data-type], por exemplo list[int]
dicionário
Nenhum
Série pandas
DataFrame do pandas

Escrita de funções

Requisitos e limitações de sintaxe

Ao escrever Funções de Dados do Usuário, você deve seguir regras de sintaxe específicas para garantir que suas funções funcionem corretamente.

Nomenclatura de parâmetro

Use camelCase: os nomes de parâmetro devem usar a convenção de nomenclatura camelCase e não podem conter sublinhados. Por exemplo, use productName ao invés de product_name.
Palavras-chave reservadas: você não pode usar palavras-chave reservadas do Python ou as seguintes palavras-chave específicas do Fabric como nomes de parâmetro ou nomes de função: req, contexte reqInvocationId.

Requisitos de parâmetro

Nenhum valor padrão: não há suporte para valores de parâmetro padrão. Todos os parâmetros são necessários ao invocar uma função. Por exemplo, a função a seguir gera um erro de sintaxe:
```
# The default value for the argument called 'name' is not supported and treated like a syntax error.
@udf.function()
def goodbye_fabric(name: str = "N/A") -> str:
    return f"Goodbye, {name}."
```
Anotações de tipo necessárias: todos os parâmetros devem incluir anotações de tipo (por exemplo, name: str).

Requisitos de função

Tipo de retorno necessário: as funções com o @udf.function() decorador devem especificar uma anotação de tipo de retorno (por exemplo, -> str).
Importações necessárias: a import fabric.functions as fn instrução e udf = fn.UserDataFunctions() a inicialização são necessárias para que suas funções funcionem.

Exemplo de sintaxe correta

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

Como escrever uma função assíncrona

Adicione o decorador assíncrono com sua definição de função em seu código. Com uma async função, você pode melhorar a capacidade de resposta e a eficiência do aplicativo manipulando várias tarefas ao mesmo tempo. Eles são ideais para gerenciar grandes volumes de operações associadas a E/S. Esta função de exemplo lê um arquivo CSV de um "lakehouse" usando pandas. A função usa o nome do arquivo como um 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}"

Trabalhando com dados

Conexões de dados com fontes de dados do Fabric

O SDK permite que você faça referência a conexões de dados sem a necessidade de gravar cadeias de conexão em seu código. A biblioteca fabric.functions fornece duas maneiras de manipular conexões de dados:

fabric.functions.FabricSqlConnection: Permite que você trabalhe com bancos de dados SQL no Fabric, incluindo endpoints do SQL Analytics e warehouses do Fabric.
fabric.functions.FabricLakehouseClient: Permite que você trabalhe com Lakehouses, com uma maneira de se conectar a tabelas e arquivos Lakehouse.

Para referenciar uma conexão a uma fonte de dados, você precisa usar o decorador @udf.connection. Você pode aplicá-lo em qualquer um dos seguintes formatos:

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

Os argumentos para @udf.connection são:

argName, o nome da variável que a conexão usa em sua função.
alias, o alias da conexão que você adicionou com o menu Gerenciar conexões.
Se argName e alias tiverem o mesmo valor, você pode usar @udf.connection("<alias and argName for the data connection>").

Exemplo

# 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

Conexões genéricas para itens do Fabric ou recursos do Azure

O SDK dá suporte a conexões genéricas que permitem criar conexões com itens do Fabric ou recursos do Azure usando sua identidade de proprietário do item do User Data Functions. Esse recurso gera um token de ID do Microsoft Entra com a identidade do proprietário do item e um tipo de público fornecido. Esse token é usado para autenticar com itens do Fabric ou recursos do Azure que dão suporte a esse tipo de audiência. Essa abordagem fornece uma experiência de programação semelhante ao uso de objetos de conexões gerenciadas do recurso Gerenciar Conexões , mas apenas para o tipo de público fornecido na conexão.

Esse recurso usa o @udf.generic_connection() decorador com os seguintes parâmetros:

Parâmetro	Descrição	Value
`argName`	O nome da variável que é passada para a função. O usuário precisa especificar essa variável nos argumentos de sua função e usar o tipo de `fn.FabricItem` para ela	Por exemplo, se `argName=CosmosDb`, a função deve conter esse argumento `cosmosDb: fn.FabricItem`.
`audienceType`	O tipo de público para o qual a conexão é criada. Esse parâmetro é associado ao tipo de item do Fabric ou ao serviço do Azure e determina o cliente usado para a conexão.	Os valores permitidos para esse parâmetro são `CosmosDb` ou `KeyVault`.

Conectar-se ao contêiner do Fabric Cosmos DB usando uma conexão genérica

As conexões genéricas dão suporte a itens nativos do Fabric Cosmos DB ao usar o CosmosDB tipo de público. O SDK de Funções de Dados do Usuário incluído fornece um método auxiliar chamado get_cosmos_client que busca um cliente singleton do Cosmos DB para cada invocação.

Você pode se conectar a um item do Fabric Cosmos DB usando uma conexão genérica seguindo estas etapas:

Vá para o portal do Fabric, localize seu workspace e abra o item de funções de dados do usuário. Selecione o gerenciamento de biblioteca, pesquise a biblioteca e instale-a azure-cosmos . Para obter mais informações, consulte Gerenciar bibliotecas.
Vá para as configurações do item do Fabric Cosmos DB.
Recupere a URL do ponto de extremidade do Fabric Cosmos DB.

Vá para o item Funções de Dados do Usuário. Use o código de exemplo a seguir para se conectar ao contêiner do Fabric Cosmos DB e executar uma consulta de leitura usando o conjunto de dados de exemplo do Cosmos DB. Substitua os valores das seguintes variáveis:

COSMOS_DB_URI com seu ponto de extremidade do Fabric Cosmos DB.
DB_NAME com o nome do item do 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)

Teste ou execute essa função fornecendo um nome de categoria, como Accessory nos parâmetros de invocação.

Observação

Você também pode usar essas etapas para se conectar a um banco de dados do Azure Cosmos DB usando a URL da conta e os nomes de banco de dados. A conta de proprietário do User Data Functions precisaria de permissões de acesso para essa conta do Azure Cosmos DB.

Conectar-se ao Azure Key Vault usando uma conexão genérica

Conexões genéricas suportam a conexão com um Azure Key Vault usando o KeyVault tipo de público. Esse tipo de conexão requer que o proprietário do Fabric User Data Functions tenha permissões para se conectar ao Azure Key Vault. Você pode usar essa conexão para recuperar chaves, segredos ou certificados por nome.

Você pode se conectar ao Azure Key Vault para recuperar um segredo do cliente para chamar uma API usando uma conexão genérica seguindo estas etapas:

Vá para o portal do Fabric, localize seu workspace e abra o item de funções de dados do usuário. Selecione Library management, depois pesquise e instale as bibliotecas requests e azure-keyvault-secrets. Para obter mais informações, consulte Gerenciar bibliotecas.
Acesse o recurso do Azure Key Vault no portal do Azure e recupere o Vault URI nome da chave, do segredo ou do certificado.

Volte para o item Funções de Dados do Usuário do Fabric e use este exemplo. Neste exemplo, recuperamos um segredo do Azure Key Vault para se conectar a uma API pública. Substitua o valor das seguintes variáveis:

KEY_VAULT_URL com o Vault URI que você recuperou na etapa anterior.
KEY_VAULT_SECRET_NAME com o nome do seu segredo.
API_URL variável com a URL da API à qual você gostaria de se conectar. Este exemplo pressupõe que você está se conectando a uma API pública que aceita solicitações GET e usa os seguintes parâmetros 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}"

Teste ou execute essa função fornecendo um corpo de solicitação em seu código.

Recursos avançados

O modelo de programação define padrões avançados que oferecem maior controle sobre suas funções. O SDK implementa esses padrões por meio de classes e métodos que permitem:

Acessar metadados de invocação sobre quem chamou sua função e como
Lidar com cenários de erro personalizados com respostas de erro estruturadas
Integrar com bibliotecas de variáveis do Fabric para o gerenciamento de configuração centralizado

Observação

O User Data Functions tem limites de serviço para tamanho da solicitação, tempo limite de execução e tamanho da resposta. Para obter detalhes sobre esses limites e como eles são impostos, consulte os detalhes e limitações do serviço.

Obtenha propriedades de invocação usando `UserDataFunctionContext`

O SDK inclui o UserDataFunctionContext objeto. Esse objeto contém os metadados de invocação de função e pode ser usado para criar uma lógica de aplicativo específica para diferentes mecanismos de invocação (como invocação de portal versus invocação da API REST).

A tabela a seguir mostra as propriedades do UserDataFunctionContext objeto:

Nome da propriedade	Tipo de Dados	Descrição
invocation_id	cadeia	O GUID exclusivo vinculado à invocação do item de funções de dados do usuário.
executing_user	objeto	Metadados das informações do usuário usados para autorizar a invocação.

O objeto executing_user contém as seguintes informações:

Nome da propriedade	Tipo de Dados	Descrição
Oid	cadeia de caracteres (GUID)	O ID do objeto do usuário, que é um i imutável Essa é a identidade verificada do usuário ou entidade de serviço usada para invocar essa função em todos os aplicativos.
Identificador do Inquilino	cadeia de caracteres (GUID)	O ID do locatário no qual o usuário está conectado.
NomeDeUsuárioPreferido	cadeia	O nome de usuário preferencial do usuário que faz a chamada, conforme definido pelo usuário. Esse valor é mutável.

Para acessar o parâmetro UserDataFunctionContext, você deve usar o seguinte decorador no topo da definição da função: @udf.context(argName="<parameter name>")

Exemplo

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

Lançar um erro tratado com `UserThrownError`

Ao desenvolver sua função, você pode gerar uma resposta de erro esperada usando a UserThrownError classe disponível no SDK. Um uso dessa classe é gerenciar casos em que as entradas fornecidas pelo usuário não passam regras de validação de negócios.

Exemplo

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

O UserThrownError construtor de classe usa dois parâmetros:

Message: essa cadeia de caracteres é retornada como a mensagem de erro para o aplicativo que está invocando essa função.
Um dicionário de propriedades é retornado ao aplicativo que está invocando essa função.

Obter variáveis de bibliotecas de variáveis do Fabric

Uma biblioteca de variáveis do Fabric no Microsoft Fabric é um repositório centralizado para gerenciar variáveis que podem ser usadas em diferentes itens em um workspace. Ele permite que os desenvolvedores personalizem e compartilhem configurações de itens com eficiência. Se você ainda não tiver uma biblioteca de variáveis, consulte Criar e gerenciar bibliotecas de variáveis.

Para usar uma biblioteca de variáveis em suas funções, adicione uma conexão a ela a partir do item de funções de dados do usuário. As bibliotecas de variáveis aparecem no catálogo do OneLake ao lado de fontes de dados como bancos de dados SQL e lakehouses.

Siga estas etapas para usar bibliotecas de variáveis em suas funções:

No item de funções de dados do usuário, adicione uma conexão à biblioteca de variáveis. No catálogo do OneLake, localize e selecione sua biblioteca de variáveis e selecione Conectar. Observe o Alias gerado pelo Fabric para a conexão.
Adicione um decorador de conexão ao item da biblioteca de variáveis. Por exemplo, @udf.connection(argName="varLib", alias="<My Variable Library Alias>") e substitua o alias para a conexão recém-adicionada para o item de biblioteca variável.
Na definição de função, inclua um argumento com o tipo fn.FabricVariablesClient. Esse cliente fornece métodos necessários para trabalhar com o item de biblioteca de variáveis.
Use getVariables() o método para obter todas as variáveis da biblioteca de variáveis.
Para ler os valores das variáveis, use ["variable-name"] ou .get("variable-name").

Exemplo

Neste exemplo, simulamos um cenário de configuração para um ambiente de produção e de desenvolvimento. Essa função define um caminho de armazenamento dependendo do ambiente selecionado usando um valor recuperado da Biblioteca de Variáveis. A Biblioteca de Variáveis contém uma variável chamada ENV onde os usuários podem definir um valor de dev ou 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"

Comentários

Esta página foi útil?

Last updated on 2026-01-22

Compartilhar via

Visão geral do modelo de programação de funções de dados do usuário do Fabric

Introdução ao SDK

Funções de dados do usuário SDK

Importações e inicialização necessárias

O @udf.function() decorador

Funções auxiliares

Tipos de entrada com suporte

Tipos de saída compatíveis

Escrita de funções

Requisitos e limitações de sintaxe

Nomenclatura de parâmetro

Requisitos de parâmetro

Requisitos de função

Exemplo de sintaxe correta

Como escrever uma função assíncrona

Trabalhando com dados

Conexões de dados com fontes de dados do Fabric

Exemplo

Conexões genéricas para itens do Fabric ou recursos do Azure

Conectar-se ao contêiner do Fabric Cosmos DB usando uma conexão genérica

Conectar-se ao Azure Key Vault usando uma conexão genérica

Recursos avançados

Obtenha propriedades de invocação usando UserDataFunctionContext

Lançar um erro tratado com UserThrownError

Obter variáveis de bibliotecas de variáveis do Fabric

Exemplo

Conteúdo relacionado

Comentários

Recursos adicionais

Obtenha propriedades de invocação usando `UserDataFunctionContext`

Lançar um erro tratado com `UserThrownError`