Configuración de un back-end de carga de trabajo de Microsoft Fabric mediante la especificación openAPI (Swagger)

Un back-end de carga de trabajo de Microsoft Fabric es un servicio que implementa el contrato de API de Fabric, lo que permite que las cargas de trabajo personalizadas se integren sin problemas con la plataforma de Microsoft Fabric. Este back-end controla las operaciones de ciclo de vida de los elementos de carga de trabajo, incluida la creación, recuperación, actualizaciones y eliminación.

Este artículo le guía a través de la generación rápida de un back-end de carga de trabajo de Fabric directamente desde una definición de OpenAPI (Swagger). Este enfoque de API primero le permite crear prototipos y validar rápidamente la lógica de back-end de forma independiente, incluso antes de integrarla en el entorno de desarrollo completo de Microsoft Fabric. Los principios que se muestran aquí son ampliamente aplicables, independientemente de las herramientas o idiomas específicos que elija.

Al final de este artículo podrá realizar lo siguiente:

Genere un backend de carga de trabajo de Fabric basado en el archivo Swagger incluido en un ejemplo.
Comprenda la estructura básica y los componentes de un back-end de carga de trabajo de Fabric.
Ejecute y pruebe el back-end generado localmente mediante Python y FastAPI.

En este artículo, implementará las siguientes operaciones principales del ciclo de vida del elemento. Estas operaciones corresponden a los puntos de conexión definidos en el archivo Swagger de la API de Fabric.

Crear elemento: inicialice nuevos elementos de carga de trabajo.
Obtener carga útil del elemento: Recuperar la configuración del elemento.
Actualizar elemento: modifique los elementos existentes.
Eliminar elemento: quite elementos del área de trabajo.

En este artículo se muestra específicamente el proceso mediante Python y FastAPI con la herramienta Generador de OpenAPI. Sin embargo, openAPI Generator admite numerosos lenguajes de programación y marcos de trabajo. Puede elegir cualquier herramienta o método de generación de código compatible con OpenAPI que se adapte a la experiencia y el proyecto de su equipo para crear el esqueleto de back-end.

Prerrequisitos

Antes de iniciar los procedimientos de este artículo, asegúrese de que tiene los siguientes elementos.

Conocimientos necesarios

Descripción del ciclo de vida de los elementos de Microsoft Fabric. Lea Administración del ciclo de vida de los elementos.

Esta comprensión es fundamental para este artículo. El back-end generado implementa las operaciones de ciclo de vida (crear, leer, actualizar, eliminar) para los elementos de Fabric, tal como se define en la documentación del ciclo de vida del elemento.
Conocimientos básicos de Python y de las API RESTful.
Familiaridad con los conceptos de carga de trabajo de Microsoft Fabric.

Requisitos de software

Python 3.8 y versiones posteriores. Descarga Python.
Node.js, que es necesario si desea instalar la CLI del generador de OpenAPI a través de npm. Descargue Node.js.
Git, para clonar el repositorio de ejemplo. Descargar Git.
Un editor de código, como Visual Studio Code, PyCharm o su entorno de desarrollo integrado (IDE) preferido.

Java para openAPI Generator

La CLI del generador de OpenAPI requiere Java como entorno de tiempo de ejecución. No es necesario escribir código Java. Solo necesita ejecutar la herramienta generador.

La versión mínima de Java necesaria es Java 8. Se recomienda usar una versión de soporte técnico a largo plazo (LTS), como Java 17 o Java 21.

Para instalar Java:

Instale la compilación de Microsoft de OpenJDK (recomendado). Siga las instrucciones para su sistema operativo en Instalar Microsoft Build de OpenJDK.

Compruebe la instalación. Abra un terminal o línea de comandos y ejecute:

java -version

Debería mostrarse una salida similar a esta de ejemplo:

openjdk version "17.0.12" 2024-07-16 LTS
OpenJDK Runtime Environment Microsoft-10377968 (build 17.0.12+7-LTS)
OpenJDK 64-Bit Server VM Microsoft-10377968 (build 17.0.12+7-LTS, mixed mode, sharing)

