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 Fabric é um SDK que fornece a funcionalidade necessária para criar e publicar funções que podem ser executadas no Fabric. O SDK também permite que você se integre perfeitamente a outros itens no ecossistema do Fabric, como fontes de dados do Fabric. Esta biblioteca está disponível publicamente no PyPI e está pré-instalada nos itens de funções de dados do usuário.

SDK de funções de dados do usuário

Um item de funções de dados do usuário contém uma ou várias funções que você pode invocar do portal Fabric, de outro item Fabric ou de um aplicativo externo usando o ponto de extremidade REST fornecido. Cada função é um método em seu script Python que permite passar parâmetros e retornar uma saída para o invocador. O modelo de programação de funções de dados do usuário contém os seguintes componentes:

A biblioteca fabric.functions fornece o código necessário para criar funções de dados do usuário em Python. Você pode ver essa biblioteca sendo importada em seu primeiro modelo de função ao criar um novo item de funções de dados do usuário.
O método fn.UserDataFunctions() fornece o contexto de execução encontrado no início do arquivo de código em todos os novos itens de funções de dados do usuário, antes de quaisquer definições de função.

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

udf = fn.UserDataFunctions()
```
Cada função é identificada com o decorador @udf.function(). Este decorador define se a sua função pode ser invocada individualmente a partir do portal ou de um invocador externo. Usar este decorador também requer que a função tenha um valor de retorno. Funções com este decorador pode acessar os objetos de conexão indicados pelo @udf.connection decorador.

Exemplo de função invocável
```
# 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()}!"
```
Qualquer método Python sem o decorador @udf.function() não pode ser invocado diretamente. Eles só podem ser invocados a partir de funções que contêm o decorador, e podem ser usados como funções auxiliares.

Exemplo de função auxiliar
```
# 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 suportados

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	Python Tipo de dados
String	STR
Cadeia de caracteres de data e hora	datetime
Booleano	Bool
Números	int, flutuar
Matriz	lista[], exemplo lista[int]
Objeto	dicionário
Objeto	Pandas DataFrame
Objeto ou matriz de objetos	Série Pandas

Observação

Para usar os tipos pandas DataFrame e Series, selecione Gerenciamento de biblioteca no portal Fabric para sua função de dados do usuário e atualize fabric-user-data-function a versão para 1.0.0.

Exemplo de corpo de solicitação para tipos de entrada suportados:

{
  "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 saída suportados

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

Python Tipo de dados
STR
datetime
Bool
int, flutuar
lista[tipo-de-dados], por exemplo lista[int]
dicionário
Nenhum
Série Pandas
Pandas DataFrame

Como escrever uma função assíncrona

Adicione 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 seu aplicativo lidando com várias tarefas ao mesmo tempo. Eles são ideais para gerenciar grandes volumes de operações vinculadas a E/S. Esta função de exemplo lê um arquivo CSV de uma casa do lago usando pandas. 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}"

Conexões de dados para fontes de dados Fabric

Este módulo permite referir as conexões de dados sem necessidade de escrever strings de conexão no teu código. A biblioteca de fabric.functions fornece duas maneiras de lidar com conexões de dados:

fabric.functions.FabricSqlConnection: Permite trabalhar com bases de dados SQL no Fabric, incluindo endpoints de SQL Analytics e armazenamentos do Fabric.
fabric.functions.FabricLakehouseClient: Permite trabalhar com Lakehouses, oferecendo uma forma de se conectar a tabelas e ficheiros de Lakehouse.

Para fazer referência a uma conexão com uma fonte de dados, precisas usar o decorador @udf.connection. 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 a favor @udf.connection são os seguintes:

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ê poderá 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:
  # 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

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

As conexões genéricas permitem que você crie conexões com itens de malha ou recursos do Azure usando sua identidade de proprietário do item 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 de malha ou recursos do Azure que dão suporte a esse tipo de público. Esse processo lhe dará 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.

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

