Επισκόπηση μοντέλου προγραμματισμού συναρτήσεων δεδομένων χρήστη Fabric

Το μοντέλο προγραμματισμού συναρτήσεων δεδομένων χρήστη Fabric ορίζει τα μοτίβα και τις έννοιες για τις συναρτήσεις σύνταξης στο Fabric.

Το fabric-user-data-functions SDK υλοποιεί αυτό το μοντέλο προγραμματισμού, παρέχοντας την απαραίτητη λειτουργικότητα για τη σύνταξη και τη δημοσίευση συναρτήσεων με δυνατότητα εκτέλεσης. Το SDK σάς επιτρέπει επίσης να ενοποιείτε απρόσκοπτα με άλλα στοιχεία στο οικοσύστημα Fabric, όπως προελεύσεις δεδομένων Fabric. Αυτή η βιβλιοθήκη είναι δημόσια διαθέσιμη στο PyPI και είναι προεγκατεστημένη στα στοιχεία συναρτήσεων δεδομένων χρήστη.

Αυτό το άρθρο εξηγεί πώς μπορείτε να χρησιμοποιήσετε το SDK για να δημιουργήσετε συναρτήσεις που μπορούν να κληθούν από την πύλη Fabric, άλλα στοιχεία Fabric ή εξωτερικές εφαρμογές χρησιμοποιώντας το REST API. Μαθαίνετε το μοντέλο προγραμματισμού και τις βασικές έννοιες με πρακτικά παραδείγματα.

Φιλοδώρημα

Για πλήρεις λεπτομέρειες σχετικά με όλες τις, τις μεθόδους και τις παραμέτρους, ανατρέξτε στην τεκμηρίωση αναφοράς SDK.

Ξεκινώντας με το SDK

Αυτή η ενότητα παρουσιάζει τα βασικά στοιχεία του SDK Συναρτήσεων δεδομένων χρήστη και εξηγεί πώς να δομήσετε τις συναρτήσεις σας. Μαθαίνετε για τις απαιτούμενες εισαγωγές, τους διακοσμητές και τους τύπους δεδομένων εισόδου και εξόδου που μπορούν να χειριστούν οι συναρτήσεις σας.

Συναρτήσεις δεδομένων χρήστη SDK

Το fabric-user-data-functions SDK παρέχει τα βασικά στοιχεία που χρειάζεστε για να δημιουργήσετε συναρτήσεις δεδομένων χρήστη στην Python.

Απαιτούμενες εισαγωγές και προετοιμασία

Κάθε αρχείο συναρτήσεων δεδομένων χρήστη πρέπει να εισάγει το fabric.functions άρθρωμα και να προετοιμάζει το περιβάλλον εκτέλεσης:

import datetime
import fabric.functions as fn
import logging

udf = fn.UserDataFunctions()

Ο @udf.function() διακοσμητής

Οι συναρτήσεις που επισημαίνονται με τον @udf.function() διακοσμητή μπορούν να κληθούν από την πύλη Fabric, ένα άλλο στοιχείο Fabric ή μια εξωτερική εφαρμογή. Οι συναρτήσεις με αυτόν τον διακοσμητή πρέπει να καθορίζουν έναν τύπο επιστροφής.

Παράδειγμα:

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

Βοηθητικές λειτουργίες

Οι μέθοδοι Python χωρίς τον @udf.function() διακοσμητή δεν μπορούν να κληθούν απευθείας. Μπορούν να κληθούν μόνο από διακοσμημένες λειτουργίες και να χρησιμεύσουν ως βοηθητικές λειτουργίες.

Παράδειγμα:

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

Υποστηριζόμενοι τύποι εισόδου

Μπορείτε να ορίσετε παραμέτρους εισόδου για τη συνάρτηση, όπως στοιχειώδεις τύπους δεδομένων όπως συμβολοσειρά, int, κινητή υποδιαστολή κ.λπ. Οι υποστηριζόμενοι τύποι δεδομένων εισόδου είναι οι εξής:

τύπου JSON	τύπου δεδομένων Python
Σειρά	str
συμβολοσειράς ημερομηνίας/ώρας	ημερομηνία/ώρα
δυαδική τιμή	δυαδ.
αριθμών	int, πλωτήρας
Παράταξη	list[], παράδειγμα list[int]
αντικειμένου	dict
αντικειμένου	pandas DataFrame
Αντικείμενο ή Πίνακας αντικειμένων	σειρά pandas

Σημείωμα

Για να χρησιμοποιήσετε τους τύπους pandas DataFrame και Series, μεταβείτε στην πύλη Fabric, βρείτε τον χώρο εργασίας σας και ανοίξτε το στοιχείο συναρτήσεων δεδομένων χρήστη. Επιλέξτε Διαχείριση βιβλιοθήκης, αναζητήστε το fabric-user-data-functions πακέτο και ενημερώστε το στην έκδοση 1.0.0 ή νεότερη.

Παράδειγμα σώματος αίτησης για τύπους εισόδου που υποστηρίζονται:

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

Υποστηριζόμενοι τύποι εξόδου

Οι υποστηριζόμενοι τύποι δεδομένων εξόδου είναι οι εξής:

τύπου δεδομένων Python
str
ημερομηνία/ώρα
δυαδ.
int, πλωτήρας
list[data-type], για παράδειγμα list[int]
dict
Καμία
σειρά pandas
pandas DataFrame

Σύνταξη συναρτήσεων

Απαιτήσεις και περιορισμοί σύνταξης

Όταν γράφετε Συναρτήσεις Δεδομένων Χρήστη, πρέπει να ακολουθείτε συγκεκριμένους συντακτικούς κανόνες για να διασφαλίσετε ότι οι συναρτήσεις σας λειτουργούν σωστά.

Ονομασία παραμέτρων

Χρήση camelCase: Τα ονόματα παραμέτρων πρέπει να χρησιμοποιούν τη σύμβαση ονομασίας camelCase και δεν μπορούν να περιέχουν χαρακτήρες υπογράμμισης. Για παράδειγμα, χρησιμοποιήστε αντί productName για product_name.
Δεσμευμένες λέξεις-κλειδιά: Δεν μπορείτε να χρησιμοποιήσετε δεσμευμένες λέξεις-κλειδιά Python ή τις ακόλουθες λέξεις-κλειδιά ειδικά για το Fabric ως ονόματα παραμέτρων ή συναρτήσεων: req, contextκαι reqInvocationId.

Απαιτήσεις παραμέτρων

Απαιτούμενοι σχολιασμοί τύπων: Όλες οι παράμετροι πρέπει να περιλαμβάνουν σχολιασμούς τύπων (για παράδειγμα, name: str).

Προεπιλεγμένες τιμές: Υποστηρίζονται οι προεπιλεγμένες τιμές παραμέτρων. Μπορείτε να ορίσετε προεπιλεγμένα ορίσματα στις συναρτήσεις δεδομένων χρήστη Fabric για να διευκολύνετε την κλήση και τη συντήρηση του κώδικά σας. Οι παράμετροι με προεπιλεγμένες τιμές είναι προαιρετικές κατά το χρόνο κλήσης. Απαιτούνται παράμετροι χωρίς προεπιλογές. Οι ακόλουθοι τύποι υποστηρίζονται ως προεπιλεγμένες τιμές:

