Creación de un elemento de funciones de datos de usuario de Fabric

Las funciones de datos de usuario permiten crear funciones de Python reutilizables que se pueden invocar en Microsoft Fabric y desde aplicaciones externas. Al centralizar la lógica de negocios en las funciones, puede mantener la coherencia, reducir la duplicación de código y simplificar los flujos de trabajo de transformación de datos en toda la organización.

Con las funciones de datos de usuario, puede hacer lo siguiente:

• Centralización de la lógica de negocios : escriba funciones una vez e invoquelas desde canalizaciones, cuadernos, reglas activadores y Power BI
• Integración sin problemas : llamada a funciones a través de puntos de conexión REST desde cualquier aplicación o servicio
• Aceleración del desarrollo : uso de funciones de ejemplo pregeneradas o creación de funciones personalizadas con el modelo de programación de Python
• Mantener la coherencia : asegúrese de que las transformaciones de datos y las reglas de negocio se aplican uniformemente en todas las cargas de trabajo.

En este inicio rápido se muestra cómo crear el primer elemento de Funciones de datos de usuario, agregar funciones desde la biblioteca de ejemplo, escribir funciones personalizadas y ejecutarlas en el portal de Fabric. Al final, tiene una función operativa que muestra la normalización de categorías para los datos de producto.

Lo que logras

En este inicio rápido, completará las siguientes tareas:

1. Creación de un elemento de Funciones de datos de usuario en el área de trabajo
2. Adición y configuración de bibliotecas de Python necesarias (como pandas)
3. Inserción de una función desde la biblioteca de ejemplo
4. Escribir una función personalizada con la sintaxis y los decoradores adecuados
5. Prueba y publica tus funciones
6. Ejecución de funciones en el portal y visualización de resultados

Prerrequisitos

• Una capacidad de Microsoft Fabric en una de las regiones admitidas. Si no tiene capacidad de Fabric, inicie una evaluación gratuita de Fabric.
• Un área de trabajo de Fabric asignada a esa capacidad

Crear un elemento de funciones de datos de usuario

1. En su área de trabajo, seleccione + Nuevo elemento.

2. Busque y seleccione el icono Funciones de datos de usuario .

   

3. Escriba un nombre para el elemento de funciones de datos de usuario y seleccione Crear.

4. Seleccione el nuevo archivo de función para crear una nueva función de ejemplo. La hello_fabric función de Python se publica y carga en el editor de código.

5. El Explorador de Functions muestra todas las funciones publicadas y listas para invocarse. Puesto que la hello_fabric función se publica, puede ejecutarla desde la lista de funciones en el Explorador de Functions.

   

Agregar una nueva función desde el ejemplo

En este ejemplo se muestra cómo agregar una nueva función desde el menú Insertar ejemplo . En este caso, agregamos una función denominada Manipular datos con la biblioteca pandas que usa la pandas biblioteca como requisito.

Adición de bibliotecas necesarias

1. Asegúrese de que está en modo Desarrollo .

   

2. Seleccione Administración de bibliotecas para agregar las bibliotecas que requiere la función.

   

3. Seleccione +Agregar desde PyPI para agregar una nueva biblioteca desde el repositorio público de PyPI.

4. Busque y seleccione la biblioteca pandas y seleccione la versión. Una vez agregada la biblioteca, se guarda automáticamente en el elemento Funciones de datos de usuario.

   

5. Opcionalmente, puede actualizar la versión de la fabric_user_data_functions biblioteca a la versión más reciente disponible. Seleccione el icono de lápiz situado junto a la biblioteca para actualizarlo.

   Nota:

   La fabric_user_data_functions biblioteca se incluye de forma predeterminada y no se puede quitar. Esta biblioteca es necesaria para la funcionalidad de las funciones de datos de usuario. Debe actualizar la versión de esta biblioteca para cualquier versión futura de este SDK.

6. Cierre el panel Administración de bibliotecas para volver a la página principal de User Data Functions.

Insertar la función de ejemplo

1. Seleccione la pestaña Editar para abrir más opciones de edición en el menú de la cinta de opciones.

2. Seleccione Insertar ejemplo>Manipulación de datos>Manipular datos con la biblioteca pandas. Esta acción agrega una nueva función que usa la pandas biblioteca para manipular datos.

   

3. Después de insertar el ejemplo en el editor, verá que la nueva función aparece en el Explorador de Functions con un icono de círculo junto a él. Este icono indica que la función cambió desde que se publicó por última vez, lo que significa que hay actualizaciones que deben publicarse.

   

