Gambaran Umum Model Pemrograman Fungsi Data Pengguna Fabric

Model pemrograman fungsi data Fabric User mendefinisikan pola dan konsep untuk fungsi penulisan di Fabric.

fabric-user-data-functions SDK mengimplementasikan model pemrograman ini, menyediakan fungsionalitas yang diperlukan untuk menulis dan menerbitkan fungsi yang dapat dijalankan. SDK juga memungkinkan Anda untuk berintegrasi dengan mulus dengan item lain dalam ekosistem Fabric, seperti sumber data Fabric. Pustaka ini tersedia untuk umum di PyPI dan telah diinstal sebelumnya di item fungsi data pengguna Anda.

Artikel ini menjelaskan cara menggunakan SDK untuk membangun fungsi yang dapat dipanggil dari portal Fabric, item Fabric lainnya, atau aplikasi eksternal menggunakan REST API. Anda mempelajari model pemrograman dan konsep utama dengan contoh praktis.

Tip

Untuk detail lengkap tentang semua kelas, metode, dan parameter, lihat dokumentasi referensi SDK.

Mulai menggunakan SDK

Bagian ini memperkenalkan komponen inti SDK Fungsi Data Pengguna dan menjelaskan cara menyusun fungsi Anda. Anda mempelajari tentang impor, dekorator, dan jenis data input dan output yang dapat ditangani fungsi Anda.

SDK untuk fungsi data pengguna

fabric-user-data-functions SDK menyediakan komponen inti yang Anda butuhkan untuk membuat fungsi data pengguna di Python.

Impor dan inisialisasi yang diperlukan

Setiap file fungsi data pengguna harus mengimpor fabric.functions modul dan menginisialisasi konteks eksekusi:

import datetime
import fabric.functions as fn
import logging

udf = fn.UserDataFunctions()

Dekorator @udf.function()

Fungsi yang ditandai dengan @udf.function() dekorator dapat dipanggil dari portal Fabric, item Fabric lain, atau aplikasi eksternal. Fungsi dengan dekorator ini harus menentukan tipe pengembalian.

Contoh :

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

Fungsi pembantu

Metode Python tanpa @udf.function() dekorator tidak dapat dipanggil secara langsung. Mereka hanya dapat dipanggil dari fungsi yang didekorasi dan berfungsi sebagai fungsi pembantu.

Contoh :

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

Jenis input yang didukung

Anda dapat menentukan parameter input untuk fungsi seperti jenis data primitif seperti str, int, float, dll. Jenis data input yang didukung adalah:

Jenis JSON	Tipe Data Python
String	Str
string tanggal waktu	tanggalwaktu
Boolean	bool
Jumlah	int (bilangan bulat), float (bilangan desimal)
Array	list[], contoh list[int]
Objek	kamus
Objek	pandas DataFrame
Objek atau Array Objek	Seri pandas

Nota

Untuk menggunakan tipe pandas DataFrame dan Series, akses portal Fabric, temukan ruang kerja Anda, dan buka item fungsi data pengguna Anda. Pilih Manajemen pustaka, cari fabric-user-data-functions paket, dan perbarui ke versi 1.0.0 atau yang lebih baru.

Contoh isi permintaan untuk jenis input yang didukung:

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

Tipe output yang didukung

Jenis data output yang didukung adalah:

Tipe Data Python
Str
tanggalwaktu
bool
int (bilangan bulat), float (bilangan desimal)
list[data-type], contohnya list[int]
kamus
Tidak ada
Seri pandas
pandas DataFrame

Menulis fungsi

Persyaratan dan batasan sintaksis

Saat menulis Fungsi Data Pengguna, Anda harus mengikuti aturan sintaks tertentu untuk memastikan fungsi Anda berfungsi dengan benar.

Penamaan parameter

Gunakan camelCase: Nama parameter harus menggunakan konvensi penamaan camelCase dan tidak boleh berisi garis bawah. Misalnya, gunakan productName, bukan product_name.
Kata kunci yang dipesan: Anda tidak dapat menggunakan kata kunci Python yang dipesan atau kata kunci khusus untuk Fabric berikut sebagai nama parameter atau nama fungsi: req, context, dan reqInvocationId.

Persyaratan parameter

Tidak ada nilai default: Nilai parameter default tidak didukung. Semua parameter diperlukan saat memanggil fungsi. Misalnya, fungsi berikut melemparkan kesalahan sintaks:

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

Anotasi tipe yang diperlukan: Semua parameter harus menyertakan anotasi tipe (misalnya, name: str).

Persyaratan fungsi

