NotebookUtils UDF-verktyg (User Data Function) för Fabric

Modulen notebookutils.udf innehåller verktyg för att integrera notebook-kod med UDF-objekt (User Data Function). Du kan komma åt funktioner från ett UDF-objekt på samma arbetsyta eller mellan olika arbetsytor och sedan anropa dessa funktioner efter behov. UDF-objekt främjar återanvändning av kod, centraliserat underhåll och teamsamarbete.

Använd UDF-verktyg för att:

  • Funktionshämtning – Åtkomstfunktioner från UDF-objekt efter namn.
  • Åtkomst mellan arbetsytor – Använd funktioner från UDF-objekt på andra arbetsytor.
  • Funktionsidentifiering – Granska tillgängliga funktioner och deras signaturer.
  • Flexibel anrop – Anropa funktioner med språkanpassade parametrar.

Anmärkning

Du behöver läsbehörighet till ett UDF-objekt på målarbetsytan för att hämta dess funktioner. Undantag från UDF-funktioner sprids till den anropande notebook-filen.

I följande tabell visas de tillgängliga UDF-metoderna:

Metod Signature Beskrivning
getFunctions getFunctions(udf: String, workspaceId: String = ""): UDF Hämtar alla funktioner från ett UDF-objekt med artefakt-ID eller namn. Returnerar ett objekt med anropsbara funktionsattribut.

Det returnerade objektet visar följande egenskaper:

Fastighet Type Beskrivning
functionDetails List En lista över ordlistor för funktionsmetadata. Varje ordlista innehåller: Name (funktionsnamn), Description (funktionsbeskrivning), Parameters (lista över parameterdefinitioner), FunctionReturnType (returtyp) och DataSourceConnections (datakällanslutningar används).
itemDetails Ordbok En ordlista med UDF-objektmetadata med nycklar: Id (artefakt-ID), Name (objektnamn), WorkspaceId (arbetsyte-ID) och CapacityId (kapacitets-ID).
<functionName> Callable Varje funktion i UDF-objektet blir en anropsbar metod för det returnerade objektet. Använd myFunctions.functionName(...) för att anropa.

Tips/Råd

Hämta UDF-funktioner en gång och cachelagra omslutningsobjektet. Undvik att anropa getFunctions() upprepade gånger i en slinga – lagra istället resultatet i cachen för att minimera omkostnaderna.

Hämta funktioner från en UDF

Använd notebookutils.udf.getFunctions() för att hämta alla funktioner från ett UDF-objekt. Du kan också ange ett arbetsyte-ID för åtkomst mellan arbetsytor.

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

Anropa en funktion

När du har hämtat funktioner från ett UDF-objekt anropar du dem med namn. Python stöder positionella och namngivna parametrar. Scala- och R-exempel använder positionsparametrar.

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

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

Standardparametervärden

Fabric användardatafunktioner stöder standardargumentvärden. När du anropar funktioner som hämtats via notebookutils.udf.getFunctionskan alla parametrar som har en definierad standard utelämnas – körningen använder standardvärdet automatiskt. Du kan också ange namngivna argument för att åsidosätta specifika standardvärden samt lämna andra oförändrade.

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

Standardindatatyper som stöds

Följande typer stöds som standardparametervärden:

Standardtyp Notes
String Alla JSON-serialiserbara strängar.
Datetime-sträng Ange som en sträng i funktionssignaturen. Körningen parsar den till datetime vid anrop. Använd ett konsekvent format som ISO 8601 (till exempel 2025-12-31T23:59:59Z).
Boolean True eller False.
Integer Alla heltalsvärden.
Flyta Alla flyttalsvärden.
List Måste vara JSON-serierbar; None föredras i signaturen och tilldelas inuti funktionen för att undvika fallgropar med föränderliga standardvärden.
Ordbok Måste vara JSON-serieliserbar; föredra None i signaturen och tilldela inuti funktionen.
Pandas DataFrame Tillhandahålls som ett JSON-objekt som SDK:t konverterar till en Pandas-typ. Kräver fabric-user-data-functions version 1.0.0 eller senare.
Pandas-serien Tillhandahålls som en JSON-matris med objekt som SDK:t konverterar till en Pandas-typ. Kräver fabric-user-data-functions version 1.0.0 eller senare.

Begränsningar och vägledning

Standardvärdena måste vara JSON-serialiserbara (uppsättningar och tupplar stöds inte). För list- eller ordlistestandarder använder du None i signaturen och tilldelar den verkliga standardinställningen i funktionen för att undvika delade, föränderliga standardvärden. Använd ISO 8601-format (till exempel 2025-12-31T23:59:59Z) för datetime-standardvärden. Användning av Pandas DataFrame eller Serie som standard kräver fabric-user-data-functions version 1.0.0 eller senare.

Visa detaljer

Du kan granska UDF-objektmetadata och funktionssignaturer programmatiskt.

Visa detaljer om UDF-objekt

display(myFunctions.itemDetails)

Visa funktionsinformation

display(myFunctions.functionDetails)

Tips/Råd

Inspektera functionDetails alltid när du arbetar med ett nytt UDF-objekt. Detta hjälper dig att verifiera tillgängliga funktioner och deras förväntade parametertyper före anrop.

Felhantering

Omslut UDF-anrop i språkanpassad felhantering för att hantera saknade funktioner eller oväntade parametertyper på ett korrekt sätt. Kontrollera alltid att det finns en funktion i UDF-objektet innan du anropar den.

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

Använda UDF-funktioner i en datapipeline

Du kan skapa UDF-funktioner för att skapa återanvändbara 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")

Viktigt!

UDF-anrop har omkostnader. Om du anropar samma funktion med samma parametrar upprepade gånger bör du överväga att cachelagra resultatet. Undvik att anropa UDF-funktioner i snäva loopar när det är möjligt.

Relaterat innehåll

  • Last updated on