Escritura de una función personalizada

Ahora que ha agregado una función desde la biblioteca de ejemplo, puede escribir su propia función personalizada directamente en el editor de código. En esta sección se muestra la sintaxis y la estructura necesarias para crear funciones desde cero.

Cada función ejecutable requiere el @udf.function() decorador antes de la definición de la función. Este decorador marca la función de Python como ejecutable dentro del marco de Funciones de datos de usuario. La sintaxis básica es:

@udf.function()
def your_function_name(parameter: type) -> return_type:
    # Your function logic here
    return result

Importante

Los nombres de parámetro deben usar camelCase (por ejemplo, productName en lugar de product_name) y se requieren todos los parámetros. Para conocer los requisitos y limitaciones de sintaxis completos, consulte Requisitos y limitaciones de sintaxis.

Este es un ejemplo completo que estandariza las categorías de productos de los datos de ventas sin procesar:

# This function standardizes inconsistent product category names from different data sources

@udf.function()
def standardize_category(productName: str, rawCategory: str) -> dict:
    # Define category mappings for common variations
    category_mapping = {
        "electronics": ["electronic", "electronics", "tech", "devices"],
        "clothing": ["clothes", "clothing", "apparel", "fashion"],
        "home_goods": ["home", "household", "home goods", "furniture"],
        "food": ["food", "grocery", "groceries", "snacks"],
        "books": ["book", "books", "reading", "literature"]
    }
    
    # Normalize the input
    raw_lower = rawCategory.lower().strip()
    
    # Find the standardized category
    standardized = "other"
    for standard_name, variations in category_mapping.items():
        if raw_lower in variations:
            standardized = standard_name
            break
    
    return {
        "product_name": productName,
        "original_category": rawCategory,
        "standardized_category": standardized,
        "needs_review": standardized == "other"
    }

Puede agregar esta función al editor de código junto con las funciones existentes. La función aparece en el explorador de Functions con un icono de círculo, lo que indica que debe publicarse.

Conceptos clave del modelo de programación

Las funciones de datos de usuario usan el modelo de programación de Python de Funciones de datos de usuario para crear, ejecutar, depurar y modificar funciones individuales. El paquete proporciona el fabric-user-data-functions modelo de programación, que está disponible públicamente en PyPI y preinstalado en los elementos de funciones de datos de usuario.

Al crear la primera función, el archivo de código incluye las instrucciones de importación necesarias:

import datetime
import fabric.functions as fn
import logging

udf = fn.UserDataFunctions()

Puntos clave sobre el modelo de programación:

• El paquete fabric-user-data-functions proporciona el módulo fabric.functions, que se importa como fn en el código.
• La fn.UserDataFunctions() llamada crea el contexto de ejecución necesario para definir y ejecutar funciones dentro de un elemento Funciones de datos de usuario.
• Otras bibliotecas como logging le permiten escribir registros personalizados para la depuración y la supervisión.

Nota:

La import fabric.functions as fn instrucción y la udf = fn.UserDataFunctions() línea son necesarias para que las funciones funcionen correctamente. Las funciones no funcionarán si faltan estas líneas.

Prueba y publica tus funciones

Ahora que ha creado varias funciones (la función de ejemplo manipulate_data y la función personalizada standardize_category ), puede probarlas y publicarlas juntas.

1. Mientras se encuentra en el modo Desarrollo , puede probar cada función mediante la funcionalidad Test antes de publicarla. Las pruebas permiten validar los cambios de código sin que estén disponibles para la invocación externa.

2. Cuando esté listo para que las funciones estén disponibles, seleccione Publicar para guardar los cambios y actualizar todas las funciones. La publicación puede tardar unos minutos.

3. Una vez finalizada la publicación, todas las funciones se actualizan en la lista explorador de Functions y se quitan los iconos de círculo. Las funciones ya están listas para ser:

   • Ejecutar desde el portal en modo de solo ejecución
   • Se invoca desde otro elemento de Fabric, como una canalización, un cuaderno o una regla activator.
   • Se llama desde una aplicación externa a través del punto de conexión REST.

Ejecuta tus funciones

Con todas las funciones creadas, probadas y publicadas, ahora puede cambiar al modo Ejecutar solo para ejecutarlas y ver los resultados.

1. Seleccione Solo modo de ejecución en el selector de modo en la esquina superior derecha del portal.

   