Jenis pengembalian diperlukan: Fungsi dengan @udf.function() dekorator harus menentukan anotasi jenis pengembalian (misalnya, -> str).
Impor yang diperlukan: Pernyataan import fabric.functions as fn dan udf = fn.UserDataFunctions() inisialisasi diperlukan agar fungsi Anda berfungsi.

Contoh sintaks yang benar

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

Cara menulis fungsi asinkron

Tambahkan dekorator asinkron dengan definisi fungsi Anda dalam kode Anda. async Dengan fungsi, Anda dapat meningkatkan responsivitas dan efisiensi aplikasi Anda dengan menangani beberapa tugas sekaligus. Mereka ideal untuk mengelola volume tinggi operasi terikat I/O. Contoh fungsi ini membaca file CSV dari Lakehouse menggunakan Pandas. Fungsi mengambil nama file sebagai parameter input.

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

Bekerja dengan data

Koneksi data ke sumber data Fabric

SDK memungkinkan Anda mereferensikan koneksi data tanpa perlu menulis string koneksi dalam kode Anda. Perpustakaan fabric.functions menyediakan dua cara untuk menangani koneksi data:

fabric.functions.FabricSqlConnection: Memungkinkan Anda bekerja dengan database SQL di Fabric, termasuk endpoint Analitik SQL dan penyimpanan Fabric.
fabric.functions.FabricLakehouseClient: Memungkinkan Anda bekerja dengan Lakehouse, dan menyediakan cara untuk terhubung dengan tabel dan file Lakehouse.

Untuk merujuk koneksi ke sumber data, Anda perlu menggunakan dekorator @udf.connection. Anda bisa menerapkannya dalam salah satu format berikut:

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

Argumen untuk @udf.connection adalah:

argName, nama variabel yang digunakan koneksi dalam fungsi Anda.
alias, alias dari koneksi yang Anda tambahkan dengan menu Kelola koneksi.
Jika argName dan alias memiliki nilai yang sama, Anda dapat menggunakan @udf.connection("<alias and argName for the data connection>").

Contoh

# 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

Koneksi generik untuk item Fabric atau sumber daya Azure

SDK mendukung koneksi generik yang memungkinkan Anda membuat koneksi ke item Fabric atau sumber daya Azure menggunakan identitas pemilik item User Data Functions Anda. Fitur ini menghasilkan token ID Microsoft Entra dengan identitas pemilik item dan jenis audiens yang disediakan. Token ini digunakan untuk mengautentikasi dengan item Fabric atau sumber daya Azure yang mendukung jenis audiens tersebut. Pendekatan ini memberikan pengalaman pemrograman serupa untuk menggunakan objek koneksi terkelola dari fitur Kelola Koneksi tetapi hanya untuk jenis audiens yang disediakan dalam koneksi.

Fitur ini menggunakan @udf.generic_connection() dekorator dengan parameter berikut:

Pengaturan	Deskripsi	Nilai
`argName`	Nama variabel yang diteruskan ke fungsi . Pengguna perlu menentukan variabel ini dalam argumen fungsi mereka dan menggunakan jenis `fn.FabricItem` untuk variabel tersebut	Misalnya, jika `argName=CosmosDb`, maka fungsi harus berisi argumen ini `cosmosDb: fn.FabricItem`
`audienceType`	Jenis audiens tempat koneksi dibuat. Parameter ini dikaitkan dengan jenis item Fabric atau layanan Azure dan menentukan klien yang digunakan untuk koneksi.	Nilai yang diizinkan untuk parameter ini adalah `CosmosDb` atau `KeyVault`.

Menyambungkan ke kontainer Fabric Cosmos DB menggunakan koneksi generik

Koneksi generik mendukung item Fabric Cosmos DB asli dengan menggunakan CosmosDB tipe audiens. SDK Fungsi Data Pengguna yang disertakan menyediakan metode pembantu yang disebut get_cosmos_client yang mengambil klien Cosmos DB tunggal untuk setiap pemanggilan.

Anda dapat terhubung ke item Fabric Cosmos DB menggunakan koneksi generik dengan mengikuti langkah-langkah berikut:

Buka portal Fabric, temukan ruang kerja Anda, dan buka item fungsi data pengguna Anda. Pilih Manajemen pustaka, cari azure-cosmos pustaka, dan instal. Untuk informasi selengkapnya, lihat Mengelola pustaka.
Buka pengaturan item Fabric Cosmos DB Anda.
Ambil URL titik akhir Fabric Cosmos DB Anda.

