Comparteix via

Generación de código de invocación para funciones de datos de usuario

Una vez que haya publicado las funciones de datos de usuario, puede llamarlas desde elementos de Fabric o aplicaciones externas. En lugar de escribir el código de invocación desde cero, use la característica Generar código de invocación para crear automáticamente plantillas de código listas para usar.

Elija la opción de generación de código en función del escenario de integración:

  • Código de Fabric Notebooks (Python): para invocar funciones desde cuadernos de Fabric, que es una manera de integrarse con elementos de Fabric. Para ver otros elementos de Fabric, como Pipelines y Activator, consulte la documentación de integración.
  • Código de aplicación cliente (Python, C#, Node.js): para llamar a las funciones desde aplicaciones externas a través del punto de conexión REST único que expone cada función. Esto permite la integración con aplicaciones web, servicios o cualquier sistema fuera de Fabric.
  • Especificación openAPI (JSON, YAML): para plataformas de administración de API, agentes de IA o generación de SDK de cliente. Úselo para integrar las funciones con Azure API Management, configurar sistemas de inteligencia artificial o generar bibliotecas para aplicaciones externas.

Prerrequisitos

Antes de generar código de invocación, necesita lo siguiente:

  • Un elemento publicado de Funciones de datos de usuario con al menos una función
  • Acceso al elemento Funciones de datos de usuario en el portal de Fabric
  • Al menos el permiso Ejecutar en el elemento Funciones de datos de usuario para generar y usar código de invocación

Generación de código para cuadernos de Fabric

Al integrar con elementos de Fabric, utilice esta opción para llamar a sus funciones desde los Cuadernos de Fabric. El código generado usa la utilidad integrada mssparkutils.userDataFunction , que proporciona una manera sencilla de invocar funciones sin administrar la autenticación o los puntos de conexión. Esto es ideal para los flujos de trabajo de procesamiento de datos, el análisis exploratorio y las canalizaciones de aprendizaje automático dentro del entorno de Fabric.

  1. Abra el elemento Funciones de datos de usuario en el portal de Fabric.

  2. En la pestaña Inicio, seleccione Generar código> de invocaciónCódigo de cliente.

  3. En Invocar desde, seleccione Notebook en la lista desplegable.

  4. Seleccione el nombre de la función que desea invocar.

  5. El código se genera automáticamente en Python. (Python es el único lenguaje disponible para el código de invocación del cuaderno).

    Captura de pantalla que muestra el código de invocación de notebooks generado.

  6. Copie el fragmento de código generado.

  7. Pegue el contenido en una nueva celda de su Fabric Notebook.

  8. Actualice los parámetros de función con los valores reales. El código generado incluye un comentario que muestra dónde actualizar:

    # UPDATE BELOW: Update the request body based on the inputs to your function
myFunctions.hello_fabric(name = "string")

  9. Ejecute la celda para invocar su función.

Para obtener más información, consulte Utilidades de Funciones de datos de usuario de Fabric Notebook.

Generación de código para aplicaciones cliente

Al integrar con aplicaciones externas, use esta opción para llamar a las funciones a través del punto de conexión REST único que expone cada función. El código generado incluye la configuración de autenticación mediante el identificador de Microsoft Entra y controla el flujo de solicitud/respuesta HTTP. Esto le permite invocar las funciones de Fabric desde aplicaciones web, aplicaciones móviles, microservicios o cualquier sistema fuera del entorno de Fabric.

  1. Abra el elemento Funciones de datos de usuario en el portal de Fabric.

  2. En la pestaña Inicio, seleccione Generar código> de invocaciónCódigo de cliente.

  3. En Invocar desde, seleccione Aplicación cliente en la lista desplegable.

  4. Seleccione el nombre de la función que desea invocar.

  5. Elija el lenguaje de programación:

    • Python
    • C#
    • Node.js

    Captura de pantalla que muestra la salida del código de cliente.

  6. Copie el código generado y agréguelo a la aplicación.

  7. Revise la estructura de código:

    • Autenticación : usa InteractiveBrowserCredential para adquirir un token (solo para desarrollo o pruebas)
    • URL del Punto de Conexión: el único punto de conexión REST para su función específica
    • Cuerpo de la solicitud : contiene los parámetros de entrada que espera la función.

  8. Actualice la request_body sección con los valores de parámetro reales. El código generado incluye un comentario que muestra dónde actualizar:

    # UPDATE HERE: Update the request body based on the inputs to your function 
request_body = {
    "name": "string"
}

  9. En el caso de las aplicaciones de producción, reemplace el código de autenticación por el registro adecuado de la aplicación de Microsoft Entra ID. El código generado incluye una advertencia y un vínculo a instrucciones para la autenticación de producción.

Para ver un tutorial completo, incluida la configuración de autenticación de producción, consulte Invoke User Data Functions from a Python application (Invocar funciones de datos de usuario desde una aplicación de Python).

Generación de la especificación de OpenAPI

Cuando necesite integrar las funciones con plataformas de administración de API, agentes de IA o generar SDK de cliente para aplicaciones externas, use esta opción para crear una especificación de OpenAPI. La especificación de OpenAPI proporciona una descripción legible por máquina de los puntos de conexión REST de la función, lo que facilita la detección e integración con las funciones mediante programación.

  1. Abra el elemento Funciones de datos de usuario en el portal de Fabric.

  2. En la pestaña Inicio, seleccione Generar código> de invocaciónEspecificación openAPI.

  3. En el cuadro de diálogo Generar especificación openAPI , seleccione el formato de salida:

    • JSON
    • YAML

    Captura de pantalla que muestra la especificación de OpenAPI.

  4. Copie la especificación generada. La especificación incluye:

    • Todas las funciones publicadas en el elemento Funciones de datos de usuario
    • Esquemas de solicitud y respuesta para cada función
    • Requisitos de autenticación (token de portador)
    • Respuestas de error HTTP estándar (400, 401, 403, 408, 413, 500)
    • Resúmenes y descripciones de funciones (de docstrings)

Mejora de la salida de OpenAPI con docstrings

La calidad de la especificación de OpenAPI depende de la documentación del código de función. Cuando los sistemas como Azure API Management, los agentes de IA o las herramientas de documentación de API consumen la especificación de OpenAPI, se basan en descripciones claras para comprender lo que hacen las funciones.

El generador de OpenAPI extrae automáticamente la información de los docstrings de tus funciones. Agregue estas propiedades a las funciones para crear documentación completa de la API:

  • Resumen : explicación de una línea que aparece en catálogos de API y vistas de alto nivel
  • Descripción : explicación detallada de lo que hace la función, qué entradas espera y qué devuelve.

Función de ejemplo con documentación adecuada:

@udf.function()
def hello_fabric(name: str) -> str:
    """
    Summary: A Python function that prints your name and the time.
    Description: This function takes a string input and concatenates it with the current time 
    to give you a warm welcome to User Data Functions. Returns a string and provides a log entry.
    """
    logging.info('Python UDF trigger function processed a request.')
    return f"Welcome to Fabric Functions, {name}, at {datetime.datetime.now()}!"

Al generar la especificación OpenAPI, estos valores de docstring rellenan los campos summary y description en el esquema de OpenAPI, lo que facilita a los desarrolladores y sistemas comprender cómo usar tus funciones.

Usos comunes para el código generado

Una vez que haya generado el código de invocación, puede usarlo para integrar las funciones en diferentes escenarios:

Integraciones de elementos de Tejido:

  • Llamar funciones desde Notebooks para el procesamiento de datos, el aprendizaje automático y el análisis exploratorio
  • Orquestar funciones en canalizaciones para flujos de trabajo de transformación de datos
  • Desencadenar funciones desde las reglas del activador en respuesta a eventos en tiempo real.

Integraciones de aplicaciones externas:

  • Invocación de funciones desde aplicaciones web, aplicaciones móviles o microservicios mediante código de aplicación cliente
  • Importación de especificaciones de OpenAPI en Azure API Management u otras puertas de enlace de API para la administración centralizada
  • Generación de SDK de cliente mediante openAPI Generator para una integración coherente en varios sistemas
  • Configurar agentes de IA para descubrir y llamar a tus funciones mediante la especificación OpenAPI
  • Prueba y validación de funciones mediante herramientas como Postman o Swagger UI

Contenido relacionado

  • Last updated on