NotebookUtils User Data Function (UDF) værktøjer til Fabric

Modulet notebookutils.udf tilbyder værktøjer til integration af notesbogskode med User Data Function (UDF)-elementer. Du kan tilgå funktioner fra et UDF-element inden for samme arbejdsområde eller på tværs af forskellige arbejdsområder og derefter aktivere disse funktioner efter behov. UDF-elementer fremmer genanvendelighed af koden, centraliseret vedligeholdelse og samarbejde i teamet.

Brug UDF-værktøjer til at:

  • Funktionshentning – Adgang til funktioner fra UDF-elementer efter navn.
  • Adgang på tværs af arbejdsområder – Brug funktioner fra UDF-elementer i andre arbejdsområder.
  • Funktionsopdagelse – Inspicer tilgængelige funktioner og deres signaturer.
  • Fleksibel invocation – Kald funktioner med sprog-passende parametre.

Bemærkning

Du har brug for læseadgang til et UDF-element i målarbejdsområdet for at hente dets funktioner. Undtagelser fra UDF-funktioner forplanter sig til den kaldende notesbog.

Følgende tabel viser de tilgængelige UDF-metoder:

Metode Signatur Beskrivelse
getFunctions getFunctions(udf: String, workspaceId: String = ""): UDF Henter alle funktioner fra et UDF-element via artefakt-ID eller navn. Returnerer et objekt med kaldbare funktionsattributter.

Det returnerede objekt eksponerer følgende egenskaber:

Property Type Beskrivelse
functionDetails Liste En liste over funktionsmetadata-ordbøger. Hver ordbog inkluderer: Name (funktionsnavn), Description (funktionsbeskrivelse), Parameters (liste over parameterdefinitioner), FunctionReturnType (returtype) og DataSourceConnections (anvendte datakildeforbindelser).
itemDetails Ordbog En ordbog over UDF-objektmetadata med nøgler: Id (artefakt-ID), Name (elementnavn), WorkspaceId (arbejdsområde-ID) og CapacityId (kapacitets-ID).
<functionName> Callable Hver funktion i UDF-elementet bliver en kaldbar metode på det returnerede objekt. Brug myFunctions.functionName(...) til at invokere.

Tips

Hent UDF-funktioner én gang og cache wrapper-objektet. Undgå at kalde gentagne gange getFunctions() i en løkke – cache resultatet i stedet for at minimere overhead.

Hent funktioner fra en UDF

Brug notebookutils.udf.getFunctions() den til at få alle funktioner fra et UDF-element. Du kan valgfrit angive et arbejdsområde-ID til adgang på tværs af arbejdsområder.

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

Aktivér en funktion

Efter at have hentet funktioner fra et UDF-element, kald dem ved navn. Python understøtter positions- og navngivne parametre. Scala- og R-eksempler bruger positionsparametre.

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

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

Standardparametreværdier

Fabric-brugerdatafunktioner understøtter standardargumentværdier. Når du kalder funktioner, der hentes via notebookutils.udf.getFunctions, kan enhver parameter med defineret standard udelades—runtimen bruger automatisk standarden. Du kan også levere navngivne argumenter for at tilsidesætte specifikke standardværdier, mens du lader andre have deres standardindstillinger.

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

Understøttede standard inputtyper

Følgende typer understøttes som standardparametre:

Standardtype Notes
String Enhver JSON-serialiserbar streng.
Dato-tid-streng Angiv som en streng i funktionssignaturen. Runtime-versionen parser det til datetime ved invocation-tidspunktet. Brug et ensartet format som ISO 8601 (for eksempel, 2025-12-31T23:59:59Z).
Boolean True eller False.
Integer Enhver heltalsværdi.
Float Enhver flydende kommatal-værdi.
Liste Skal være JSON-serialiserbar; foretræk None i signaturen og tildel inde i funktionen for at undgå foranderlige standardfaldgruber.
Ordbog Skal være JSON-serialiserbar; foretræk None i signaturen og tildel inden for funktionen.
pandaer DataFrame Leveres som et JSON-objekt, som SDK'en konverterer til en pandas-type. Kræver fabric-user-data-functions version 1.0.0 eller nyere.
pandas-serien Leveres som et JSON-array af objekter, som SDK'en konverterer til en pandas-type. Kræver fabric-user-data-functions version 1.0.0 eller nyere.

Begrænsninger og vejledning

Standardindstillinger skal være JSON-serialiserbare (sæt og tupler understøttes ikke). For liste- eller ordbogsdefaults, brug None i signaturen og tildel den rigtige standard inde i funktionen for at undgå delte foranderlige defaults. Brug ISO 8601-formatet (for eksempel, 2025-12-31T23:59:59Z) til standardindstillinger for datotid. At bruge pandas DataFrame eller Series som standard kræver fabric-user-data-functions version 1.0.0 eller nyere.

Displaydetaljer

Du kan inspicere UDF-objektmetadata og funktionssignaturer programmatisk.

Vis UDF-elementdetaljer

display(myFunctions.itemDetails)

Detaljer om visningsfunktion

display(myFunctions.functionDetails)

Tips

Inspicer functionDetails altid, når du arbejder med et nyt UDF-produkt. Dette hjælper dig med at verificere tilgængelige funktioner og deres forventede parametertyper før påkaldelse.

Fejlhåndtering

Indpak UDF-kald i sprogtilpasset fejlhåndtering for at håndtere manglende funktioner eller uventede parametertyper elegant. Verificér altid, at der findes en funktion i UDF-elementet, før du kalder det.

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

Brug UDF-funktioner i en datapipeline

Du kan sammensætte UDF-funktioner for at bygge genanvendelige ETL-trin:

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

Vigtigt!

UDF-påkaldelser har overhead. Hvis du kalder den samme funktion med de samme parametre gentagne gange, så overvej at cache resultatet. Undgå at kalde UDF-funktioner i stramme løkker, når det er muligt.

Relateret indhold

  • Last updated on