Pergi ke item Fungsi Data Pengguna Anda. Gunakan kode sampel berikut untuk menyambungkan ke kontainer Fabric Cosmos DB Anda dan jalankan kueri baca menggunakan himpunan data sampel Cosmos DB. Ganti nilai variabel berikut:

COSMOS_DB_URI dengan titik akhir Fabric Cosmos DB Anda.
DB_NAME dengan nama item Fabric Cosmos DB Anda.

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)

Uji atau jalankan fungsi ini dengan memberikan nama kategori, seperti Accessory dalam parameter pemanggilan.

Nota

Anda juga dapat menggunakan langkah-langkah ini untuk menyambungkan ke database Azure Cosmos DB menggunakan URL akun dan nama database. Akun pemilik Fungsi Data Pengguna akan memerlukan izin akses ke akun Azure Cosmos DB tersebut.

Menyambungkan ke Azure Key Vault menggunakan koneksi generik

Koneksi generik mendukung menghubungkan dengan Azure Key Vault dengan menggunakan KeyVault sebagai tipe audiens. Jenis koneksi ini mengharuskan pemilik Fabric User Data Functions memiliki izin untuk terhubung ke Azure Key Vault. Anda dapat menggunakan koneksi ini untuk mengambil kunci, rahasia, atau sertifikat berdasarkan nama.

Anda dapat tersambung ke Azure Key Vault untuk mengambil rahasia klien untuk memanggil API menggunakan koneksi generik dengan mengikuti langkah-langkah berikut:

Buka portal Fabric, temukan ruang kerja Anda, dan buka item fungsi data pengguna Anda. Pilih Manajemen pustaka, lalu cari dan instal pustaka requests dan azure-keyvault-secrets. Untuk informasi selengkapnya, lihat Mengelola pustaka.
Buka sumber daya Azure Key Vault Anda di portal Microsoft Azure dan ambil Vault URI dan nama kunci, rahasia, atau sertifikat Anda.

Kembali ke item Fabric User Data Functions Anda dan gunakan contoh ini. Dalam sampel ini, kami mengambil rahasia dari Azure Key Vault untuk menyambungkan ke API publik. Ganti nilai variabel berikut:

KEY_VAULT_URL dengan yang Vault URI Anda ambil di langkah sebelumnya.
KEY_VAULT_SECRET_NAME dengan nama rahasia Anda.
API_URL variabel dengan URL API yang ingin Anda sambungkan. Sampel ini mengasumsikan bahwa Anda terhubung ke API publik yang menerima permintaan GET dan mengambil parameter api-key berikut dan 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}"

Uji atau jalankan fungsi ini dengan menyediakan isi permintaan dalam kode Anda.

Fitur tingkat lanjut

Model pemrograman mendefinisikan pola lanjutan yang memberi Anda kontrol yang lebih besar atas fungsi Anda. SDK mengimplementasikan pola-pola ini melalui kelas dan metode yang memungkinkan Anda untuk:

Mengakses metadata pemanggilan tentang siapa yang memanggil fungsi Anda dan bagaimana
Menangani skenario kesalahan kustom dengan respons kesalahan terstruktur
Integrasikan dengan pustaka variabel Fabric untuk manajemen konfigurasi terpusat

Nota

Fungsi Data Pengguna memiliki batas layanan untuk ukuran permintaan, batas waktu eksekusi, dan ukuran respons. Untuk detail tentang batas ini dan cara penerapannya, lihat Detail dan batasan layanan.

Mendapatkan properti pemanggilan menggunakan `UserDataFunctionContext`

SDK menyertakan objek UserDataFunctionContext. Objek ini berisi metadata pemanggilan fungsi dan dapat digunakan untuk membuat logika aplikasi tertentu untuk mekanisme pemanggilan yang berbeda (seperti pemanggilan portal versus pemanggilan REST API).

Tabel berikut memperlihatkan properti untuk objek UserDataFunctionContext:

Nama Properti	Jenis Data	Deskripsi
invocation_id	string	GUID unik yang terkait dengan pemanggilan item fungsi data pengguna.
pengguna_eksekusi	objek	Metadata informasi pengguna yang digunakan untuk mengotorisasi pemanggilan.

Objek executing_user berisi informasi berikut:

Nama Properti	Jenis Data	Deskripsi
Oid	string (GUID)	ID objek pengguna, yang merupakan pengidentifikasi yang tidak dapat diubah untuk pemohon. Ini adalah identitas terverifikasi pengguna atau perwakilan layanan yang digunakan untuk memanggil fungsi ini di seluruh aplikasi.
ID Penyewa	string (GUID)	ID penyewa yang digunakan pengguna untuk masuk.
NamaPenggunaYangDipilih	string	Nama pengguna pilihan dari pengguna yang memanggil, sebagaimana diatur oleh pengguna. Nilai ini dapat diubah.