Si ya tiene Java instalado desde otro proveedor (por ejemplo, Oracle, Eclipse Temurin o Amazon Corretto) con la versión 8 o posterior, puede usar la instalación existente.

Paso 1: Configuración del entorno de desarrollo

En primer lugar, configure el entorno de desarrollo con las herramientas y paquetes necesarios:

Clonar el repositorio de muestra para desarrolladores de Microsoft Fabric.

git clone https://github.com/microsoft/Microsoft-Fabric-workload-development-sample
cd Microsoft-Fabric-workload-development-sample

Cree un PythonBackend directorio:
```
mkdir PythonBackend
cd PythonBackend
```

Cree un entorno virtual de Python:

# Create a Python virtual environment for the project
python -m venv .venv

# Activate the virtual environment
# Windows
.venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate

Instale la CLI del generador de OpenAPI:
```
npm install @openapitools/openapi-generator-cli -g
```
Para obtener métodos de instalación alternativos, consulte la documentación de instalación del generador de OpenAPI.

Paso 2: Comprobación de que el entorno virtual de Python está activo

Después de crear el entorno virtual, es fundamental asegurarse de que usa el intérprete de Python correcto. Este enfoque mantiene las dependencias del proyecto aisladas y administradas correctamente.

Comprobación de la activación del entorno virtual

Confirme que el entorno virtual está activado. Debería ver (.venv) al principio del mensaje del terminal.

Si el entorno virtual no está activado, ejecute:

# Windows
.venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate

Comprobación de que el intérprete de Python del entorno virtual está activo

Confirme que el terminal usa el intérprete de Python desde el entorno virtual, no la instalación global de Python del sistema.

Ejecute el siguiente comando:

# Display the path to the active Python interpreter
python -c "import sys; print(sys.executable)"

La salida esperada debe apuntar al entorno virtual:

- Windows: C:\path\to\project\PythonBackend\.venv\Scripts\python.exe
- macOS/Linux: /path/to/project/PythonBackend/.venv/bin/python

Importante

Si la salida apunta a una ubicación diferente (como la instalación de Python para todo el sistema), el entorno virtual no se activa correctamente. Vuelva a consultar la tarea de activación y asegúrese de que aparece el mensaje del terminal con (.venv).

Configuración del IDE (opcional)

La mayoría de los IDE modernos detectan automáticamente entornos virtuales de Python. Sin embargo, es posible que tenga que seleccionar manualmente el intérprete dentro de la configuración del IDE.

Ejemplo: Configuración de Visual Studio Code

Abra la carpeta del proyecto en Visual Studio Code.
Abra la paleta de comandos:
- Windows o Linux: Ctrl+Shift+P
- macOS: Cmd+Shift+P
Busque y seleccione Python: Select Interpreter.
Elija el intérprete ubicado en el entorno virtual:
- Windows: .venv\Scripts\python.exe
- macOS o Linux: .venv/bin/python
Compruebe la selección en la barra de estado de la parte inferior de Visual Studio Code. Debería mostrar algo parecido a:
```
Python 3.x.x ('.venv': venv)
```
Abra un nuevo terminal integrado (Terminal>Nuevo terminal). El entorno virtual debe activarse automáticamente, como se indica (.venv) en la línea de comandos.

Solución de problemas del entorno virtual

Asegúrese siempre de que el entorno virtual esté activado antes de instalar dependencias o ejecutar la aplicación. El (.venv) prefijo en el terminal confirma el estado de activación. Si encuentra errores de importación o paquetes que faltan, compruebe que usa el intérprete de Python correcto mediante la ejecución de los comandos de comprobación mencionados anteriormente.

Sugerencia

Si el IDE no detecta automáticamente el entorno virtual o si la ruta de acceso del intérprete no coincide con el entorno virtual, pruebe estas soluciones:

Asegúrese de abrir el IDE desde el directorio del proyecto correcto.
Reinicie el IDE e intente volver a seleccionar el intérprete.
Confirme que el entorno virtual está activado en el terminal.

Paso 3: Generación del proyecto fastAPI a partir de la especificación de OpenAPI

Usa la herramienta CLI de OpenAPI Generator para crear un proyecto de FastAPI en Python a partir de la especificación Swagger del Fabric API.