Προεπιλεγμένος τύπος	Notes
Συμβολοσειρά	Οποιαδήποτε συμβολοσειρά με δυνατότητα σειριοποίησης JSON.
Συμβολοσειρά ημερομηνίας/ώρας	Καθορίστε ως συμβολοσειρά στην υπογραφή της συνάρτησης. Ο χρόνος εκτέλεσης αναλύει τη συμβολοσειρά στο `datetime` χρόνο επίκλησης. Χρησιμοποιήστε τη μορφή ISO 8601 (για παράδειγμα, `2025-12-31T23:59:59Z`) για συνεπή, σαφή ανάλυση.
Boolean	`True` ή `False`.
Integer	Οποιαδήποτε ακέραια τιμή.
Float	Οποιαδήποτε τιμή κινητής υποδιαστολής.
Λίστα	Πρέπει να είναι σειριακό JSON. Προτιμήστε `None` στην υπογραφή και εκχωρήστε την πραγματική προεπιλογή μέσα στη συνάρτηση για να αποφύγετε κοινές μεταβλητές προεπιλογές.
Λεξικό	Πρέπει να είναι σειριακό JSON. Προτιμήστε `None` στην υπογραφή και εκχωρήστε την πραγματική προεπιλογή μέσα στη συνάρτηση.
pandas DataFrame	Παρέχεται ως αντικείμενο JSON που το SDK μετατρέπει σε τύπο pandas. Απαιτείται `fabric-user-data-functions` έκδοση 1.0.0 ή νεότερη.
σειρά pandas	Παρέχεται ως συστοιχία JSON αντικειμένων που το SDK μετατρέπει σε τύπο pandas. Απαιτείται `fabric-user-data-functions` έκδοση 1.0.0 ή νεότερη.

Σύνταξη

@udf.function()
def function_name(
    requiredParam: str,
    optionalStr: str = "hello",
    optionalDate: datetime.datetime = "2025-01-01T00:00:00Z",  # specify as a string; the runtime parses it to datetime at invocation time
    optionalBool: bool = True,
    optionalInt: int = 10,
    optionalFloat: float = 1.5,
    optionalList: list | None = None,   # assign real default inside the function
    optionalDict: dict | None = None,   # assign real default inside the function
) -> dict:
    optionalList = optionalList or [1, 2, 3]
    optionalDict = optionalDict or {"key": "value"}
    return {"param": requiredParam}

Οι προεπιλογές πρέπει να είναι σειριοποιήσιμες μέσω JSON (τα σύνολα και οι πλειάδες δεν υποστηρίζονται). Για προεπιλογές λίστας ή λεξικού, χρησιμοποιήστε None το στην υπογραφή και εκχωρήστε την πραγματική προεπιλογή μέσα στη συνάρτηση για να αποφύγετε κοινές μεταβλητές προεπιλογές. Χρησιμοποιήστε τη μορφή ISO 8601 (για παράδειγμα, 2025-12-31T23:59:59Z) για προεπιλογές ημερομηνίας/ώρας. Η χρήση του pandas DataFrame ή Series ως προεπιλογή απαιτεί fabric-user-data-functions έκδοση 1.0.0 ή νεότερη.

Απαιτήσεις λειτουργίας

Απαιτούμενος τύπος επιστροφής: Οι συναρτήσεις με τον @udf.function() διακοσμητή πρέπει να καθορίζουν έναν σχολιασμό τύπου επιστροφής (για παράδειγμα, -> str).
Απαιτούμενες εισαγωγές: Η πρόταση και import fabric.functions as fn η udf = fn.UserDataFunctions() προετοιμασία απαιτούνται για να λειτουργήσουν οι συναρτήσεις σας.

Παράδειγμα σωστής σύνταξης

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

Πώς να γράψετε μια ασύγχρονη συνάρτηση

Προσθέστε ασύγχρονο decorator με τον ορισμό της συνάκρισής σας στον κείμενό σας. Με μια async συνάρτηση, μπορείτε να βελτιώσετε την ανταπόκριση και την αποτελεσματικότητα της εφαρμογής σας, χρησιμοποιώντας πολλαπλές εργασίες ταυτόχρονα. Είναι ιδανικά για τη διαχείριση μεγάλου όγκου λειτουργιών που συνδέονται με I/O. Αυτό το παράδειγμα συνάρτησης διαβάζει ένα αρχείο CSV από ένα lakehouse που χρησιμοποιεί pandas. Η συνάρτηση λαμβάνει το όνομα αρχείου ως παράμετρο εισόδου.

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

