Βοηθητικά προγράμματα NotebookUtils User Data Function (UDF) για το Fabric

Η notebookutils.udf ενότητα παρέχει βοηθητικά προγράμματα για την ενσωμάτωση κώδικα σημειωματάριου με στοιχεία λειτουργίας δεδομένων χρήστη (UDF). Μπορείτε να αποκτήσετε πρόσβαση σε συναρτήσεις από ένα στοιχείο UDF στον ίδιο χώρο εργασίας ή σε διαφορετικούς χώρους εργασίας και, στη συνέχεια, να καλέσετε αυτές τις συναρτήσεις όπως απαιτείται. Τα στοιχεία UDF προωθούν την επαναχρησιμοποίηση κώδικα, την κεντρική συντήρηση και τη συνεργασία της ομάδας.

Χρησιμοποιήστε βοηθητικά προγράμματα UDF για:

  • Ανάκτηση συναρτήσεων – Πρόσβαση σε συναρτήσεις από στοιχεία UDF με βάση το όνομα.
  • Πρόσβαση μεταξύ χώρων εργασίας – Χρησιμοποιήστε συναρτήσεις από στοιχεία UDF σε άλλους χώρους εργασίας.
  • Εντοπισμός συναρτήσεων – Επιθεωρήστε τις διαθέσιμες συναρτήσεις και τις υπογραφές τους.
  • Ευέλικτη κλήση – Λειτουργίες κλήσης με παραμέτρους κατάλληλες για τη γλώσσα.

Σημείωμα

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

Ο παρακάτω πίνακας παραθέτει τις διαθέσιμες μεθόδους UDF:

Μέθοδος Υπογραφή Περιγραφή
getFunctions getFunctions(udf: String, workspaceId: String = ""): UDF Ανακτά όλες τις συναρτήσεις από ένα στοιχείο UDF κατά αναγνωριστικό τεχνουργήματος ή όνομα. Επιστρέφει ένα αντικείμενο με χαρακτηριστικά συνάρτησης με δυνατότητα κλήσης.

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

Ιδιοκτησία Τύπος Περιγραφή
functionDetails Λίστα Μια λίστα λεξικών μεταδεδομένων συναρτήσεων. Κάθε λεξικό περιλαμβάνει: Name (όνομα συνάρτησης), Description (περιγραφή συνάρτησης), Parameters (λίστα ορισμών παραμέτρων), FunctionReturnType (τύπος επιστροφής) και DataSourceConnections (χρησιμοποιούμενες συνδέσεις προέλευσης δεδομένων).
itemDetails Λεξικό Ένα λεξικό μετα-δεδομένων στοιχείων UDF με κλειδιά: Id (αναγνωριστικό αντικειμένου), Name (όνομα στοιχείου), WorkspaceId (αναγνωριστικό χώρου εργασίας) και CapacityId (αναγνωριστικό χωρητικότητας).
<functionName> Με δυνατότητα κλήσης Κάθε συνάρτηση στο στοιχείο UDF γίνεται μια μέθοδος με δυνατότητα κλήσης στο επιστρεφόμενο αντικείμενο. Χρησιμοποιήστε το myFunctions.functionName(...) για να καλέσετε.

Συμβουλή

Ανακτήστε τις συναρτήσεις UDF μία φορά και αποθηκεύστε προσωρινά το αντικείμενο περιτυλίγματος. Αποφύγετε τις επανειλημμένες κλήσεις getFunctions() σε βρόχο—αποθηκεύστε το αποτέλεσμα στην προσωρινή μνήμη για να ελαχιστοποιήσετε την επιβάρυνση.

Ανάκτηση συναρτήσεων από UDF

Χρησιμοποιείται notebookutils.udf.getFunctions() για τη λήψη όλων των συναρτήσεων από ένα στοιχείο UDF. Μπορείτε προαιρετικά να καθορίσετε ένα αναγνωριστικό χώρου εργασίας για πρόσβαση μεταξύ χώρων εργασίας.

# Get functions from a UDF item in the current workspace
myFunctions = notebookutils.udf.getFunctions('UDFItemName')

# Get functions from a UDF item in another workspace
myFunctions = notebookutils.udf.getFunctions('UDFItemName', 'workspaceId')

Κλήση συνάρτησης

Μετά την ανάκτηση συναρτήσεων από ένα στοιχείο UDF, καλέστε τις με το όνομά τους. Η Python υποστηρίζει παραμέτρους θέσης και ονόματα. Τα παραδείγματα Scala και R χρησιμοποιούν παραμέτρους θέσης.

# Positional parameters
myFunctions.functionName('value1', 'value2')

# Named parameters (recommended for clarity)
myFunctions.functionName(parameter1='value1', parameter2='value2')

Προεπιλεγμένες τιμές παραμέτρων