Ejecución del comando de generación

Ejecute el siguiente comando desde el PythonBackend directorio:

openapi-generator-cli generate -i ../Backend/src/Contracts/FabricAPI/Workload/swagger.json -g python-fastapi -o . --additional-properties=packageName=fabric_api

Este comando indica a la CLI del generador de OpenAPI que realice las siguientes acciones:

Parámetro	Importancia	Descripción	Obligatorio	Propósito	Referencia
`-i`	`[InputSpecPath]` ¹	Especificación de entrada: Especifica la ruta de acceso al archivo de definición de OpenAPI (Swagger) de código fuente.	Obligatorio	Hace referencia al contrato de la API de Fabric que define todos los puntos de conexión, modelos y operaciones.	Especificación de OpenAPI
`-g`	`python-fastapi` ²	Nombre del generador: Indica a la herramienta que use el `python-fastapi` generador para crear código python del lado servidor	Obligatorio	Determina el lenguaje y el marco de salida para el código back-end generado.	Generador de FastAPI de Python Exploración de todos los generadores de servidores disponibles
`-o`	`.`	Directorio de salida: Indica al generador que coloque los archivos de salida en el directorio actual.	Obligatorio	Especifica dónde se crea la estructura del proyecto generada.	No aplicable
`--additional-properties`	`packageName=fabric_api`	Opciones específicas del generador: Establece el nombre del paquete de Python para el código generado en `fabric_api`	Opcional	Personaliza la estructura de código generada y las convenciones de nomenclatura	Opciones del generador

¹ Para [InputSpecPath], la ruta de acceso es ../Backend/src/Contracts/FabricAPI/Workload/swagger.json.

² Para el parámetro generador (-g), en este artículo se usa el valor python-fastapi como ejemplo. OpenAPI Generator admite numerosos generadores de código del lado servidor para varios lenguajes y marcos de trabajo. Puede reemplazar python-fastapi con el generador que desee. Para obtener una lista completa, consulte la documentación sobre los generadores de servidores openAPI.

Instalación de las dependencias necesarias

Para instalar dependencias, use este comando:

pip install -r requirements.txt

En Windows, es posible que encuentre un error con el uvloop paquete. Si eso ocurre, haga lo siguiente:

Abrir el archivo requirements.txt.
Busque la uvloop entrada, que podría tener un aspecto similar a uvloop==0.17.0. Agregue la plataforma condicional al final:
```
uvloop==<existing version>; sys_platform != 'win32'
```
Por ejemplo, si el archivo tiene uvloop==0.17.0, cámbielo a uvloop==0.17.0; sys_platform != 'win32'.
Vuelva a ejecutar pip install -r requirements.txt.

Este cambio garantiza que uvloop se instale solo en plataformas que no son Windows.

Paso 4: Descripción de la estructura de código generada

OpenAPI Generator crea un proyecto de FastAPI estructurado con los siguientes directorios clave:

PythonBackend/
├── src/
│   └── fabric_api/
│       ├── apis/              # Generated API route definitions
│       │   ├── item_lifecycle_api.py
│       │   ├── jobs_api.py
│       │   └── endpoint_resolution_api.py
│       ├── impl/              # Where you'll implement controllers
│       │   └── __init__.py
│       ├── models/            # Data models for requests/responses
│       │   ├── create_item_request.py
│       │   └── ...
│       └── main.py            # FastAPI application entry point
├── tests/                     # Generated test files
└── requirements.txt           # Dependencies

El apis directorio contiene las definiciones de enrutador para cada punto de conexión de API.
El models directorio contiene modelos Pydantic para objetos de solicitud y respuesta.
El impl directorio es donde se implementa la lógica del controlador.
El main.py archivo configura la aplicación FastAPI.

Paso 5: Implementar el controlador ItemLifecycle

Cree una implementación del controlador que controle las solicitudes de api de Fabric. El controlador hereda de la clase base generada.

Cree item_lifecycle_controller.py en el directorio impl.

# file path: src/fabric_api/impl/item_lifecycle_controller.py