Parâmetro	Descrição	Valor
`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 o `argName=CosmosDb`, então a função deve conter este argumento `cosmosDb: fn.FabricItem`
`audienceType`	O tipo de público para o qual a conexão é criada. Esse parâmetro está associado ao tipo de item de malha ou serviço do Azure e determina o cliente usado para a conexão.	Os valores permitidos para este 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 suportam itens nativos do Fabric Cosmos DB usando o tipo de público CosmosDB. 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 Cosmos DB singleton para cada invocação.

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

No item de Funções de Dados do Utilizador do Fabric, instale a azure-cosmos biblioteca usando a experiência de Gerenciamento de Biblioteca.
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 o seu endpoint 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 do banco de dados. A conta de proprietário das Funções de Dados do Usuário precisaria de permissões para aceder a essa conta do Azure Cosmos DB.

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

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

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

No item das Funções de Utilização de Dados do Fabric, instale a requests e a biblioteca azure-keyvault-secrets usando a experiência de gestão de biblioteca.
Vá para o recurso do Cofre da Chave do Azure e recupere o Vault URI e o nome da sua chave, segredo ou certificado.

Volte para o item Fabric User Data Functions e use este exemplo. Neste exemplo, recuperamos um segredo do Cofre da Chave do Azure para nos conectarmos a uma API pública. Substitua o valor das seguintes variáveis:

KEY_VAULT_URL com o Vault URI que recuperaste na fase anterior.
KEY_VAULT_SECRET_NAME com o nome do seu segredo.
API_URL variável com a URL da API à qual você deseja se conectar. Este exemplo pressupõe que você esteja 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.

Obter propriedades de invocação usando `UserDataFunctionContext`

O modelo de programação também inclui o objeto UserDataFunctionContext. Este objeto contém os metadados de invocação de função e pode ser usado para criar lógica de aplicativo específica para determinados mecanismos de invocação.

A tabela a seguir mostra as propriedades do objeto UserDataFunctionContext:

Nome da propriedade	Tipo de dados	Descrição
ID de invocação	cadeia (de caracteres)	O GUID exclusivo vinculado à invocação do item de funções de dados do usuário.
Utilizador Executante	objecto	Metadados das informações do usuário usados para autorizar a invocação.

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

Nome da propriedade	Tipo de dados	Descrição
Oide	cadeia de caracteres (GUID)	O ID do objeto do usuário, que é um identificador imutável para o solicitante. Essa é a identidade verificada do usuário ou da entidade de serviço usada para invocar essa função entre aplicativos.
Id do Locatário	cadeia de caracteres (GUID)	O ID do inquilino ao qual o utilizador está ligado.
NomeDeUtilizadorPreferido	cadeia (de caracteres)	O nome de usuário preferido do usuário que invoca, conforme definido pelo usuário. Este valor é mutável.

Para acessar o parâmetro UserDataFunctionContext, você deve usar o seguinte decorador na parte superior 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 = {context.executing_user['Oid']}, TenantId = {context.executing_user['TenantId']}, PreferredUsername = {context.executing_user['PreferredUsername']}, InvocationId = {context.invocation_id}"

Lançar um erro controlado com `UserThrownError`

Ao desenvolver sua função, você pode lançar uma resposta de erro esperada usando o método UserThrownError disponível no modelo de programação Python. Um uso desse método é o gerenciamento de casos em que as entradas fornecidas pelo usuário não passam pelas 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()}!"

Este método UserThrownError usa dois parâmetros:

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

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

Uma Fabric Variable Library no Microsoft Fabric é um repositório centralizado para gerir variáveis que podem ser usadas em diferentes itens num espaço de trabalho. Ele permite que os desenvolvedores personalizem e compartilhem configurações de itens de forma eficiente.

Adicione uma conexão a uma biblioteca de variáveis usando Gerenciar conexões e obtenha o alias para o item de biblioteca variável.
Adicione um decorador @udf.connection(argName="varLib", alias="<My Variable Library Alias>") de conexões para fazer referência ao alias do item de biblioteca variável.
Na definição da função, inclua um argumento com o tipo fn.FabricVariablesClient. Este cliente fornece métodos que você precisa para trabalhar com o item de biblioteca de variáveis. Por exemplo, def standardize_date(rawDate: str, varLib: fn.FabricVariablesClient) -> str:
Use getVariables() o método para obter todas as variáveis da biblioteca de variáveis.

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

1 Para ler os valores das variáveis, use ["variable-name"] ou .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")

Comentários

Esta página foi útil?

Last updated on 2025-11-10