Το SDK σάς επιτρέπει να αναφέρετε συνδέσεις δεδομένων χωρίς να χρειάζεται να γράψετε συμβολοσειρές σύνδεσης στον κώδικά σας. Η βιβλιοθήκη fabric.functions παρέχει δύο τρόπους για τον χειρισμό των συνδέσεων δεδομένων:

fabric.functions.FabricSqlConnection: σάς επιτρέπει να εργαστείτε με βάσεις δεδομένων SQL στο Fabric, συμπεριλαμβανομένων τελικών σημείων της SQL Analytics και αποθηκών Fabric.
fabric.functions.FabricLakehouseClient: Σας επιτρέπει να εργαστείτε με Lakehouses, με έναν τρόπο σύνδεσης τόσο σε πίνακες Lakehouse όσο και σε αρχεία Lakehouse.

Για να αναφέρετε μια σύνδεση σε μια προέλευση δεδομένων, πρέπει να χρησιμοποιήσετε το @udf.connection decorator. Μπορείτε να την εφαρμόσετε σε οποιαδήποτε από τις ακόλουθες μορφές:

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

Τα ορίσματα για @udf.connection είναι τα εξής:

argName, το όνομα της μεταβλητής που χρησιμοποιεί η σύνδεση στη συνάφειά σας.
alias, το ψευδώνυμο της σύνδεσης που προσθέσατε με το μενού Διαχείριση συνδέσεων.
Εάν οι argName και alias έχουν την ίδια τιμή, μπορείτε να χρησιμοποιήσετε @udf.connection("<alias and argName for the data connection>").

Παράδειγμα

# 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

Γενικές συνδέσεις για στοιχεία Fabric ή πόρους Azure

Το SDK υποστηρίζει γενικές συνδέσεις που σας επιτρέπουν να δημιουργείτε συνδέσεις σε στοιχεία Fabric ή πόρους Azure χρησιμοποιώντας την ταυτότητα κατόχου του στοιχείου Συναρτήσεις δεδομένων χρήστη. Αυτή η δυνατότητα δημιουργεί ένα διακριτικό Microsoft Entra ID με την ταυτότητα του κατόχου του στοιχείου και έναν παρεχόμενο τύπο κοινού. Αυτό το διακριτικό χρησιμοποιείται για τον έλεγχο ταυτότητας με στοιχεία Fabric ή πόρους Azure που υποστηρίζουν αυτόν τον τύπο κοινού. Αυτή η προσέγγιση παρέχει παρόμοια εμπειρία προγραμματισμού με τη χρήση αντικειμένων διαχειριζόμενων συνδέσεων από τη λειτουργία Διαχείριση συνδέσεων , αλλά μόνο για τον τύπο κοινού που παρέχεται στη σύνδεση.

Αυτή η δυνατότητα χρησιμοποιεί τον @udf.generic_connection() διακοσμητή με τις ακόλουθες παραμέτρους:

Παράμετρος	Περιγραφή	Τιμή
`argName`	Το όνομα της μεταβλητής που μεταβιβάζεται στη συνάρτηση. Ο χρήστης πρέπει να καθορίσει αυτή τη μεταβλητή στα ορίσματα της συνάρτησής του και να χρησιμοποιήσει τον τύπο της `fn.FabricItem` για αυτήν	Για παράδειγμα, εάν το `argName=CosmosDb`, τότε η συνάρτηση θα πρέπει να περιέχει αυτό το όρισμα `cosmosDb: fn.FabricItem`
`audienceType`	Ο τύπος κοινού για τον οποίο δημιουργείται η σύνδεση. Αυτή η παράμετρος σχετίζεται με τον τύπο του στοιχείου Fabric ή της υπηρεσίας Azure και καθορίζει τον υπολογιστή-πελάτη που χρησιμοποιείται για τη σύνδεση.	Οι επιτρεπόμενες τιμές για αυτήν την παράμετρο είναι `CosmosDb` ή `KeyVault`.