2. Seleccione el icono Ejecutar que aparece al mantener el puntero sobre una función en la lista Explorador de Functions.

   

Ejecuta la función de ejemplo

1. En el Explorador de Functions, mantenga el puntero sobre la manipulate_data función.

2. Seleccione el botón Ejecutar que aparece al mantener el puntero sobre la función.

3. Se abre un panel de ejecución en el lado derecho de la pantalla.

4. En el panel de ejecución, verá el nombre del parámetro data con el tipo list. Escriba el siguiente valor JSON en el cuadro de texto:

   [
    {
     "Name": "John",
     "Age": 22,
     "Gender": "male"
    }
   ]
   

5. Seleccione el botón Ejecutar del panel de ejecución (situado junto a donde especificó los datos JSON) para ejecutar la función.

   

6. Vea los resultados y los registros en Salida (lista) en el panel de ejecución. La salida muestra los datos manipulados como dataframe de Pandas en formato JSON.

Ejecución de la función personalizada

Ahora intente ejecutar la función personalizada standardize_category .

1. En el Explorador de Functions, mantenga el puntero sobre la standardize_category función.

2. Seleccione el botón Ejecutar que aparece al mantener el puntero sobre la función.

3. Se abre un panel de ejecución en el lado derecho de la pantalla.

4. Proporcione parámetros de prueba:

   • productName: Laptop Computer
   • rawCategory: tech

5. Seleccione Ejecutar y observe la salida, que debe mostrar la categoría estandarizada como "electrónica" e incluir los metadatos sobre la categorización.

Administración de funciones

Después de crear y ejecutar las funciones, puede cambiar el nombre o eliminarlas según sea necesario. Todas las operaciones de administración requieren que esté en modo de desarrollo .

Cambiar el nombre de una función

1. En el modo Desarrollar, seleccione en el editor de código y actualice el nombre de la función. Por ejemplo, cambie el nombre hello_fabric a hello_fabric1:

   @udf.function()
   def hello_fabric1(name: str) -> str:
      logging.info('Python UDF trigger function processed a request.')
   
      return f"Welcome to Fabric Functions, {name}, at {datetime.datetime.now()}!"
   

2. Después de cambiar el nombre, seleccione Publicar para guardar estos cambios.

3. Una vez publicados los cambios, verá el nuevo nombre de la función en el explorador de Functions.

Eliminar una función

Para eliminar una función, seleccione el código de función en el editor de código y quite toda la sección de código. Publique los cambios para eliminarlos por completo del elemento de funciones de datos de usuario.

Por ejemplo, para eliminar la función hello_fabric, quite el siguiente bloque de código:

@udf.function()
def hello_fabric(name: str) -> str:
    logging.info('Python UDF trigger function processed a request.')

    return f"Welcome to Fabric Functions, {name}, at {datetime.datetime.now()}!"

Una vez quitado el código, puede seleccionar Publicar para guardar los cambios. Una vez completada la publicación, verá una lista actualizada de funciones disponibles en el Explorador de Functions.

Solución de problemas

Si tiene problemas al trabajar con Las funciones de datos de usuario:

• Function no publicará : compruebe si hay errores de sintaxis en el código. Asegúrese de que están presentes todas las importaciones necesarias (fabric.functions) y la udf = fn.UserDataFunctions() línea.
• Errores de nomenclatura de parámetros : recuerde que los nombres de parámetro deben usar camelCase (sin caracteres de subrayado). Revise los requisitos y las limitaciones de la sintaxis.
• Errores de importación de biblioteca: compruebe que todas las bibliotecas necesarias se agregan a través de administración de bibliotecas y que la versión es compatible con Python 3.11.
• Función que no aparece en el Explorador de Functions : asegúrese de publicar los cambios después de agregar o modificar funciones.

Para obtener más ayuda, consulte Límites y consideraciones del servicio User Data Functions.

Contenido relacionado

Ahora que ha creado el primer elemento de Funciones de datos de usuario, explore estos recursos para expandir sus aptitudes:

• Creación de un elemento de funciones de datos de usuario de Fabric en Visual Studio Code : aprenda a desarrollar funciones localmente con compatibilidad completa con ide
• Más información sobre el modelo de programación de funciones de datos de usuario: profundización en el SDK de Python y las características avanzadas
• Invocación de funciones de datos de usuario desde una aplicación de Python : llamada a las funciones desde aplicaciones externas a través de las API REST
• Administración de librerías para las funciones de datos de usuario - Aprenda técnicas avanzadas de gestión de librerías