NotebookUtils User Data Function (UDF)-verktøy for Fabric

Modulen notebookutils.udf tilbyr verktøy for å integrere notatbokkode med User Data Function (UDF)-elementer. Du kan få tilgang til funksjoner fra et UDF-element innenfor samme arbeidsområde eller på tvers av forskjellige arbeidsområder, og deretter kalle disse funksjonene etter behov. UDF-elementer fremmer gjenbruk av kode, sentralisert vedlikehold og teamsamarbeid.

Bruk UDF-verktøy til å:

  • Funksjonshenting – Få tilgang til funksjoner fra UDF-elementer med navn.
  • Tilgang på tvers av arbeidsområder – Bruk funksjoner fra UDF-elementer i andre arbeidsområder.
  • Funksjonsoppdagelse – Inspiser tilgjengelige funksjoner og deres signaturer.
  • Fleksibel invokasjon – Kalle funksjoner med språk-passende parametere.

Bemerkning

Du trenger lesetilgang til et UDF-element i målarbeidsområdet for å hente funksjonene deres. Unntak fra UDF-funksjoner overføres til den kallende notatboken.

Tabellen nedenfor viser tilgjengelige UDF-metoder:

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

Det returnerte objektet eksponerer følgende egenskaper:

Eiendom Type Beskrivelse
functionDetails Liste En liste over funksjonsmetadata-ordbøker. Hver ordbok inkluderer: Name (funksjonsnavn), Description (funksjonsbeskrivelse), Parameters (liste over parameterdefinisjoner), FunctionReturnType (returtype), og DataSourceConnections (brukte datakildeforbindelser).
itemDetails Ordbok En ordbok over UDF-elementmetadata med nøkler: Id (artefakt-ID), Name (elementnavn), WorkspaceId (arbeidsområde-ID) og CapacityId (kapasitets-ID).
<functionName> Callable Hver funksjon i UDF-elementet blir en kallbar metode på det returnerte objektet. Bruk myFunctions.functionName(...) for å påkalle.

Tips

Hente UDF-funksjoner én gang og cache wrapper-objektet. Unngå å kalle getFunctions() gjentatte ganger i en løkke – cache resultatet i stedet for å minimere overhead.

Hente funksjoner fra en UDF

Bruk notebookutils.udf.getFunctions() for å hente alle funksjoner fra et UDF-element. Du kan valgfritt spesifisere en arbeidsområde-ID for tilgang på tvers av arbeidsområ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')

Aktiver en funksjon

Etter å ha hentet funksjoner fra et UDF-element, kall dem ved navn. Python støtter posisjonelle og navngitte parametere. Scala- og R-eksempler bruker posisjonelle parametere.

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

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

Standard parameterverdier

Fabric-brukerdatafunksjoner støtter standard argumentverdier. Når du kaller funksjoner hentet via notebookutils.udf.getFunctions, kan enhver parameter som har en definert standard utelates—kjøretiden bruker automatisk standarden. Du kan også tilby navngitte argumenter for å overstyre spesifikke standardinnstillinger mens du lar andre stå på sine standardinnstillinger.

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

Støttede standard inndatatyper

Følgende typer støttes som standard parameterverdier:

Standardtype Notes
string Enhver JSON-serialiserbar streng.
Dato-tid-streng Spesifiser som en streng i funksjonssignaturen. Kjøretiden parser det til datetime ved invokasjon. Bruk et konsistent format som ISO 8601 (for eksempel 2025-12-31T23:59:59Z).
boolsk True eller False.
Integer Enhver heltallsverdi.
Flyttall Enhver flyttallsverdi.
Liste Må være JSON-serialiserbar; foretrekk None i signaturen og tilordne inne i funksjonen for å unngå foranderlige standardfallgruver.
Ordbok Må være JSON-serialiserbar; foretrekk None i signaturen og tilordne inne i funksjonen.
pandaer DataFrame Levert som et JSON-objekt som SDK-en konverterer til en pandas-type. Krever fabric-user-data-functions versjon 1.0.0 eller nyere.
pandas-serien Leveres som et JSON-array av objekter som SDK-en konverterer til en pandas-type. Krever fabric-user-data-functions versjon 1.0.0 eller nyere.

Begrensninger og veiledning

Standardinnstillinger må være JSON-serialiserbare (sett og tupler støttes ikke). For liste- eller ordbokstandardinnstillinger, bruk None i signaturen og tildel den reelle standarden inne i funksjonen for å unngå delte, foranderlige standardinnstillinger. Bruk ISO 8601-formatet (for eksempel, 2025-12-31T23:59:59Z) for dato-tid-standardinnstillinger. Å bruke pandas DataFrame eller Series som standard krever fabric-user-data-functions versjon 1.0.0 eller nyere.

Utstillingsdetaljer

Du kan inspisere UDF-objektmetadata og funksjonssignaturer programmatisk.

Vis detaljer om UDF-elementer

display(myFunctions.itemDetails)

Detaljer om visningsfunksjon

display(myFunctions.functionDetails)

Tips

Inspekter functionDetails alltid når du jobber med et nytt UDF-produkt. Dette hjelper deg å verifisere tilgjengelige funksjoner og deres forventede parametertyper før du kaller.

Feilbehandling

Pakk inn UDF-kall i språktilpasset feilhåndtering for å håndtere manglende funksjoner eller uventede parametertyper på en elegant måte. Verifiser alltid at det finnes en funksjon i UDF-elementet før du kaller 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}")

Bruk UDF-funksjoner i en datapipeline

Du kan komponere UDF-funksjoner for å bygge gjenbrukbare ETL-steg:

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

Viktig!

UDF-påkallelser har overhead. Hvis du kaller den samme funksjonen med de samme parameterne gjentatte ganger, vurder å cache resultatet. Unngå å kalle UDF-funksjoner i tette løkker når det er mulig.

Relatert innhold

  • Last updated on