Utilidades de NotebookUtils para la función de datos de usuario (UDF) en Fabric

El notebookutils.udf módulo proporciona utilidades para integrar código de cuaderno con elementos de función de datos de usuario (UDF). Puede acceder a las funciones desde un elemento de UDF dentro del mismo área de trabajo o entre distintas áreas de trabajo y, a continuación, invocar esas funciones según sea necesario. Los elementos de UDF promueven la reutilización del código, el mantenimiento centralizado y la colaboración en equipo.

Use utilidades de UDF para:

  • Recuperación de funciones: Acceda a funciones de elementos UDF por nombre.
  • Acceso entre áreas de trabajo : use funciones de elementos UDF en otras áreas de trabajo.
  • Detección de funciones: inspeccione las funciones disponibles y sus firmas.
  • Invocación flexible – Llamar a funciones con parámetros adecuados para el lenguaje.

Nota:

Necesita acceso de lectura a un elemento de UDF en el área de trabajo de destino para recuperar sus funciones. Las excepciones de las funciones UDF se propagan al notebook que realiza la llamada.

En la tabla siguiente se enumeran los métodos UDF disponibles:

Método Signature Descripción
getFunctions getFunctions(udf: String, workspaceId: String = ""): UDF Recupera todas las funciones de un elemento de UDF por identificador de artefacto o nombre. Devuelve un objeto con atributos de función invocables.

El objeto devuelto expone las siguientes propiedades:

Propiedad Tipo Descripción
functionDetails List Lista de diccionarios de metadatos de función. Cada diccionario incluye: Name (nombre de función), Description (descripción de la función), Parameters (lista de definiciones de parámetros), FunctionReturnType (tipo de valor devuelto) y DataSourceConnections (conexiones de origen de datos usadas).
itemDetails Diccionario Diccionario de metadatos de elementos de UDF con claves: Id (id. de artefacto), Name (nombre del elemento), WorkspaceId (id. de área de trabajo) y CapacityId (id. de capacidad).
<functionName> Callable Cada función del elemento UDF se convierte en un método invocable en el objeto devuelto. Use myFunctions.functionName(...) para invocar.

Sugerencia

Recupere las funciones de UDF una vez y almacene en caché el objeto contenedor. Evite llamar getFunctions() repetidamente en un bucle: almacene en caché el resultado en su lugar para minimizar la sobrecarga.

Recuperación de funciones de una UDF

Use notebookutils.udf.getFunctions() para obtener todas las funciones de un elemento de UDF. Opcionalmente, puede especificar un identificador de área de trabajo para el acceso entre áreas de trabajo.

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

Invocar una función

Después de recuperar funciones de un elemento de UDF, llámalas por nombre. Python admite parámetros posicionales y con nombre. Los ejemplos de Scala y R usan parámetros posicionales.

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

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

Valores de parámetro predeterminados

Las funciones de datos de usuario de Fabric admiten valores de argumento predeterminados. Cuando se invocan funciones recuperadas a través notebookutils.udf.getFunctionsde , se puede omitir cualquier parámetro que tenga un valor predeterminado definido; el tiempo de ejecución usa el valor predeterminado automáticamente. También puede proporcionar argumentos con nombre para invalidar valores predeterminados específicos mientras deja a otros en sus valores predeterminados.

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

Tipos de entrada predeterminados admitidos

Los siguientes tipos se admiten como valores de parámetro predeterminados:

Tipo predeterminado Notes
String Cualquier cadena serializable en JSON.
Cadena de fecha y hora Especificar como una cadena en la firma de la función. El tiempo de ejecución lo analiza en datetime al momento de la invocación. Use un formato coherente como ISO 8601 (por ejemplo, 2025-12-31T23:59:59Z).
Boolean True o False.
Integer Cualquier valor entero.
Flotante Cualquier valor de punto flotante.
List Debe ser serializable JSON; prefiera None en la firma y asigne dentro de la función para evitar inconvenientes predeterminados mutables.
Diccionario Debe ser serializable en JSON. Se recomienda None en la firma y asignar dentro de la función.
DataFrame de Pandas Se proporciona como un objeto JSON que el SDK convierte en un tipo pandas. Requiere fabric-user-data-functions la versión 1.0.0 o posterior.
Serie pandas Se proporciona como una matriz JSON de objetos que el SDK convierte en un tipo pandas. Requiere fabric-user-data-functions la versión 1.0.0 o posterior.

Limitaciones e instrucciones

Los valores predeterminados deben ser serializables por JSON (no se admiten conjuntos y tuplas). Para los valores predeterminados de lista o diccionario, use None en la firma y asigne el valor predeterminado real dentro de la función para evitar valores predeterminados mutables compartidos. Use el formato ISO 8601 (por ejemplo, 2025-12-31T23:59:59Z) para los valores predeterminados de fecha y hora. El uso de DataFrame o Series de Pandas como valor predeterminado requiere fabric-user-data-functions la versión 1.0.0 o posterior.

Mostrar detalles

Puede inspeccionar los metadatos de elementos UDF y las firmas de función mediante programación.

Mostrar detalles del elemento de UDF

display(myFunctions.itemDetails)

Mostrar detalles de la función

display(myFunctions.functionDetails)

Sugerencia

Inspeccione functionDetails siempre cuando trabaje con un nuevo elemento de UDF. Esto le ayuda a comprobar las funciones disponibles y sus tipos de parámetros esperados antes de la invocación.

Gestión de errores

Envuelva las invocaciones de UDF con un manejo de errores apropiado para el lenguaje para gestionar correctamente las funciones que faltan o los tipos de parámetros inesperados. Compruebe siempre que existe una función en el elemento UDF antes de llamarla.

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

Uso de funciones UDF en una canalización de datos

Puede crear funciones de UDF para crear pasos de ETL reutilizables:

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

Importante

Las invocaciones de UDF tienen un coste adicional. Si llama a la misma función con los mismos parámetros repetidamente, considere la posibilidad de almacenar en caché el resultado. Evite llamar a funciones UDF en bucles estrechos siempre que sea posible.

Contenido relacionado

  • Last updated on