Untuk mengakses UserDataFunctionContext parameter, Anda harus menggunakan dekorator berikut di bagian atas definisi fungsi: @udf.context(argName="<parameter name>")

Contoh

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

Melempar kesalahan yang ditangani dengan `UserThrownError`

Saat mengembangkan fungsi Anda, Anda dapat melempar respons kesalahan yang diharapkan dengan menggunakan kelas UserThrownError yang tersedia di SDK. Salah satu penggunaan kelas ini adalah mengelola kasus di mana input yang disediakan pengguna gagal melewati aturan validasi bisnis.

Contoh

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

UserThrownError Konstruktor kelas mengambil dua parameter:

Message: String ini dikembalikan sebagai pesan kesalahan ke aplikasi yang memanggil fungsi ini.
Kamus properti dikembalikan ke aplikasi yang memanggil fungsi ini.

Memperoleh variabel dari pustaka variabel Fabric

Pustaka variabel Fabric di Microsoft Fabric adalah repositori terpusat untuk mengelola variabel yang dapat digunakan di berbagai item dalam ruang kerja. Ini memungkinkan pengembang untuk menyesuaikan dan berbagi konfigurasi item secara efisien. Jika Anda belum memiliki pustaka variabel, lihat Membuat dan mengelola pustaka variabel.

Untuk menggunakan pustaka variabel di fungsi Anda, Anda menambahkan koneksi ke pustaka tersebut dari item fungsi data pengguna Anda. Pustaka variabel muncul di katalog OneLake bersama sumber data seperti database SQL dan lakehouse.

Ikuti langkah-langkah ini untuk menggunakan pustaka variabel di fungsi Anda:

Di item fungsi data pengguna Anda, tambahkan koneksi ke pustaka variabel Anda. Di katalog OneLake, temukan dan pilih pustaka variabel Anda, lalu pilih Sambungkan. Perhatikan Alias yang dihasilkan Fabric untuk koneksi.
Tambahkan dekorator koneksi untuk item pustaka variabel. Misalnya, @udf.connection(argName="varLib", alias="<My Variable Library Alias>") dan ganti alias ke koneksi yang baru ditambahkan untuk item pustaka variabel.
Dalam definisi fungsi, sertakan argumen dengan jenis fn.FabricVariablesClient. Klien ini menyediakan metode yang Anda butuhkan untuk bekerja dengan item pustaka variabel.
Gunakan getVariables() metode untuk mendapatkan semua variabel dari pustaka variabel.
Gunakan, untuk membaca nilai variabel, ["variable-name"] atau .get("variable-name").

Contoh

Dalam contoh ini, kami mensimulasikan skenario konfigurasi untuk produksi dan lingkungan pengembangan. Fungsi ini mengatur jalur penyimpanan tergantung pada lingkungan yang dipilih menggunakan nilai yang diambil dari Pustaka Variabel. Pustaka Variabel berisi variabel yang disebut ENV tempat pengguna dapat mengatur nilai dev atau 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"

Dokumentasi API Referensi
Buat sebuah item fungsi data untuk Pengguna Fabric
Contoh fungsi data pengguna

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-01-22

Bagikan melalui

Gambaran Umum Model Pemrograman Fungsi Data Pengguna Fabric

Mulai menggunakan SDK

SDK untuk fungsi data pengguna

Impor dan inisialisasi yang diperlukan

Dekorator @udf.function()

Fungsi pembantu

Jenis input yang didukung

Tipe output yang didukung

Menulis fungsi

Persyaratan dan batasan sintaksis

Penamaan parameter

Persyaratan parameter

Persyaratan fungsi

Contoh sintaks yang benar

Cara menulis fungsi asinkron

Bekerja dengan data

Koneksi data ke sumber data Fabric

Contoh

Koneksi generik untuk item Fabric atau sumber daya Azure

Menyambungkan ke kontainer Fabric Cosmos DB menggunakan koneksi generik

Menyambungkan ke Azure Key Vault menggunakan koneksi generik

Fitur tingkat lanjut

Mendapatkan properti pemanggilan menggunakan UserDataFunctionContext

Melempar kesalahan yang ditangani dengan UserThrownError

Memperoleh variabel dari pustaka variabel Fabric

Contoh

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan:

Mendapatkan properti pemanggilan menggunakan `UserDataFunctionContext`

Melempar kesalahan yang ditangani dengan `UserThrownError`