Yapı Kullanıcı verisi işlevleri programlama modeline genel bakış

Doku Kullanıcısı veri işlevleri programlama modeli, Doku'da çalıştırılabilir işlevler yazmak ve yayımlamak için gerekli işlevleri sağlayan bir SDK'dır. SDK ayrıca Doku ekosistemindeki Doku veri kaynakları gibi diğer öğelerle sorunsuz bir şekilde tümleştirmenizi sağlar. Bu kitaplık PyPI'de genel kullanıma açıktır ve kullanıcı verileri işlevleri öğelerinizde önceden yüklenmiştir.

Kullanıcı verileri işlevleri SDK'sı

Kullanıcı veri işlevleri öğesi, Doku portalından, başka bir Doku öğesinden veya sağlanan REST uç noktasını kullanarak bir dış uygulamadan çağırabileceğiniz bir veya birden çok işlev içerir. Her işlev, Python betiğinizde parametrelerin geçirilmesine ve çağırıcıya bir çıkış döndürülmesini sağlayan bir yöntemdir. Kullanıcı veri işlevleri programlama modeli aşağıdaki bileşenleri içerir:

fabric.functions kütüphanesi, Python'da kullanıcı veri işlevleri oluşturmak için ihtiyacınız olan kodu sağlar. Yeni bir kullanıcı verileri işlevleri öğesi oluşturduğunuzda ilk işlev şablonunuzda bu kitaplığın içeri aktarıldığını görebilirsiniz.
yöntemi fn.UserDataFunctions() , tüm yeni kullanıcı verileri işlevleri öğelerinde kod dosyasının başında bulunan yürütme bağlamını işlev tanımlarından önce sağlar.

Örnek:
```
import datetime
import fabric.functions as fn
import logging

udf = fn.UserDataFunctions()
```
Her işlev bir @udf.function() dekoratörü ile tanımlanır. Bu dekoratör, işlevinizin portaldan mı yoksa bir dış çağırıcıdan mı ayrı ayrı çağrılabileceğini tanımlar. Bu dekoratörün kullanılması işlevin bir dönüş değerine sahip olmasını da gerektirir. Bu dekoratöre sahip işlevler, dekoratör tarafından belirtilen bağlantı nesnelerine @udf.connection erişebilir.

Çağrılabilen işlev örneği
```
# 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()}!"
```
Dekoratör olmadan @udf.function() herhangi bir Python yöntemi doğrudan çağrılamaz. Bunlar yalnızca dekoratör içeren işlevlerden çağrılabilir ve yardımcı işlevler olarak kullanılabilir.

Yardımcı işlevi örneği
```
# 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()
```

Desteklenen giriş türleri

str, int, float gibi ilkel veri türleri gibi işlev için giriş parametreleri tanımlayabilirsiniz. Desteklenen giriş veri türleri şunlardır:

JSON Türü	Python Veri Türü
Dizgi	str
Tarih saat dizesi	tarih/zaman
Boolean	Boole
Sayılar	int (tamsayı), float (kesirli sayı)
Dizi	list[], örnek liste[int]
Nesne	Dict
Nesne	pandas DataFrame
Nesne veya Nesne Dizisi	pandas Serisi

Uyarı

pandas DataFrame ve Series türlerini kullanmak için kullanıcı verileri işleviniz için Doku portalında Kitaplık yönetimi'ni seçin ve fabric-user-data-function sürümünü 1.0.0'a güncelleyin.

Desteklenen giriş türleri için istek gövdesi örneği:

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

Desteklenen çıkış türleri

Desteklenen çıkış veri türleri şunlardır:

Python Veri Türü
str
tarih/zaman
Boole
int (tamsayı), float (kesirli sayı)
list[data-type], örneğin list[int]
Dict
Hiç kimse
pandas Serisi
pandas DataFrame

Asenkron işlev yazma

Kodunuzda fonksiyon tanımınızda asenkron dekoratör ekleyin. Bir async işlevle, birden çok görevi aynı anda işleyerek uygulamanızın yanıt hızını ve verimliliğini geliştirebilirsiniz. Yüksek hacimli G/Ç bağlantılı işlemleri yönetmek için idealdir. Bu örnek işlev, pandas kullanarak bir göl evinden CSV dosyasını okur. İşlev, giriş parametresi olarak dosya adını alır.

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

Fabric veri kaynaklarına veri bağlantıları

Bu modül, kodunuzda bağlantı dizeleri yazmaya gerek kalmadan veri bağlantılarına başvurmanızı sağlar. fabric.functions kitaplığı, veri bağlantılarını işlemek için iki yol sunar.

fabric.functions.FabricSqlConnection: SQL Analytics uç noktaları ve Doku ambarları dahil olmak üzere Doku'daki SQL veritabanlarıyla çalışmanıza olanak tanır.
fabric.functions.FabricLakehouseClient: Lakehouse tablolarına ve dosyalarına bağlanmanıza olanak tanıyarak Lakehouse'larla çalışmanıza imkan tanır.

