Omówienie modelu programowania danych użytkownika w ramach Fabric

Model programowania funkcji danych użytkownika sieci szkieletowej to zestaw SDK, który zapewnia niezbędne funkcje do tworzenia i publikowania funkcji możliwych do uruchomienia w sieci szkieletowej. Zestaw SDK umożliwia również bezproblemową integrację z innymi elementami w ekosystemie sieci Szkieletowej, takimi jak źródła danych sieci szkieletowej. Ta biblioteka jest publicznie dostępna w PyPI i jest wstępnie zainstalowana w elementach funkcji danych użytkownika.

Zestaw SDK do funkcji danych użytkownika

Element funkcji danych użytkownika zawiera jedną lub wiele funkcji, które można wywołać z portalu sieci szkieletowej, z innego elementu sieci szkieletowej lub z aplikacji zewnętrznej przy użyciu podanego punktu końcowego REST. Każda funkcja jest metodą w skryscie języka Python, która umożliwia przekazywanie parametrów i zwracanie danych wyjściowych do obiektu invoker. Model programowania funkcji danych użytkownika zawiera następujące składniki:

Biblioteka fabric.functions zawiera kod potrzebny do utworzenia funkcji danych użytkownika w Pythonie. Możesz zobaczyć tę bibliotekę importowaną w pierwszym szablonie funkcji, gdy tworzysz nowy element funkcji danych użytkownika.
Metoda fn.UserDataFunctions() udostępnia kontekst wykonywania znaleziony na początku pliku kodu we wszystkich nowych elementach funkcji danych użytkownika przed wszelkimi definicjami funkcji.

Przykład:
```
import datetime
import fabric.functions as fn
import logging

udf = fn.UserDataFunctions()
```
Każda funkcja jest rozpoznawana za pomocą dekoratora @udf.function(). Ten dekorator określa, czy funkcję można wywołać samodzielnie z portalu lub poprzez zewnętrzne wywołanie. Użycie tego dekoratora wymaga również, aby funkcja miała wartość zwracaną. Funkcje z tym dekoratorem mogą uzyskiwać dostęp do obiektów połączenia, które są oznaczone dekoratorem @udf.connection.

przykład funkcji wywoływalnej
```
# 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()}!"
```
Nie można bezpośrednio wywołać żadnych metod Python bez dekoratora @udf.function(). Mogą być wywoływane tylko z funkcji zawierających dekorator i mogą być używane jako funkcje pomocnicze.

Przykład funkcji pomocniczej
```
# 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()
```

Obsługiwane typy danych wejściowych

Można zdefiniować parametry wejściowe dla funkcji, takie jak typy danych pierwotnych, takie jak str, int, float itp. Obsługiwane typy danych wejściowych to:

Typ JSON	typ danych języka Python
String	Str
Ciąg daty/godziny	data/godzina
Boolean	Bool
Liczby	int, float
Tablica	list[], przykładowa lista[int]
Obiekt	słownik
Obiekt	Ramka danych biblioteki pandas
Obiekt lub tablica obiektów	Pandas Series

Uwaga / Notatka

Aby użyć typów DataFrame i Series w pandas, wybierz Zarządzanie biblioteką w portalu Fabric dla funkcji danych użytkownika i zaktualizuj wersję do 1.0.0.

Przykład treści żądania dla obsługiwanych typów danych wejściowych:

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

Obsługiwane typy danych wyjściowych

Obsługiwane typy danych wyjściowych to:

typ danych języka Python
Str
data/godzina
Bool
int, float
list[data-type], na przykład list[int]
słownik
Żaden
Pandas Series
Ramka danych biblioteki pandas

Jak napisać funkcję asynchroniową

Dodaj dekorator asynchroniczny z definicją funkcji w kodzie. async Dzięki funkcji można poprawić czas odpowiedzi i wydajność aplikacji, obsługując jednocześnie wiele zadań. Doskonale nadają się do zarządzania dużymi ilościami operacji związanych z operacjami we/wy. Ta przykładowa funkcja odczytuje plik CSV z magazynu lakehouse przy użyciu biblioteki pandas. Funkcja przyjmuje nazwę pliku jako parametr wejściowy.

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

Połączenia danych ze źródłami danych Fabric

Ten moduł umożliwia odwołanie się do połączeń danych bez konieczności pisania łańcuchów połączenia w kodzie. Biblioteka fabric.functions udostępnia dwa sposoby na obsługę połączeń danych:

fabric.functions.FabricSqlConnection: Umożliwia pracę z bazami danych SQL w usłudze Fabric, w tym punktami końcowymi usługi SQL Analytics i repozytoriami Fabric.
fabric.functions.FabricLakehouseClient: Umożliwia pracę z Lakehouses, oferując możliwość połączenia z tabelami i plikami Lakehouse.