Οι συναρτήσεις δεδομένων χρήστη Fabric υποστηρίζουν προεπιλεγμένες τιμές ορισμάτων. Όταν καλείτε συναρτήσεις που ανακτώνται μέσω notebookutils.udf.getFunctions, οποιαδήποτε παράμετρος που έχει καθορισμένη προεπιλογή μπορεί να παραλειφθεί—ο χρόνος εκτέλεσης χρησιμοποιεί αυτόματα την προεπιλογή. Μπορείτε επίσης να δώσετε επώνυμα ορίσματα για να παρακάμψετε συγκεκριμένες προεπιλογές, αφήνοντας άλλα στις προεπιλογές τους.

# Assume the UDF item defines a function like:
# def score_customer(customerId: str, startDate: datetime = "2025-01-01T00:00:00Z", isActive: bool = True, maxRecords: int = 100) -> dict
# The datetime defaults are specified as strings in the signature; the runtime parses them to datetime at invocation time.

# 1. Call without optional parameters — defaults are used for startDate, isActive, and maxRecords
result = myFunctions.scoreCustomer(customerId='C001')

# 2. Override one default via a named argument, keep the others at their defaults
result = myFunctions.scoreCustomer(customerId='C001', maxRecords=50)

# 3. Pass a date/time in ISO 8601 format for reliable parsing
result = myFunctions.scoreCustomer(customerId='C001', startDate='2025-12-31T23:59:59Z')

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

Οι ακόλουθοι τύποι υποστηρίζονται ως προεπιλεγμένες τιμές παραμέτρων:

Προεπιλεγμένος τύπος 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 ή νεότερη.

Περιορισμοί και καθοδήγηση

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

Εμφάνιση λεπτομερειών

Μπορείτε να επιθεωρήσετε τα μεταδεδομένα στοιχείων UDF και τις υπογραφές συναρτήσεων μέσω προγραμματισμού.

Εμφάνιση λεπτομερειών στοιχείου UDF

display(myFunctions.itemDetails)

Εμφάνιση λεπτομερειών λειτουργίας

display(myFunctions.functionDetails)

Συμβουλή

Ελέγχετε functionDetails πάντα όταν εργάζεστε με ένα νέο στοιχείο UDF. Αυτό σας βοηθά να επαληθεύσετε τις διαθέσιμες συναρτήσεις και τους αναμενόμενους τύπους παραμέτρων τους πριν από την κλήση.

Χειρισμός σφαλμάτων

Τυλίξτε τις κλήσεις UDF σε χειρισμό σφαλμάτων κατάλληλο για τη γλώσσα για να διαχειριστείτε ομαλά τις λειτουργίες που λείπουν ή τους απροσδόκητους τύπους παραμέτρων. Επαληθεύετε πάντα ότι υπάρχει μια συνάρτηση στο στοιχείο UDF πριν την καλέσετε.

import json

try:
    validators = notebookutils.udf.getFunctions('DataValidators')

    # Check if function exists before calling
    functions_info = json.loads(validators.functionDetails)
    function_names = [f['Name'] for f in functions_info]

    if 'validateSchema' in function_names:
        is_valid = validators.validateSchema(
            schema='sales_schema',
            data_path='Files/data/sales.csv'
        )
        print(f"Schema validation: {'passed' if is_valid else 'failed'}")
    else:
        print("validateSchema function not available in this UDF item")
        print(f"Available functions: {', '.join(function_names)}")

except AttributeError as e:
    print(f"Function not found: {e}")
except TypeError as e:
    print(f"Parameter type mismatch: {e}")
except Exception as e:
    print(f"Error invoking UDF: {e}")

Χρήση συναρτήσεων UDF σε μια διοχέτευση δεδομένων

Μπορείτε να συνθέσετε συναρτήσεις UDF για να δημιουργήσετε επαναχρησιμοποιήσιμα βήματα ETL:

etl_functions = notebookutils.udf.getFunctions('ETLUtilities')

df = spark.read.csv('Files/raw/sales.csv', header=True)
cleaned_df = etl_functions.removeOutliers(df, columns=['amount'])
enriched_df = etl_functions.addCalculatedColumns(cleaned_df)
validated_df = etl_functions.validateAndFilter(enriched_df)

validated_df.write.mode('overwrite').parquet('Files/processed/sales.parquet')
print("ETL pipeline completed using UDF functions")

Σημαντικό

Οι επικλήσεις UDF έχουν γενικά έξοδα. Εάν καλείτε επανειλημμένα την ίδια συνάρτηση με τις ίδιες παραμέτρους, εξετάστε το ενδεχόμενο προσωρινής αποθήκευσης του αποτελέσματος. Αποφύγετε να καλείτε συναρτήσεις UDF σε στενούς βρόχους όταν είναι δυνατόν.

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

  • Last updated on