from fabric_api.apis.item_lifecycle_api_base import BaseItemLifecycleApi
from fabric_api.models.get_item_payload_response import GetItemPayloadResponse
from pydantic import Field, StrictStr
from typing_extensions import Annotated
from fastapi import HTTPException

class ItemLifecycleController(BaseItemLifecycleApi):
    """
    Implementation of Item Lifecycle API methods.
    """
    
    async def item_lifecycle_create_item(
        self,
        workspaceId,
        itemType,
        itemId,
        activity_id,
        request_id,
        authorization,
        x_ms_client_tenant_id,
        create_item_request,
    ) -> None:
        """
        Implementation for creating a new item.
        """
        print(f"\n=== CREATE ITEM CALLED ===")
        print(f"Workspace ID: {workspaceId}")
        print(f"Item Type: {itemType}")
        print(f"Item ID: {itemId}")
        print(f"Display Name: {create_item_request.display_name}")
        print(f"Description: {create_item_request.description}")
        if create_item_request.creation_payload:
            print(f"Creation Payload: {create_item_request.creation_payload}")
        print("===========================\n")
        return
    
    async def item_lifecycle_delete_item(
        self,
        workspaceId,
        itemType,
        itemId,
        activity_id,
        request_id,
        authorization,
        x_ms_client_tenant_id,
    ) -> None:
        """
        Implementation for deleting an existing item.
        """
        print(f"Delete item called for itemId: {itemId}")
        return
    
    async def item_lifecycle_get_item_payload(
        self,
        workspaceId,
        itemType,
        itemId,
        activity_id,
        request_id,
        authorization,
        x_ms_client_tenant_id,
    ) -> GetItemPayloadResponse:
        """
        Implementation for retrieving the payload for an item.
        """
        print(f"Get item payload called for itemId: {itemId}")
        # Return a simple payload
        return GetItemPayloadResponse(item_payload={"sample": "data"})
    
    async def item_lifecycle_update_item(
        self,
        workspaceId,
        itemType,
        itemId,
        activity_id,
        request_id,
        authorization,
        x_ms_client_tenant_id,
        update_item_request,
    ) -> None:
        """
        Implementation for updating an existing item.
        """
        print(f"Update item called for itemId: {itemId}")
        return

Paso 6: Configuración y ejecución de la aplicación FastAPI

Antes de ejecutar la aplicación FastAPI, asegúrese de que la configuración del puerto se alinea con el entorno de desarrollo de Microsoft Fabric. Este paso es fundamental para la integración adecuada con el gateway de desarrollo de Fabric.

Descripción de la configuración del puerto

Al desarrollar una carga de trabajo de Microsoft Fabric, la puerta de enlace de desarrollo enruta las solicitudes de API al back-end. Esta configuración requiere:

Tu back end debe ejecutarse en un puerto específico (valor predeterminado: 5000).
Puerto que coincide con el valor WorkloadEndpointURL en la configuración de la carga de trabajo.
Todas las llamadas API de Fabric deben ser enrutadas a través de la puerta de enlace de desarrollo hacia este punto de conexión.

Configura el punto de conexión de carga de trabajo (para la integración de Fabric)

Al integrarse con el entorno completo de desarrollo de Microsoft Fabric, debe configurar la URL del punto de conexión de carga de trabajo. Esta configuración indica a la puerta de enlace de desarrollo dónde reenviar solicitudes de API.

Busque o cree el archivo de configuración de carga de trabajo (workload-dev-mode.json):
- La ubicación predeterminada es C:\workload-dev-mode.json.
- Puede crear este archivo más adelante cuando configure el entorno de desarrollo completo de Fabric.

Asegúrese de que el valor WorkloadEndpointURL coincida con su puerto de back-end.

{
    "WorkloadEndpointURL": "http://localhost:5000",
    // ... other configuration settings
}

Para obtener información completa sobre la configuración de la carga de trabajo, consulte la documentación para empezar a trabajar con el back-end de extensibilidad.

Ejecución de la aplicación FastAPI

Inicie la aplicación FastAPI en el puerto 5000 (o el puerto elegido que coincida con la configuración).

Para Windows PowerShell:

$env:PYTHONPATH="src"
uvicorn fabric_api.main:app --host 0.0.0.0 --port 5000

Para un símbolo del sistema de Windows:

set PYTHONPATH=src
uvicorn fabric_api.main:app --host 0.0.0.0 --port 5000

Para macOS o Linux:

PYTHONPATH=src uvicorn fabric_api.main:app --host 0.0.0.0 --port 5000

Importante

La configuración PYTHONPATH es fundamental para Que Python encuentre correctamente los módulos. Esta variable de entorno afecta solo a la sesión de terminal actual.

Como alternativa, puede ejecutar el comando desde el src directorio :

cd src
python -m uvicorn fabric_api.main:app --host 0.0.0.0 --port 5000

Nota:

A menudo, el puerto 5000 se usa como valor predeterminado en los ejemplos de desarrollo de cargas de trabajo de Microsoft Fabric. Si necesita usar un puerto diferente:

Cambie el --port valor del uvicorn comando (por ejemplo, --port 5001).
Para que coincida con este puerto nuevo, actualice el WorkloadEndpointURL valor del workload-dev-mode.json archivo (por ejemplo, "http://localhost:5001").

Asegúrese de que otra aplicación del sistema aún no esté usando el puerto elegido.

Verifique que el backend sea accesible

Después de iniciar la aplicación, compruebe que se está ejecutando correctamente:

Compruebe la salida de la consola. Debe ser similar a este ejemplo:

INFO:     Uvicorn running on http://0.0.0.0:5000 (Press CTRL+C to quit)
INFO:     Started reloader process [xxxx]
INFO:     Started server process [xxxx]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

Pruebe la documentación de la API:
1. Abra su explorador y diríjase a http://localhost:5000/docs.
2. Confirme que la interfaz de usuario de Swagger muestra todos los puntos de conexión disponibles.

Paso 7: Probar la API

Puede probar la API mediante comandos de Curl o la interfaz de usuario integrada de Swagger que proporciona FastAPI.

curl

Ejecute el siguiente comando en el terminal:

curl -X POST "http://localhost:5000/workspaces/test-workspace/items/TestItemType/test-item-123" \
  -H "Content-Type: application/json" \
  -H "activity-id: test-activity-id" \
  -H "request-id: test-request-123" \
  -H "authorization: SubjectAndAppToken1.0 subjectToken=\"dummy-token\", appToken=\"dummy-app-token\"" \
  -H "x-ms-client-tenant-id: test-tenant-456" \
  -d '{
    "display_name": "Test Item",
    "description": "This is a test item created via curl",
    "creation_payload": {
      "key1": "value1",
      "key2": "value2",
      "nested": {
        "data": "example"
      }
    }
  }'

Interfaz de usuario de Swagger

FastAPI genera automáticamente documentación de API interactiva, por lo que puede probar los puntos de conexión directamente desde el explorador:

Abra su explorador y diríjase a http://localhost:5000/docs.

En la ItemLifecycle sección, busque el POST endpoint.

POST /workspaces/{workspaceId}/items/{itemType}/{itemId}

Seleccione el botón Pruébelo.
Rellene los parámetros obligatorios:
- workspaceId: test-workspace
- itemType: TestItemType
- itemId: test-item-123
- activity-id: test-activity-id
- request-id: test-request-123
- authorization: SubjectAndAppToken1.0 subjectToken="dummy-token", appToken="dummy-app-token"
- x-ms-client-tenant-id: test-tenant-456
Para el cuerpo de la solicitud, use el código siguiente:
```
{
    "display_name": "Test Item",
    "description": "This is a test item created via Swagger UI",
    "creation_payload": {
        "key1": "value1",
        "key2": "value2",
        "nested": {
        "data": "example"
        }
    }
}
```
Seleccione el botón Ejecutar para enviar la solicitud.

La consola del servidor muestra una salida similar a los mensajes siguientes:
```
=== CREATE ITEM CALLED ===
Workspace ID: test-workspace
Item Type: TestItemType
Item ID: test-item-123
Display Name: Test Item
Description: This is a test item created via Swagger UI
Creation Payload: {'key1': 'value1', 'key2': 'value2', 'nested': {'data': 'example'}}
===========================
```
Los detalles de la respuesta también aparecen directamente en la interfaz de usuario de Swagger.