Aby odwołać się do połączenia ze źródłem danych, należy użyć dekoratora @udf.connection. Można go zastosować w dowolnym z następujących formatów:

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

Argumenty dla @udf.connection są następujące:

argName, nazwa zmiennej używanej przez połączenie w funkcji.
alias, alias połączenia dodanego za pomocą menu Zarządzanie połączeniami .
Jeśli argName i alias mają tę samą wartość, możesz użyć @udf.connection("<alias and argName for the data connection>").

Przykład

# 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

Ogólne połączenia dla elementów Fabric lub zasobów Azure

Połączenia ogólne umożliwiają tworzenie połączeń z elementami Fabric lub zasobami platformy Azure przy użyciu tożsamości właściciela elementu w funkcjach danych użytkownika. Ta funkcja generuje token identyfikatora Entra firmy Microsoft z tożsamością właściciela elementu i podanym typem odbiorców. Ten token służy do uwierzytelniania za pomocą elementów sieci szkieletowej lub zasobów platformy Azure, które obsługują ten typ odbiorców. Ten proces zapewnia podobne środowisko programowania do korzystania z obiektów połączeń zarządzanych z funkcji Zarządzanie połączeniami , ale tylko dla podanego typu odbiorców w połączeniu.

Ta funkcja używa dekoratora @udf.generic_connection() z następującymi parametrami:

Parameter	Opis	Wartość
`argName`	Nazwa zmiennej przekazanej do funkcji. Użytkownik musi określić tę zmienną w argumentach funkcji i użyć typu `fn.FabricItem` dla niej	Na przykład jeśli element `argName=CosmosDb`, funkcja powinna zawierać ten argument `cosmosDb: fn.FabricItem`
`audienceType`	Typ odbiorców, dla których jest tworzone połączenie. Ten parametr jest skojarzony z typem elementu sieci szkieletowej lub usługi platformy Azure i określa klienta używanego do połączenia.	Dozwolone wartości tego parametru to `CosmosDb` lub `KeyVault`.

Podłącz się do kontenera Cosmos DB w Fabric przy użyciu połączenia ogólnego

Połączenia ogólne obsługują natywne elementy usługi Cosmos DB Fabric, korzystając z typu odbiorców CosmosDB. Dołączony zestaw SDK funkcji danych użytkownika udostępnia metodę pomocnika o nazwie get_cosmos_client, która uzyskuje pojedynczego klienta usługi Cosmos DB dla każdego wywołania.

Aby nawiązać połączenie z elementem usługi Fabric Cosmos DB , możesz nawiązać połączenie ogólne, wykonując następujące kroki:

W elemencie Funkcje użytkownika Fabric zainstaluj bibliotekę azure-cosmos przy użyciu środowiska zarządzania biblioteką.
Przejdź do ustawień elementu Cosmos DB w usłudze Fabric.
Pobierz adres URL punktu końcowego usługi Fabric dla Cosmos DB.

Przejdź do elementu Funkcje danych użytkownika. Użyj poniższego przykładowego kodu, aby nawiązać połączenie z kontenerem usługi Cosmos DB usługi Fabric i uruchomić zapytanie odczytu przy użyciu przykładowego zestawu danych usługi Cosmos DB. Zastąp wartości następujących zmiennych:

COSMOS_DB_URI z punktem końcowym usługi Fabric Cosmos DB.
DB_NAME z nazwą elementu 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)

Przetestuj lub uruchom tę funkcję , podając nazwę kategorii, na przykład Accessory w parametrach wywołania.

Uwaga / Notatka

Możesz również użyć tych kroków, aby nawiązać połączenie z bazą danych usługi Azure Cosmos DB przy użyciu adresu URL konta i nazw baz danych. Konto właściciela usługi User Data Functions będzie potrzebować uprawnień dostępu do tego konta usługi Azure Cosmos DB.

Nawiązywanie połączenia z usługą Azure Key Vault przy użyciu połączenia ogólnego

Połączenia ogólne obsługują nawiązywanie połączenia z usługą Azure Key Vault przy użyciu KeyVault typu odbiorców. Ten typ połączenia wymaga, aby właściciel funkcji danych użytkownika Fabric miał uprawnienia do nawiązywania połączenia z Azure Key Vault. Możesz użyć tego połączenia, aby pobierać klucze, sekrety lub certyfikaty na podstawie nazwy.

Aby pobrać klucz tajny klienta w celu wywołania interfejsu API przy użyciu połączenia ogólnego, możesz nawiązać połączenie z usługą Azure Key Vault , wykonując następujące kroki:

W elemencie Funkcje danych użytkownika Fabric zainstaluj biblioteki requests i azure-keyvault-secrets przy użyciu zarządzania bibliotekami.
Przejdź do zasobu usługi Azure Key Vault i pobierz Vault URI nazwę klucza, wpisu tajnego lub certyfikatu.

Wróć do Funkcji danych użytkownika Fabric i użyj tego przykładu. W tym przykładzie pobieramy tajną wartość z usługi Azure Key Vault, aby połączyć się z publicznym interfejsem API. Zastąp wartość następujących zmiennych:

KEY_VAULT_URL przy użyciu elementu Vault URI, który pobrano w poprzednim kroku.
KEY_VAULT_SECRET_NAME z nazwą twojego sekretu.
API_URL zmienna z adresem URL interfejsu API, z którym chcesz nawiązać połączenie. W tym przykładzie założono, że nawiązujesz połączenie z publicznym interfejsem API, który akceptuje żądania GET i przyjmuje następujące parametry api-key i 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}"

Przetestuj lub uruchom tę funkcję , podając treść żądania w kodzie.

Uzyskiwanie właściwości wywołania przy użyciu polecenia `UserDataFunctionContext`

Model programowania zawiera również obiekt UserDataFunctionContext. Ten obiekt zawiera metadane wywołania funkcji i może służyć do tworzenia określonej logiki aplikacji dla niektórych mechanizmów wywołania.

W poniższej tabeli przedstawiono właściwości obiektu UserDataFunctionContext.

Nazwa właściwości	Typ danych	Opis
Identyfikator wywołania	ciąg	Unikatowy identyfikator GUID powiązany z wywołaniem elementu funkcji danych użytkownika.
Użytkownik wykonujący	obiekt	Metadane informacji użytkownika używanych do autoryzowania wywołania.

Obiekt ExecutingUser zawiera następujące informacje:

Nazwa właściwości	Typ danych	Opis
Oid	string (GUID)	Identyfikator obiektu użytkownika, który jest niezmiennym identyfikatorem osoby żądającej. Jest to zweryfikowana tożsamość użytkownika lub jednostki usługi używanej do wywoływania tej funkcji w aplikacjach.
Identyfikator najemcy	string (GUID)	Identyfikator dzierżawcy, z którym użytkownik jest zalogowany.
Preferowana nazwa użytkownika	ciąg	Preferowana nazwa użytkownika wywołującego użytkownika ustawiona przez użytkownika. Ta wartość jest modyfikowalna.

Aby uzyskać dostęp do parametru UserDataFunctionContext , należy użyć następującego dekoratora w górnej części definicji funkcji: @udf.context(argName="<parameter name>")

Przykład

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

Zgłaszanie obsłużonego błędu za pomocą polecenia `UserThrownError`

Podczas opracowywania funkcji, można zgłosić oczekiwany komunikat o błędzie, używając metody UserThrownError, dostępnej w modelu programowania Python. Jednym zastosowaniem tej metody jest zarządzanie przypadkami, w których dane wejściowe dostarczone przez użytkownika nie przechodzą reguł walidacji biznesowej.

Przykład

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

Ta metoda UserThrownError przyjmuje dwa parametry:

Message: ten ciąg jest zwracany jako komunikat o błędzie do aplikacji wywołującej tę funkcję.
Słownik właściwości jest zwracany do aplikacji wywołującej tę funkcję.

Pobieranie zmiennych z bibliotek zmiennych Fabric

Biblioteka Zmiennych Fabric w usłudze Microsoft Fabric to scentralizowane repozytorium do zarządzania zmiennymi, które mogą być używane w różnych elementach obszaru roboczego. Umożliwia deweloperom wydajne dostosowywanie i udostępnianie konfiguracji elementów.

Dodaj połączenie do biblioteki zmiennych przy użyciu opcji Zarządzaj połączeniami i uzyskaj alias dla elementu biblioteki zmiennych.
Dodaj dekorator połączeń, @udf.connection(argName="varLib", alias="<My Variable Library Alias>") aby odwołać się do aliasu elementu biblioteki zmiennych.
W definicji funkcji dołącz argument o typie fn.FabricVariablesClient. Ten klient udostępnia metody potrzebne do pracy z elementem biblioteki zmiennych. Na przykład def standardize_date(rawDate: str, varLib: fn.FabricVariablesClient) -> str:
Użyj getVariables() metody , aby pobrać wszystkie zmienne z biblioteki zmiennych.

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

1 Aby odczytać wartości zmiennych, użyj polecenia ["variable-name"] lub .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")

Dokumentacja interfejsu API referencyjnego
Utwórz element funkcji danych użytkownika Fabric
przykłady funkcji danych użytkownika

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-11-10