Nástroje pro User Data Function (UDF) NotebookUtils v systému Fabric

Modul notebookutils.udf poskytuje nástroje pro integraci kódu poznámkového bloku s položkami funkce uživatelská data (UDF). K funkcím můžete přistupovat z položky UDF ve stejném pracovním prostoru nebo v různých pracovních prostorech a podle potřeby tyto funkce vyvolat. UDF položky podporují opakovaně použitelné kódy, centralizovanou údržbu a týmové spolupráci.

Použijte UDF nástroje k:

  • Načtení funkce – Přístup k funkcím z položek UDF podle názvu
  • Přístup mezi pracovními prostory – Používejte funkce z položek UDF v jiných pracovních prostorech.
  • Zjišťování funkcí – Kontrola dostupných funkcí a jejich podpisů
  • Flexibilní vyvolání – Volání funkcí s odpovídajícími parametry jazyka

Poznámka:

K načtení jeho funkcí potřebujete přístup pro čtení k položce definované uživatelem v cílovém pracovním prostoru. Výjimky z funkcí definované uživatelem se šíří do volajícího poznámkového bloku.

V následující tabulce jsou dostupné metody UDF:

Metoda Signature Description
getFunctions getFunctions(udf: String, workspaceId: String = ""): UDF Načte všechny funkce z položky UDF podle ID nebo názvu artefaktu. Vrátí objekt s atributy volatelné funkce.

Vrácený objekt zveřejňuje následující vlastnosti:

Vlastnictví Typ Description
functionDetails List Seznam slovníků metadat funkcí Každý slovník zahrnuje: Name (název funkce), Description (popis funkce), Parameters (seznam definic parametrů), FunctionReturnType (návratový typ) a DataSourceConnections (použitá připojení ke zdroji dat).
itemDetails Slovník Slovník metadat položek UDF s klíči: Id (ID artefaktu), Name (název položky), WorkspaceId (ID pracovního prostoru) a CapacityId (ID kapacity).
<functionName> Callable Každá funkce v položce UDF se stane volatelnou metodou pro vrácený objekt. Použijte myFunctions.functionName(...) k vyvolání.

Návod

Načtení funkcí UDF jednou a uložení objektu obálky do mezipaměti. Vyhněte se opakovanému volání getFunctions() ve smyčce – místo toho do mezipaměti zapamujte výsledek, abyste minimalizovali režijní náklady.

Načtení funkcí z UDF

Slouží notebookutils.udf.getFunctions() k získání všech funkcí z položky UDF. Volitelně můžete zadat ID pracovního prostoru pro přístup mezi pracovními prostory.

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

Vyvolat funkci

Po načtení funkcí z položky UDF je zavolejte podle názvu. Python podporuje poziční a pojmenované parametry. Příklady Scala a R používají poziční parametry.

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

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

Výchozí hodnoty parametrů

Fabric funkce uživatelských dat podporují výchozí hodnoty argumentů. Když vyvoláte funkce načtené prostřednictvím notebookutils.udf.getFunctions, všechny parametry, které mají definované výchozí nastavení, je možné vynechat – modul runtime použije výchozí hodnotu automaticky. Můžete také zadat pojmenované argumenty pro přepsání konkrétních výchozích hodnot a zároveň ponechat ostatní výchozí hodnoty.

# 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é výchozí typy vstupu

Jako výchozí hodnoty parametrů se podporují následující typy:

Výchozí typ Notes
String Libovolný řetězec json serializovatelný.
Řetězec datetime Zadejte jako řetězec v podpisu funkce. Modul runtime ho analyzuje při datetime vyvolání. Použijte konzistentní formát, například ISO 8601 (například 2025-12-31T23:59:59Z).
logický True nebo False.
Integer Libovolná celočíselná hodnota.
Float Libovolná hodnota s plovoucí desetinou čárkou.
List Musí být serializovatelný ve formátu JSON; preferujte None v podpisu a přiřaďte uvnitř funkce, aby se předešlo problémům s proměnlivými výchozími hodnotami.
Slovník Musí být serializovatelný JSON; upřednostněte None v podpisu a přiřaďte ho uvnitř funkce.
pandas DataFrame Poskytuje se jako objekt JSON, který sada SDK převede na typ pandas. Vyžaduje fabric-user-data-functions verzi 1.0.0 nebo novější.
Pandas Series Poskytuje se jako pole JSON objektů, které sada SDK převede na typ pandas. Vyžaduje fabric-user-data-functions verzi 1.0.0 nebo novější.

Omezení a pokyny

Výchozí hodnoty musí být serializovatelné ve formátu JSON (množiny a n-tice se nepodporují). Pro výchozí hodnoty seznamu nebo slovníku použijte None v podpisu a přiřaďte skutečné výchozí nastavení uvnitř funkce, abyste se vyhnuli sdíleným proměnlivým výchozím nastavením. Pro výchozí hodnoty data a času použijte formát ISO 8601 (například 2025-12-31T23:59:59Z). Použití datového rámce pandas nebo řady jako výchozí verze vyžaduje fabric-user-data-functions verzi 1.0.0 nebo novější.

Zobrazit podrobnosti

Metadata položek UDF a podpisy funkcí UDF můžete kontrolovat programově.

Zobrazit detaily položky UDF

display(myFunctions.itemDetails)

Zobrazení podrobností funkce

display(myFunctions.functionDetails)

Návod

Při práci s novou položkou UDF vždy zkontrolujte functionDetails. To vám pomůže před vyvoláním ověřit dostupné funkce a jejich očekávané typy parametrů.

Zpracování chyb

Obalte uživatelsky definované funkce ve zpracování chyb vhodném pro daný jazyk pro správu chybějících funkcí nebo neočekávaných typů parametrů elegantně. Před voláním funkce vždy ověřte, že existuje v položce uživatelsky definované funkce (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}")

Použití funkcí UDF v datovém kanálu

Můžete vytvářet funkce UDF pro sestavení opakovaně použitelných kroků 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")

Důležité

Volání uživatelských funkcí mají režijní náklady. Pokud voláte stejnou funkci se stejnými parametry opakovaně, zvažte uložení výsledku do mezipaměti. Pokud je to možné, vyhněte se volání funkcí UDF v těsných smyčkách.

Související obsah

  • Last updated on