Gambaran Umum Model Pemrograman Fungsi Data Pengguna Fabric

Model pemrograman fungsi data Fabric User adalah SDK yang menyediakan fungsionalitas yang diperlukan untuk menulis dan menerbitkan fungsi yang dapat dijalankan di Fabric. 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.

SDK untuk fungsi data pengguna

Item fungsi data pengguna berisi satu atau banyak fungsi yang dapat Anda panggil dari portal Fabric, dari item Fabric lain, atau dari aplikasi eksternal menggunakan titik akhir REST yang disediakan. Setiap fungsi adalah metode dalam skrip Python Anda yang memungkinkan melewati parameter dan mengembalikan output ke pemanggil. Model pemrograman fungsi data pengguna berisi komponen berikut:

Pustaka fabric.functions menyediakan kode yang Anda butuhkan untuk membuat fungsi data pengguna di Python. Anda dapat melihat pustaka ini diimpor dalam templat fungsi pertama Anda ketika Anda membuat item fungsi data pengguna baru.
Metode fn.UserDataFunctions() ini menyediakan konteks eksekusi yang ditemukan di awal file kode di semua item fungsi data pengguna baru, sebelum definisi fungsi apa pun.

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

udf = fn.UserDataFunctions()
```

Setiap fungsi diidentifikasi dengan dekorator @udf.function(). Dekorator ini menentukan apakah fungsi Anda dapat dipanggil satu per satu dari portal atau pemanggil eksternal. Menggunakan dekorator ini juga mengharuskan fungsi memiliki nilai pengembalian. Fungsi dengan dekorator ini dapat mengakses objek koneksi yang ditandai oleh @udf.connection dekorator.

Contoh fungsi yang dapat dipanggil

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

Setiap metode Python tanpa dekorator @udf.function() tidak dapat dipanggil secara langsung. Mereka hanya dapat dipanggil dari fungsi yang berisi dekorator, dan dapat digunakan sebagai fungsi pembantu.

contoh fungsi pembantu

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

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 jenis DataFrame dan Series pandas, pilih Pengelolaan Pustaka di portal Fabric untuk fungsi data milik Anda dan perbarui versi fabric-user-data-function ke 1.0.0.

Contoh isi permintaan untuk jenis input yang didukung:

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

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

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

Koneksi data ke sumber data Fabric

Modul ini memungkinkan Anda untuk 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:
  # 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

Koneksi generik untuk item Fabric atau sumber daya Azure

Koneksi generik 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. Proses ini akan memberi Anda 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:

Dalam item Fabric User Data Functions Anda, instal azure-cosmos pustaka menggunakan antarmuka Manajemen 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:

Dalam item Fabric User Data Functions Anda, instal requests dan azure-keyvault-secrets pustaka menggunakan antarmuka Manajemen Pustaka.
Buka sumber daya Azure Key Vault Anda 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.

Mendapatkan properti pemanggilan menggunakan `UserDataFunctionContext`

Model pemrograman juga mencakup objek UserDataFunctionContext. Objek ini berisi metadata pemanggilan fungsi dan dapat digunakan untuk membuat logika aplikasi tertentu untuk mekanisme pemanggilan tertentu.

Tabel berikut memperlihatkan properti untuk objek UserDataFunctionContext:

Nama Properti	Jenis Data	Deskripsi
ID Panggilan	string	GUID unik yang terkait dengan pemanggilan item fungsi data pengguna.
PenggunaEksekusi (ExecutingUser)	objek	Metadata informasi pengguna yang digunakan untuk mengotorisasi pemanggilan.

Objek ExecutingUser 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 = {context.executing_user['Oid']}, TenantId = {context.executing_user['TenantId']}, PreferredUsername = {context.executing_user['PreferredUsername']}, InvocationId = {context.invocation_id}"

Melempar kesalahan yang ditangani dengan `UserThrownError`

Saat mengembangkan fungsi, Anda dapat menghasilkan respons kesalahan yang diharapkan dengan menggunakan metode UserThrownError yang tersedia dalam pemodelan pemrograman Python. Salah satu penggunaan metode 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()}!"

Metode UserThrownError ini 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.

Tambahkan koneksi ke pustaka variabel menggunakan Kelola koneksi dan dapatkan alias untuk item pustaka variabel.
Tambahkan dekorator koneksi, @udf.connection(argName="varLib", alias="<My Variable Library Alias>") untuk mereferensikan alias 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. Misalnya: def standardize_date(rawDate: str, varLib: fn.FabricVariablesClient) -> str:
Gunakan getVariables() metode untuk mendapatkan semua variabel dari pustaka variabel.

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

1 Untuk membaca nilai variabel yang digunakan, baik ["variable-name"] atau .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")

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 2025-11-10