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 é um SDK que fornece a funcionalidade necessária para criar e publicar funções executáveis no Fabric. 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.

Funções de dados do usuário SDK

Um item de funções de dados do usuário contém uma ou muitas funções que você pode invocar do portal do Fabric, de outro item do Fabric ou de um aplicativo externo usando o ponto de extremidade REST fornecido. Cada função é um método no seu script Python que permite passar parâmetros e retornar uma saída ao 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 no 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 qualquer definição de função.

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

udf = fn.UserDataFunctions()
```

Cada função é identificada com um decorador @udf.function(). Esse decorador define se sua função pode ser invocada individualmente do portal ou de um invocador externo. Usar esse decorador também requer que a função tenha um valor retornado. As funções com este decorador podem acessar os objetos de conexão indicados pelo decorador @udf.connection.

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

Nenhum método Python sem o decorador @udf.function() pode ser invocado diretamente. Elas só podem ser invocadas a partir de funções que contenham o decorador e podem ser usadas 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 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, selecione o gerenciamento de biblioteca no portal do Fabric para a função de dados do usuário e atualize fabric-user-data-function a versão para 1.0.0.

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

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

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

Conexões de dados com fontes de dados do Fabric

Esse módulo permite que você faça referência às conexões de dados sem a necessidade de escrever strings 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:
  # 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 do Fabric ou recursos do Azure

Conexões genéricas permitem que você crie 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. Esse processo fornecerá 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:

No item Funções de Dados do Usuário do Fabric, instale a azure-cosmos biblioteca usando a experiência de Gerenciamento de 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:

No item Funções de Dados do Usuário do Fabric, instale as bibliotecas e usando a experiência de Gerenciamento de Bibliotecas .
Vá para o recurso do Azure Key Vault 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.

Obtenha propriedades de invocação usando `UserDataFunctionContext`

O modelo de programação também inclui o objeto UserDataFunctionContext. Esse objeto contém os metadados de invocação da 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 UserDataFunctionContext objeto:

Nome da propriedade	Tipo de Dados	Descrição
ID de Invocação	cadeia	O GUID exclusivo vinculado à invocação do item de funções de dados do usuário.
Usuário em Execução	objeto	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
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 = {context.executing_user['Oid']}, TenantId = {context.executing_user['TenantId']}, PreferredUsername = {context.executing_user['PreferredUsername']}, InvocationId = {context.invocation_id}"

Lançar um erro tratado 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 é gerenciar casos em que as entradas fornecidas pelo usuário não passam nas 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()}!"

Esse método UserThrownError recebe 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.

Adicione uma conexão a uma biblioteca de variáveis usando Gerenciar conexões e obtenha o alias para o item de biblioteca de variáveis.
Adicione um decorador de conexão @udf.connection(argName="varLib", alias="<My Variable Library Alias>") para referenciar o alias do item da biblioteca de variáveis.
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. 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 usadas, 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