Σύνδεση σε κοντέινερ Fabric Cosmos DB με χρήση γενικής σύνδεσης

Οι γενικές συνδέσεις υποστηρίζουν εγγενή στοιχεία Fabric Cosmos DB χρησιμοποιώντας τον CosmosDB τύπο κοινού. Το συμπεριλαμβανόμενο SDK Λειτουργιών Δεδομένων Χρήστη παρέχει μια βοηθητική μέθοδο που ονομάζεται get_cosmos_client που ανακτά έναν πελάτη Cosmos DB για κάθε επίκληση.

Μπορείτε να συνδεθείτε σε ένα στοιχείο Fabric Cosmos DB χρησιμοποιώντας μια γενική σύνδεση ακολουθώντας τα εξής βήματα:

Μεταβείτε στην πύλη Fabric, βρείτε τον χώρο εργασίας σας και ανοίξτε το στοιχείο συναρτήσεων δεδομένων χρήστη. Επιλέξτε Διαχείριση βιβλιοθήκης, αναζητήστε τη βιβλιοθήκη azure-cosmos και εγκαταστήστε την. Για περισσότερες πληροφορίες, ανατρέξτε στο θέμα Διαχείριση βιβλιοθηκών.
Μεταβείτε στις ρυθμίσεις στοιχείων Fabric Cosmos DB .
Ανακτήστε τη διεύθυνση URL τελικού σημείου Fabric Cosmos DB.

Μεταβείτε στο στοιχείο Λειτουργίες δεδομένων χρήστη. Χρησιμοποιήστε το παρακάτω δείγμα κώδικα για να συνδεθείτε στο κοντέινερ Fabric Cosmos DB και να εκτελέσετε ένα ερώτημα ανάγνωσης χρησιμοποιώντας το δείγμα συνόλου δεδομένων Cosmos DB. Αντικαταστήστε τις τιμές των ακόλουθων μεταβλητών:

COSMOS_DB_URI με το τελικό σημείο Fabric Cosmos DB.
DB_NAME με το όνομα του στοιχείου 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)

Δοκιμάστε ή εκτελέστε αυτήν τη συνάρτηση παρέχοντας ένα όνομα κατηγορίας, όπως Accessory στις παραμέτρους κλήσης.

Σημείωμα

Μπορείτε επίσης να χρησιμοποιήσετε αυτά τα βήματα για να συνδεθείτε σε μια βάση δεδομένων Azure Cosmos DB χρησιμοποιώντας τη διεύθυνση URL του λογαριασμού και τα ονόματα της βάσης δεδομένων. Ο λογαριασμός κατόχου User Data Functions θα χρειαζόταν δικαιώματα access σε αυτόν τον λογαριασμό Azure Cosmos DB.

Σύνδεση στο Azure Key Vault με χρήση γενικής σύνδεσης

Οι γενικές συνδέσεις υποστηρίζουν τη σύνδεση σε ένα Azure Key Vault χρησιμοποιώντας τον τύπο κοινού KeyVault. Αυτός ο τύπος σύνδεσης απαιτεί ο κάτοχος των λειτουργιών δεδομένων χρήστη Fabric να έχει δικαιώματα σύνδεσης στο Azure Key Vault. Μπορείτε να χρησιμοποιήσετε αυτήν τη σύνδεση για να ανακτήσετε κλειδιά, μυστικά ή πιστοποιητικά με βάση το όνομα.

Μπορείτε να συνδεθείτε στο Azure Key Vault για να ανακτήσετε έναν μυστικό κωδικό υπολογιστή-πελάτη για να καλέσετε ένα API χρησιμοποιώντας μια γενική σύνδεση, ακολουθώντας τα εξής βήματα:

Μεταβείτε στην πύλη Fabric, βρείτε τον χώρο εργασίας σας και ανοίξτε το στοιχείο συναρτήσεων δεδομένων χρήστη. Επιλέξτε Διαχείριση βιβλιοθήκης και, στη συνέχεια, αναζητήστε και εγκαταστήστε τις βιβλιοθήκες requests και azure-keyvault-secrets. Για περισσότερες πληροφορίες, ανατρέξτε στο θέμα Διαχείριση βιβλιοθηκών.
Μεταβείτε στον πόρο Azure Key Vault στο Azure portal και ανακτήστε το Vault URI και το όνομα του κλειδιού, του μυστικού ή του πιστοποιητικού σας.

Go back στο στοιχείο Fabric User Data Functions και χρησιμοποιήστε αυτό το δείγμα. Σε αυτό το δείγμα, ανακτούμε έναν μυστικό κωδικό από το Azure Key Vault για να συνδεθούμε σε ένα δημόσιο API. Αντικαταστήστε την τιμή των ακόλουθων μεταβλητών:

KEY_VAULT_URL με το Vault URI που ανακτήσατε στο προηγούμενο βήμα.
KEY_VAULT_SECRET_NAME με το όνομα του μυστικού σου.
API_URL με τη διεύθυνση URL του API στο οποίο θέλετε να συνδεθείτε. Αυτό το δείγμα προϋποθέτει ότι συνδέεστε σε ένα δημόσιο API που δέχεται αιτήσεις GET και λαμβάνει τις ακόλουθες παραμέτρους api-key και 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}"

Δοκιμάστε ή εκτελέστε αυτήν τη συνάρτηση παρέχοντας ένα σώμα αίτησης στον κώδικά σας.

Δυνατότητες για προχωρημένους

Το μοντέλο προγραμματισμού ορίζει προηγμένα μοτίβα που σας δίνουν μεγαλύτερο έλεγχο στις λειτουργίες σας. Το SDK υλοποιεί αυτά τα μοτίβα μέσω κλάσεων και μεθόδων που σας επιτρέπουν να κάνετε τα εξής:

Access μετα-δεδομένα επίκλησης σχετικά με το ποιος κάλεσε τη συνάρτησή σας και πώς
Χειρισμός προσαρμοσμένων σεναρίων σφαλμάτων με δομημένες αποκρίσεις σφαλμάτων
Ενοποίηση με βιβλιοθήκες μεταβλητών Fabric για κεντρική διαχείριση διαμόρφωσης

Σημείωμα

Οι Συναρτήσεις δεδομένων χρήστη έχουν όρια υπηρεσίας για το μέγεθος αιτήματος, το χρονικό όριο εκτέλεσης και το μέγεθος απόκρισης. Για λεπτομέρειες σχετικά με αυτά τα όρια και τον τρόπο επιβολής τους, ανατρέξτε στην ενότητα Λεπτομέρειες και περιορισμοί υπηρεσίας.

Λήψη ιδιοτήτων κλήσης με χρήση `UserDataFunctionContext`

Το SDK περιλαμβάνει το UserDataFunctionContext αντικείμενο. Αυτό το αντικείμενο περιέχει τα μετα-δεδομένα κλήσης της συνάρτησης και μπορεί να χρησιμοποιηθεί για τη δημιουργία συγκεκριμένης λογικής εφαρμογής για διαφορετικούς μηχανισμούς επίκλησης (όπως η κλήση πύλης έναντι της επίκλησης REST API).

Ο παρακάτω πίνακας εμφανίζει τις ιδιότητες για το αντικείμενο UserDataFunctionContext:

Όνομα ιδιότητας	Τύπος δεδομένων	Περιγραφή
invocation_id	συμβολοσειρά	Το μοναδικό GUID συνδέεται με την κλήση του στοιχείου συναρτήσεων δεδομένων χρήστη.
executing_user	αντικείμενο	Μετα-δεδομένα των πληροφοριών χρήστη που χρησιμοποιούνται για την εξουσιοδότηση της κλήσης.