Bir veri kaynağına referansta bulunmak için @udf.connection dekoratörünü kullanmanız gerekir. Aşağıdaki biçimlerden herhangi birinde uygulayabilirsiniz:

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

@udf.connection için bağımsız değişkenler şunlardır:

argName, bağlantının işlevinizde kullandığı değişkenin adı.
alias, Bağlantıları Yönet menüsüyle eklediğiniz bağlantının takma adıdır.
ve argName aynı değere sahipse alias kullanabilirsiniz@udf.connection("<alias and argName for the data connection>").

Örnek

# 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

Fabric öğeleri veya Azure kaynakları için genel bağlantılar

Genel bağlantılar, Kullanıcı Verileri İşlevleri öğe sahibi kimliğinizi kullanarak Doku öğelerine veya Azure kaynaklarına bağlantı oluşturmanıza olanak tanır. Bu özellik, öğe sahibinin kimliğine ve sağlanan hedef kitle türüne sahip bir Microsoft Entra Id belirteci oluşturur. Bu belirteç, bu hedef kitle türünü destekleyen Doku öğeleri veya Azure kaynaklarıyla kimlik doğrulaması yapmak için kullanılır. Bu işlem, Bağlantıları Yönet özelliğinden yönetilen bağlantılar nesnelerini kullanmaya benzer bir programlama deneyimi sağlar, ancak yalnızca bağlantıda sağlanan hedef kitle türü için kullanılır.

Bu özellik aşağıdaki @udf.generic_connection() parametrelerle dekoratör kullanır:

Parametre	Açıklama	Değer
`argName`	İşleve geçirilen değişkenin adı. Kullanıcının işlevinin bağımsız değişkenlerinde bu değişkeni belirtmesi ve bunun için türünü `fn.FabricItem` kullanması gerekir	Örneğin, eğer `argName=CosmosDb` ise işlevi bu bağımsız değişkeni içermelidir. `cosmosDb: fn.FabricItem`
`audienceType`	Bağlantının oluşturulduğu hedef kitle türü. Bu parametre Doku öğesi veya Azure hizmeti türüyle ilişkilendirilir ve bağlantı için kullanılan istemciyi belirler.	Bu parametre için izin verilen değerler `CosmosDb` veya `KeyVault` şeklindedir.

Genel bağlantı kullanarak Fabric Cosmos DB kapsayıcısına bağlanın

Genel bağlantılar, CosmosDB izleyici türünü kullanarak özgün Fabric Cosmos DB öğelerini destekler. Dahil edilen Kullanıcı Verileri İşlevleri SDK'sı, her çağrı için tek bir Cosmos DB istemcisi getiren adlı get_cosmos_client bir yardımcı yöntem sağlar.

Şu adımları izleyerek genel bir bağlantı kullanarak bir Fabric Cosmos DB öğesine bağlanabilirsiniz:

Doku Kullanıcı Verileri İşlevleri öğenizde Kitaplık azure-cosmos yükleyin.
Fabric Cosmos DB öğesi ayarlarınıza gidin.
Fabric Cosmos DB uç noktasının URL'sini alın.

Kullanıcı Verileri İşlevleri öğenize gidin. Doku Cosmos DB kapsayıcınıza bağlanmak ve Cosmos DB örnek veri kümesini kullanarak bir okuma sorgusu çalıştırmak için aşağıdaki örnek kodu kullanın. Aşağıdaki değişkenlerin değerlerini değiştirin:

COSMOS_DB_URI kullanarak Fabric Cosmos DB uç noktanızı kullanın.
DB_NAME ifadesini, Doku Cosmos DB öğenizin adıyla değiştirin.

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)

Çağırma parametrelerinde olduğu gibi bir kategori adı sağlayarak Accessory.

Uyarı

Hesap URL'sini ve veritabanı adlarını kullanarak bir Azure Cosmos DB veritabanına bağlanmak için de bu adımları kullanabilirsiniz. Kullanıcı Veri İşlevleri sahip hesabının bu Azure Cosmos DB hesabı için erişim izinleri olması gerekir.

Genel bir bağlantı kullanarak Azure Key Vault'a bağlanma

Genel bağlantılar, KeyVault dinleyici türünü kullanarak Azure Key Vault'a bağlanmayı destekler. Bu tür bir bağlantı, Doku Kullanıcı Verileri İşlevleri sahibinin Azure Key Vault'a bağlanma izinlerine sahip olmasını gerektirir. Anahtarları, gizli dizileri veya sertifikaları ada göre almak için bu bağlantıyı kullanabilirsiniz.

Genel bir bağlantı kullanarak API çağrılarını yapmak için bir istemci sırrını almak üzere Azure Key Vault'a aşağıdaki adımları izleyerek bağlanabilirsiniz:

Fabric Kullanıcı Verileri İşlevleri öğenizde, requests ve azure-keyvault-secrets kitaplıklarını Kitaplık Yönetimi arayüzünü kullanarak yükleyin.
Azure Key Vault kaynağınıza gidin ve anahtarınızın, gizli dizinizin veya sertifikanızın adını alınVault URI.

Doku Kullanıcı Verileri İşlevleri öğenize dönün ve bu örneği kullanın. Bu örnekte, genel API'ye bağlanmak için Azure Key Vault'tan bir gizli dizi alıyoruz. Aşağıdaki değişkenlerin değerini değiştirin:

KEY_VAULT_URL ile önceki adımda aldığınız Vault URI öğesini kullanın.
KEY_VAULT_SECRET_NAME gizlinizin adıyla.
API_URL değişkenine bağlanmak istediğiniz API'nin URL'sini ekleyin. Bu örnekte GET isteklerini kabul eden ve aşağıdaki parametreleri api-key ve request-bodyalan bir genel API'ye bağlandığınız varsayılır.

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

Kodunuzda bir istek gövdesi sağlayarak bu işlevi test edin veya çalıştırın.

`UserDataFunctionContext` kullanarak çağırma özelliklerini al

Programlama modeli nesnesini de içerir UserDataFunctionContext . Bu nesne işlev çağırma meta verilerini içerir ve belirli çağırma mekanizmaları için belirli uygulama mantığı oluşturmak için kullanılabilir.

Aşağıdaki tabloda UserDataFunctionContext nesnesinin özellikleri gösterilmektedir.

Özellik Adı	Veri Türü	Açıklama
Çağırma Kimliği	String	Kullanıcı veri işlevlerinin öğesinin çağrılmasıyla ilişkili benzersiz GUID.
Yürütücü Kullanıcı	nesne	Çağrıyı yetkilendirmek için kullanılan kullanıcının bilgilerinin meta verileri.

ExecutingUser nesnesi aşağıdaki bilgileri içerir:

Özellik Adı	Veri Türü	Açıklama
Oıd	dize (GUID)	İstek sahibi için sabit bir tanımlayıcı olan kullanıcının nesne kimliği. Bu, uygulamalar arasında bu işlevi çağırmak için kullanılan kullanıcı veya hizmet sorumlusunun doğrulanmış kimliğidir.
KiracıID	dize (GUID)	Kullanıcının oturum açtığı kiracının kimliği.
Tercih Edilen Kullanıcı Adı	String	Kullanıcı tarafından belirlenen, çağıran kullanıcının tercih edilen kullanıcı adı. Bu değer değişebilir.

parametresine UserDataFunctionContext erişmek için işlev tanımının en üstünde aşağıdaki dekoratörü kullanmanız gerekir: @udf.context(argName="<parameter name>")

Örnek

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

`UserThrownError` ile işlenen bir hata atın

İşlevinizi geliştirirken, Python programlama modelinde bulunan bir yöntemi kullanarak beklenen bir hata yanıtı fırlatabilirsiniz. Bu yöntemin bir kullanımı, kullanıcı tarafından sağlanan girişlerin iş doğrulama kurallarını geçememesi durumlarını yönetmektir.

Örnek

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

Bu UserThrownError yöntem iki parametre alır:

Message: Bu dize, bu işlevi çağıran uygulamaya hata iletisi olarak döndürülür.
Bu işlevi çağıran uygulamaya bir özellik sözlüğü döndürülür.

Fabric değişken kütüphanelerinden değişkenleri alma

Microsoft Fabric'teki Fabric Variable Library, çalışma alanı içindeki farklı öğeler arasında kullanılabilecek değişkenleri yönetmeye yönelik merkezi bir depodur. Geliştiricilerin öğe yapılandırmalarını verimli bir şekilde özelleştirmesine ve paylaşmasına olanak tanır.

Bağlantıları yönet'i kullanarak bir değişken kitaplığına bağlantı ekleyin ve değişken kitaplığı öğesinin diğer adını alın.
Değişken kitaplık öğesinin diğer adına başvurmak için bir bağlantı dekoratörü @udf.connection(argName="varLib", alias="<My Variable Library Alias>") ekleyin.
İşlev tanımına türüne fn.FabricVariablesClientsahip bir bağımsız değişken ekleyin. Bu istemci, değişkenler kitaplığı öğesiyle çalışmak için ihtiyacınız olan yöntemleri sağlar. Örneğin, def standardize_date(rawDate: str, varLib: fn.FabricVariablesClient) -> str:
Değişken kitaplığındaki tüm değişkenleri almak için yöntemini kullanın getVariables() .

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

Değişkenlerin değerlerini okumak için ya ["variable-name"] ya da .get("variable-name") kullanın.

  # 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")

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-11-10