Nástroje NotebookUtils User Data Function (UDF) pre Fabric

Modul notebookutils.udf poskytuje nástroje na integráciu kódu zápisníka s položkami User Data Function (UDF). Funkciám môžete pristupovať z UDF položky v rámci toho istého pracovného priestoru alebo naprieč rôznymi pracovnými priestormi a potom tieto funkcie podľa potreby volať. Položky UDF podporujú znovupoužiteľnosť kódu, centralizovanú údržbu a tímovú spoluprácu.

Použite UDF nástroje na:

  • Vyhľadávanie funkcií – Prístup k funkciám z UDF položiek podľa názvu.
  • Prístup naprieč pracovnými priestormi – Používajte funkcie z UDF položiek v iných pracovných priestoroch.
  • Objavovanie funkcií – Skontrolujte dostupné funkcie a ich podpisy.
  • Flexibilné volanie – Volajte funkcie s parametrami vhodnými pre jazyk.

Poznámka

Na získanie jej funkcií potrebujete prístup k UDF položke v cieľovom pracovnom priestore. Výnimky z UDF funkcií sa šíria do volajúceho zápisníka.

Nasledujúca tabuľka uvádza dostupné metódy UDF:

Method Podpis Description
getFunctions getFunctions(udf: String, workspaceId: String = ""): UDF Získava všetky funkcie z UDF položky podľa ID artefaktu alebo názvu. Vráti objekt s volateľnými atribútmi funkcie.

Vrátený objekt odhaľuje nasledujúce vlastnosti:

Vlastnosť Typ Description
functionDetails Zoznam Zoznam slovníkov metadát funkcií. Každý slovník obsahuje: Name (názov funkcie), Description (popis funkcie), Parameters (zoznam definícií parametrov), FunctionReturnType (typ návratu) a DataSourceConnections (použité spojenia so zdrojom dát).
itemDetails Slovník Slovník metadát položiek UDF s kľúčmi: Id (artefaktový identifikátor), Name (názov položky), WorkspaceId (pracovný priestor) a CapacityId (kapacitný identifikátor).
<functionName> Volateľné Každá funkcia v položke UDF sa stáva volateľnou metódou na vrátenom objekte. Použiť myFunctions.functionName(...) na vyvolávanie.

Prepitné

Načítajte UDF funkcie raz a uložte obalový objekt do vyrovnávacej pamäte. Vyhnite sa opakovanému volaniu getFunctions() v slučke – výsledok ukladajte do vyrovnávacej pamäte, aby ste minimalizovali režijné náklady.

Načítanie funkcií z jazyka UDF

Použite notebookutils.udf.getFunctions() na získanie všetkých funkcií z UDF predmetu. Voliteľne môžete nastaviť ID pracovného priestoru pre prístup medzi pracovnými priestormi.

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

Vyvolanie funkcie

Po získaní funkcií z UDF položky ich volajte podľa mena. Python podporuje pozičné a pomenované parametre. Príklady Scala a R používajú polohové parametre.

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

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

Predvolené hodnoty parametrov

Fabric používateľské dátové funkcie podporujú predvolené hodnoty argumentov. Keď vyvoláte funkcie získané cez notebookutils.udf.getFunctions, každý parameter s definovaným predvoleným nastavením môže byť vynechaný – runtime automaticky používa predvolený. Môžete tiež dodať pomenované argumenty na prepísanie konkrétnych predvolených hodnôt a ponechať ostatné na ich predvolených hodnotách.

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

Podporované predvolené typy vstupov

Nasledujúce typy sú podporované ako predvolené hodnoty parametrov:

Predvolený typ Notes
Povrázok Akýkoľvek JSON-serializovateľný reťazec.
Reťazec dátumového času Špecifikujte ako reťazec v podpise funkcie. Runtime ho analyzuje na datetime čas vyvolávania. Použite konzistentný formát, napríklad ISO 8601 (napríklad 2025-12-31T23:59:59Z).
booleovský True alebo False.
Integer Akékoľvek celočíselné hodnoty.
Float Akúkoľvek hodnotu s pohyblivou desatinnou čiarkou.
Zoznam Musí byť JSON-serializovateľný; preferovať None v podpise a priradiť vo funkcii, aby sa predišlo mutovateľným predvoleným nástrahám.
Slovník Musí byť JSON-serializovateľný; preferovať None v podpise a priraďovať vo vnútri funkcie.
Dátový rámec pandas Poskytovaný ako JSON objekt, ktorý SDK konvertuje na typ pandas. Vyžaduje verziu fabric-user-data-functions 1.0.0 alebo novšiu.
séria pandas Poskytované ako JSON pole objektov, ktoré SDK konvertuje na typ pandas. Vyžaduje verziu fabric-user-data-functions 1.0.0 alebo novšiu.

Obmedzenia a usmernenia

Predvolené nastavenia musia byť JSON-serializovateľné (množiny a n-tice nie sú podporované). Pre zoznamové alebo slovníkové predvolené nastavenia použite None v podpise a priraďte skutočné predvolené vo funkcii, aby sa predišlo zdieľaným mutabilným predvoleným nastaveniam. Použite formát ISO 8601 (napríklad ) 2025-12-31T23:59:59Zpre predvolené nastavenia dátumového času. Použitie pandas DataFrame alebo Series ako predvoleného vyžaduje fabric-user-data-functions verziu 1.0.0 alebo novšiu.

Detaily výstavy

Môžete programovo kontrolovať metadáta položiek a podpisy funkcií v UDF.

Zobraziť detaily o položke UDF

display(myFunctions.itemDetails)

Detaily zobrazovacej funkcie

display(myFunctions.functionDetails)

Prepitné

Vždy kontrolujte functionDetails , keď pracujete s novým UDF predmetom. To vám pomáha overiť dostupné funkcie a ich očakávané typy parametrov pred vyvolaním.

Spracovanie chýb

Zabaliť UDF volania do jazykovo vhodného spracovania chýb, aby ste elegantne spravovali chýbajúce funkcie alebo neočakávané typy parametrov. Vždy si overte, že funkcia existuje v UDF položke predtým, než ju zavoláte.

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

Použitie UDF funkcií v dátovom potrubí

Môžete zostaviť UDF funkcie na vytvorenie opakovane použiteľných ETL krokov:

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

Dôležité

Invokácie UDF majú režijné náklady. Ak opakovane voláte tú istú funkciu s rovnakými parametrami, zvážte uloženie výsledku do vyrovnávacej pamäte. Vyhnite sa volaniu UDF funkcií v úzkych slučkách, ak je to možné.

Súvisiaci obsah

  • Last updated on