Sugerencia

El uso de la interfaz de usuario de Swagger suele ser más fácil y rápido durante el desarrollo, ya que proporciona una interfaz fácil de usar para probar los puntos de conexión de API sin crear manualmente comandos de Curl.

Paso 8: Exploración de la documentación de la API

FastAPI genera automáticamente documentación de API interactiva:

Abra su explorador y diríjase a http://localhost:5000/docs.
En la interfaz de usuario de Swagger que aparece, puede explorar y probar todos los puntos de conexión.
Para ver los puntos de conexión de creación, consulta, actualización y eliminación, seleccione la sección ItemLifecycle.

En la imagen siguiente se muestra un ejemplo de la interfaz de usuario de Swagger con los puntos de conexión de la API de Fabric.

Paso 9: Implementación de funcionalidades más avanzadas

Los pasos anteriores proporcionan un ejemplo básico de cómo implementar la ItemLifecycle API mediante Python con FastAPI. Recuerde que este artículo es un ejemplo fundamental que muestra solo los conceptos básicos. Para un back-end sólido y de calidad de producción, normalmente se implementa más funcionalidad, como:

Cree clases de servicio para controlar la lógica de negocios, las operaciones de base de datos y otros elementos de una capa de servicio:

# src/fabric_api/services/storage_service.py
class StorageService:
    async def create_item(self, workspace_id, item_type, item_id, item_data):
        """
        Store the item in a database or other persistent storage
        """
        # Implementation here
        pass

    async def get_item(self, workspace_id, item_type, item_id):
        """
        Retrieve an item from storage
        """
        # Implementation here
        pass

Utilice la inyección de dependencias en su controlador.

# src/fabric_api/impl/item_lifecycle_controller.py
from fabric_api.services.storage_service import StorageService

class ItemLifecycleController(BaseItemLifecycleApi):
    def __init__(self):
        self.storage_service = StorageService()

    async def item_lifecycle_create_item(self, workspaceId, ...):
        # Use the service
        await self.storage_service.create_item(workspaceId, itemType, itemId, create_item_request)

Agregar control de errores:

async def item_lifecycle_create_item(self, ...):
    try:
        # Your implementation
        await self.storage_service.create_item(...)
        return None
    except ValueError as e:
        # Client error
        raise HTTPException(status_code=400, detail=str(e))
    except Exception as e:
        # Server error
        raise HTTPException(status_code=500, detail="Internal server error")

Estas son más consideraciones para un back-end sólido:

Implementación de los controladores restantes: Por ejemplo, implemente la API de procesos y la API de resolución de endpoints.
Autenticación y autorización: ayude a proteger los puntos de conexión mediante la validación de tokens y permisos. Para obtener más información, consulte visión general de la autenticación y autorización de back-end.
Almacenamiento persistente: integre con bases de datos u otras soluciones de almacenamiento para la persistencia de datos.
Registro y supervisión: implemente un registro y una supervisión completos para realizar un seguimiento del estado y el rendimiento de las aplicaciones.
Pruebas: escriba pruebas unitarias e de integración para ayudar a garantizar la confiabilidad y corrección.

Conclusión

Ahora ha configurado correctamente un back-end de la API de carga de trabajo de Microsoft Fabric mediante Python con FastAPI. Esta implementación:

Usa la herramienta Generador de OpenAPI para crear un proyecto de FastAPI.
Implementa los controladores necesarios para controlar las solicitudes de API de Fabric.

Este artículo es un ejemplo básico que muestra cómo implementar una API para ItemLifecycle mediante Python. Más mejoras y consideraciones, como las descritas en paso 9: Implementar funcionalidades más avanzadas, son necesarias para crear un back-end seguro, sólido y de alta calidad que sea adecuado para un entorno de producción.

Una integración completa con Microsoft Fabric requiere implementar el control de autenticación adecuado, el almacenamiento persistente, el control completo de errores y la lógica de negocios personalizada específica de la carga de trabajo.

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2025-07-02