Το αντικείμενο executing_user περιέχει τις ακόλουθες πληροφορίες:

Όνομα ιδιότητας	Τύπος δεδομένων	Περιγραφή
Oid	συμβολοσειρά (GUID)	Το αναγνωριστικό αντικειμένου του χρήστη, το οποίο είναι ένα αμετάβλητο αναγνωριστικό για τον αιτούντα. Αυτή είναι η επαληθευμένη ταυτότητα του χρήστη ή της κύριας υπηρεσίας που χρησιμοποιείται για την κλήση αυτής της συνάρτησης σε όλες τις εφαρμογές.
Αναγνωριστικό μισθωτή	συμβολοσειρά (GUID)	Το αναγνωριστικό του μισθωτή στον οποίο έχει συνδεθεί ο χρήστης.
PreferredUsername	συμβολοσειρά	Το προτιμώμενο όνομα χρήστη του χρήστη που κάνει την κλήση, όπως έχει οριστεί από τον χρήστη. Αυτή η τιμή είναι μεταλλαγμένη.

Για να access την παράμετρο UserDataFunctionContext, πρέπει να χρησιμοποιήσετε τον ακόλουθο διακοσμητή στο επάνω μέρος του ορισμού της συνάρτησης: @udf.context(argName="<parameter name>")

Παράδειγμα

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

Εμφάνιση σφάλματος χειρισμού με `UserThrownError`

Κατά την ανάπτυξη της συνάρτησής σας, μπορείτε να ρίξετε μια αναμενόμενη απόκριση σφάλματος χρησιμοποιώντας την UserThrownError κλάση που είναι διαθέσιμη στο SDK. Μια χρήση αυτής της κλάσης είναι η διαχείριση περιπτώσεων όπου οι είσοδοι που παρέχονται από τον χρήστη αποτυγχάνουν να περάσουν τους κανόνες επικύρωσης επιχείρησης.

Παράδειγμα

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 κατασκευαστής κλάσης λαμβάνει δύο παραμέτρους:

Message: Αυτή η συμβολοσειρά επιστρέφεται ως μήνυμα σφάλματος στην εφαρμογή που καλεί αυτήν τη συνάρτηση.
Ένα λεξικό ιδιοτήτων επιστρέφεται στην εφαρμογή που καλεί αυτήν τη συνάρτηση.

Λήψη μεταβλητών από βιβλιοθήκες μεταβλητών Fabric

Μια βιβλιοθήκη μεταβλητών Fabric στο Microsoft Fabric είναι ένα κεντρικό αποθετήριο για τη διαχείριση μεταβλητών που μπορούν να χρησιμοποιηθούν σε διαφορετικά στοιχεία μέσα σε έναν χώρο εργασίας. Επιτρέπει στους προγραμματιστές να προσαρμόζουν και να μοιράζονται αποτελεσματικά τις διαμορφώσεις στοιχείων. Εάν δεν έχετε ακόμα βιβλιοθήκη μεταβλητών, ανατρέξτε στο θέμα Δημιουργία και διαχείριση βιβλιοθηκών μεταβλητών.

Για να χρησιμοποιήσετε μια βιβλιοθήκη μεταβλητών στις συναρτήσεις σας, προσθέστε μια σύνδεση σε αυτήν από το στοιχείο συναρτήσεων δεδομένων χρήστη. Οι βιβλιοθήκες μεταβλητών εμφανίζονται στον κατάλογο OneLake μαζί με προελεύσεις δεδομένων όπως βάσεις δεδομένων SQL και lakehouses.

Ακολουθήστε αυτά τα βήματα για να χρησιμοποιήσετε βιβλιοθήκες μεταβλητών στις συναρτήσεις σας:

Στο στοιχείο συναρτήσεων δεδομένων χρήστη, προσθέστε μια σύνδεση στη βιβλιοθήκη μεταβλητών σας. Στον κατάλογο OneLake, βρείτε και επιλέξτε τη βιβλιοθήκη μεταβλητών σας και, στη συνέχεια, επιλέξτε Σύνδεση. Σημειώστε το ψευδώνυμο που δημιουργεί το Fabric για τη σύνδεση.
Προσθέστε έναν διακοσμητή σύνδεσης για το στοιχείο βιβλιοθήκης μεταβλητής. Για παράδειγμα, @udf.connection(argName="varLib", alias="<My Variable Library Alias>") και αντικαταστήστε το ψευδώνυμο στη σύνδεση που προστέθηκε πρόσφατα για το στοιχείο βιβλιοθήκης μεταβλητής.
Στον ορισμό της συνάρτησης, συμπεριλάβετε ένα όρισμα με τύπο fn.FabricVariablesClient. Αυτός ο πελάτης παρέχει μεθόδους που χρειάζεστε για να εργαστείτε με το στοιχείο βιβλιοθήκης μεταβλητών.
Χρησιμοποιήστε getVariables() τη μέθοδο για να λάβετε όλες τις μεταβλητές από τη βιβλιοθήκη μεταβλητών.
Για να διαβάσετε τις τιμές των μεταβλητών χρησιμοποιήστε, είτε ["variable-name"].get("variable-name")είτε .

Παράδειγμα

Σε αυτό το παράδειγμα προσομοιώνουμε ένα σενάριο διαμόρφωσης για ένα περιβάλλον παραγωγής και ανάπτυξης. Αυτή η συνάρτηση ορίζει μια διαδρομή storage ανάλογα με το επιλεγμένο περιβάλλον χρησιμοποιώντας μια τιμή που ανακτάται από τη Βιβλιοθήκη μεταβλητών. Η βιβλιοθήκη μεταβλητών περιέχει μια μεταβλητή που ονομάζεται ENV όπου οι χρήστες μπορούν να ορίσουν μια τιμή dev ή 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"

Σχόλια

Ήταν χρήσιμη αυτή η σελίδα;

Last updated on 2026-01-22

Επισκόπηση μοντέλου προγραμματισμού συναρτήσεων δεδομένων χρήστη Fabric

Ξεκινώντας με το SDK

Συναρτήσεις δεδομένων χρήστη SDK

Απαιτούμενες εισαγωγές και προετοιμασία

Ο @udf.function() διακοσμητής

Βοηθητικές λειτουργίες

Υποστηριζόμενοι τύποι εισόδου

Υποστηριζόμενοι τύποι εξόδου

Σύνταξη συναρτήσεων

Απαιτήσεις και περιορισμοί σύνταξης

Ονομασία παραμέτρων

Απαιτήσεις παραμέτρων

Απαιτήσεις λειτουργίας

Παράδειγμα σωστής σύνταξης

Πώς να γράψετε μια ασύγχρονη συνάρτηση

Εργασία με δεδομένα

Συνδέσεις δεδομένων σε προελεύσεις δεδομένων Fabric

Παράδειγμα

Γενικές συνδέσεις για στοιχεία Fabric ή πόρους Azure

Σύνδεση σε κοντέινερ Fabric Cosmos DB με χρήση γενικής σύνδεσης

Σύνδεση στο Azure Key Vault με χρήση γενικής σύνδεσης

Δυνατότητες για προχωρημένους

Λήψη ιδιοτήτων κλήσης με χρήση UserDataFunctionContext

Εμφάνιση σφάλματος χειρισμού με UserThrownError

Λήψη μεταβλητών από βιβλιοθήκες μεταβλητών Fabric

Παράδειγμα

Σχετικό περιεχόμενο

Σχόλια

Πρόσθετοι πόροι

Λήψη ιδιοτήτων κλήσης με χρήση `UserDataFunctionContext`

Εμφάνιση σφάλματος χειρισμού με `UserThrownError`