Configurer un back-end de charge de travail Microsoft Fabric à l’aide de la spécification OpenAPI (Swagger)

2025-07-02

Un back-end de charge de travail Microsoft Fabric est un service qui implémente le contrat d’API Fabric, qui permet aux charges de travail personnalisées de s’intégrer en toute transparence à la plateforme Microsoft Fabric. Ce back-end gère les opérations de cycle de vie de vos éléments de charge de travail, notamment la création, la récupération, les mises à jour et la suppression.

Cet article vous guide tout au long de la génération rapide d’un back-end de charge de travail Fabric directement à partir d’une définition OpenAPI (Swagger). Cette approche API-first vous permet de prototyper et de valider rapidement la logique back-end indépendamment, même avant de l’intégrer dans l’environnement de développement Microsoft Fabric complet. Les principes présentés ici sont largement applicables, quels que soient les outils ou langues spécifiques que vous choisissez.

À la fin de cet article, vous serez en mesure d’effectuer les opérations suivantes :

Générez un back-end de charge de travail Fabric basé sur le fichier Swagger inclus dans un exemple.
Comprendre la structure de base et les composants d’un back-end de charge de travail Fabric.
Exécutez et testez votre back-end généré localement à l’aide de Python et FastAPI.

Dans cet article, vous implémentez les opérations principales suivantes à partir du cycle de vie des éléments. Ces opérations correspondent aux points de terminaison définis dans le fichier Swagger de l’API Fabric.

Créer un élément : initialiser de nouveaux éléments de charge de travail.
Obtenir la charge utile de l’élément : récupérer la configuration de l’élément.
Élément de mise à jour : modifiez les éléments existants.
Supprimer l’élément : supprimez les éléments de l’espace de travail.

Cet article illustre spécifiquement le processus à l’aide de Python et FastAPI avec l’outil Générateur OpenAPI. Toutefois, OpenAPI Generator lui-même prend en charge de nombreux langages de programmation et frameworks. Vous êtes libre de choisir n’importe quel outil ou méthode de génération de code compatible OpenAPI qui convient à l’expertise et au projet de votre équipe pour créer votre squelette back-end.

Conditions préalables

Avant de commencer les procédures décrites dans cet article, vérifiez que vous disposez des éléments suivants.

Connaissances requises

Compréhension du cycle de vie des éléments Microsoft Fabric. Lire la gestion du cycle de vie des éléments.

Cette compréhension est cruciale pour cet article. Le back-end généré implémente les opérations de cycle de vie (créer, lire, mettre à jour, supprimer) pour les éléments Fabric, comme défini dans la documentation sur le cycle de vie des éléments.
Connaissances de base des API Python et RESTful.
Connaissance des concepts de charge de travail Microsoft Fabric.

Logiciels requis

Python 3.8+. Télécharger Python.
Node.js, ce qui est requis si vous souhaitez installer l’interface CLI du générateur OpenAPI via npm. Téléchargez Node.js.
Git, pour cloner l’exemple de référentiel. Télécharger Git.
Éditeur de code, tel que Visual Studio Code, PyCharm ou votre environnement de développement intégré (IDE) préféré.

Java pour OpenAPI Generator

L’interface CLI du générateur OpenAPI nécessite Java en tant qu’environnement d’exécution. Vous n’avez pas besoin d’écrire du code Java. Vous n’en avez besoin que pour exécuter l’outil générateur.

La version java minimale requise est Java 8. Nous vous recommandons d’utiliser une version de support à long terme (LTS) prise en charge, telle que Java 17 ou Java 21.

Pour installer Java :

Installez la build Microsoft d’OpenJDK (recommandé). Suivez les instructions de votre système d’exploitation dans Installer microsoft Build of OpenJDK.

Vérifiez votre installation. Ouvrez un terminal ou une invite de commandes et exécutez :

java -version

La sortie doit ressembler à cet exemple :

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 vous avez déjà installé Java à partir d’un autre fournisseur (par exemple, Oracle, Eclipse Temurin ou Amazon Corretto) avec la version 8 ou ultérieure, vous pouvez utiliser votre installation existante.

Étape 1 : Configurer votre environnement de développement

Tout d’abord, configurez votre environnement de développement avec les outils et packages requis :

Clonez l’exemple de référentiel de développeurs Microsoft Fabric :

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

Créez un PythonBackend répertoire :
```
mkdir PythonBackend
cd PythonBackend
```

Créez un environnement virtuel 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

Installez l’interface CLI du générateur OpenAPI :
```
npm install @openapitools/openapi-generator-cli -g
```
Pour obtenir d’autres méthodes d’installation, consultez la documentation d’installation d’OpenAPI Generator.

Étape 2 : Vérifier que votre environnement virtuel Python est actif

Après avoir créé votre environnement virtuel, il est essentiel de vous assurer que vous utilisez l’interpréteur Python approprié. Cette approche conserve les dépendances de votre projet isolées et gérées correctement.

Vérifier l’activation de l’environnement virtuel

Vérifiez que votre environnement virtuel est activé. Vous devez voir (.venv) au début de votre invite de commande.

Si l’environnement virtuel n’est pas activé, exécutez :

# Windows
.venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate

Vérifiez que l’interpréteur Python de votre environnement virtuel est actif

Vérifiez que votre terminal utilise l’interpréteur Python de votre environnement virtuel, et non l’installation globale de Python de votre système.

Exécutez la commande suivante:

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

La sortie attendue doit pointer vers votre environnement virtuel :

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

Important

Si la sortie pointe vers un autre emplacement (par exemple, votre installation Python à l’échelle du système), votre environnement virtuel n’est pas activé correctement. Réexévez la tâche d’activation et vérifiez que votre invite de terminal s’affiche avec (.venv).

Configurer votre IDE (facultatif)

La plupart des IDE modernes détectent automatiquement les environnements virtuels Python. Toutefois, vous devrez peut-être sélectionner manuellement l’interpréteur dans vos paramètres IDE.

Exemple : configuration de Visual Studio Code

Ouvrez votre dossier de projet dans Visual Studio Code.
Ouvrez la palette de commandes :
- Windows ou Linux : Ctrl+Shift+P
- MacOS : Cmd+Shift+P
Recherchez et sélectionnez Python: Select Interpreter.
Choisissez l’interpréteur situé dans votre environnement virtuel :
- Windows : .venv\Scripts\python.exe
- macOS ou Linux : .venv/bin/python
Vérifiez votre sélection dans la barre d’état en bas de Visual Studio Code. Il doit afficher quelque chose comme suit :
```
Python 3.x.x ('.venv': venv)
```
Ouvrez un nouveau terminal intégré (terminal>nouveau terminal). Votre environnement virtuel doit être activé automatiquement, comme indiqué par l’invite (.venv).

Résoudre les problèmes liés à votre environnement virtuel

Vérifiez toujours que votre environnement virtuel est activé avant d’installer des dépendances ou d’exécuter votre application. Le (.venv) préfixe de votre terminal confirme l’état d’activation. Si vous rencontrez des erreurs d’importation ou des packages manquants, vérifiez que vous utilisez l’interpréteur Python approprié en exécutant les commandes de vérification mentionnées précédemment.

Conseil / Astuce

Si votre IDE ne détecte pas automatiquement votre environnement virtuel ou si le chemin d’accès de l’interpréteur ne correspond pas à votre environnement virtuel, essayez ces solutions :

Vérifiez que vous ouvrez votre IDE à partir du répertoire de projet approprié.
Redémarrez votre IDE et réessayez de sélectionner l’interpréteur.
Vérifiez que votre environnement virtuel est activé dans votre terminal.

Étape 3 : Générer le projet FastAPI à partir de la spécification OpenAPI

Utilisez l’interface CLI du générateur OpenAPI pour créer un projet FastAPI Python à partir de la spécification Swagger de l’API Fabric.

Exécuter la commande de génération

Exécutez la commande suivante à partir de votre PythonBackend répertoire :

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

Cette commande indique à l’interface CLI du générateur OpenAPI d’effectuer les actions suivantes :

Paramètre	Valeur	Descriptif	Obligatoire	Objectif	Référence
`-i`	`[InputSpecPath]` ¹	Spécification d’entrée : Spécifie le chemin d’accès au fichier de définition OpenAPI source (Swagger)	Obligatoire	Pointe vers le contrat d’API Fabric qui définit tous les points de terminaison, modèles et opérations	Spécification OpenAPI
`-g`	`python-fastapi` ²	Nom du générateur : Indique à l’outil d’utiliser le générateur pour créer du `python-fastapi` code Python côté serveur	Obligatoire	Détermine l’infrastructure de sortie et le langage pour le code back-end généré	Générateur FastAPI Python Explorer tous les générateurs de serveurs disponibles
`-o`	`.`	Répertoire de sortie : Indique au générateur de placer les fichiers de sortie dans le répertoire actif	Obligatoire	Spécifie l’emplacement où la structure de projet générée est créée	Sans objet
`--additional-properties`	`packageName=fabric_api`	Options spécifiques au générateur : Définit le nom du package Python pour le code généré sur `fabric_api`	Optionnel	Personnalise la structure de code générée et les conventions d’affectation de noms	Options du générateur

¹ Pour [InputSpecPath], le chemin est ../Backend/src/Contracts/FabricAPI/Workload/swagger.json.

² Pour le paramètre générateur (-g), cet article utilise la valeur python-fastapi comme exemple. OpenAPI Generator prend en charge de nombreux générateurs de code côté serveur pour différents langages et infrastructures. Vous pouvez remplacer python-fastapi par votre générateur souhaité. Pour obtenir une liste complète, reportez-vous à la documentation openAPI Server Generators.

Installer les dépendances requises

Pour installer des dépendances, utilisez cette commande :

pip install -r requirements.txt

Sur Windows, vous pouvez rencontrer une erreur avec le uvloop package. Si cela se produit :

Ouvrez votre fichier requirements.txt.
Recherchez l’entrée uvloop , qui peut ressembler à uvloop==0.17.0. Ajoutez la condition liée à la plateforme à la fin :
```
uvloop==<existing version>; sys_platform != 'win32'
```
Par exemple, si votre fichier a uvloop==0.17.0, remplacez-le uvloop==0.17.0; sys_platform != 'win32'par .
Exécutez de nouveau pip install -r requirements.txt.

Cette modification garantit l’installation uvloop uniquement sur les plateformes non-Windows.

Étape 4 : Comprendre la structure de code générée

OpenAPI Generator crée un projet FastAPI structuré avec les répertoires clés suivants :

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

Le apis répertoire contient les définitions de routeur pour chaque point de terminaison d’API.
Le models répertoire contient des modèles Pydantic pour les objets de requête et de réponse.
Le impl répertoire est l’emplacement où vous implémentez votre logique de contrôleur.
Le main.py fichier configure l’application FastAPI.

Étape 5 : Implémenter le contrôleur ItemLifecycle

Créez une implémentation de contrôleur qui gère les demandes d’API Fabric. Le contrôleur hérite de la classe de base générée.

Créez item_lifecycle_controller.py dans le impl répertoire :

# 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

Étape 6 : Configurer et exécuter l’application FastAPI

Avant d’exécuter votre application FastAPI, vérifiez que la configuration du port s’aligne sur l’environnement de développement Microsoft Fabric. Cette étape est cruciale pour une intégration appropriée à la passerelle de développement Fabric.

Comprendre la configuration du port

Lorsque vous développez une charge de travail Microsoft Fabric, la passerelle de développement achemine les demandes d’API vers votre back-end. Cette configuration nécessite :

Votre back-end à exécuter sur un port spécifique (par défaut : 5000).
Associer le port à la valeur WorkloadEndpointURL dans la configuration de la charge de travail.
Tous les appels d'API Fabric doivent être acheminés par la passerelle de développement vers ce point final.

Configurer le point de terminaison de charge de travail (pour l’intégration de Fabric)

Lorsque vous intégrez l’environnement de développement Microsoft Fabric complet, vous devez configurer l’URL du point de terminaison de charge de travail. Cette configuration indique à la passerelle de développement où transférer des demandes d’API.

Recherchez ou créez votre fichier de configuration de charge de travail (workload-dev-mode.json) :
- L’emplacement par défaut est C:\workload-dev-mode.json.
- Vous pouvez créer ce fichier ultérieurement lorsque vous configurez l’environnement de développement Fabric complet.

Vérifiez que la WorkloadEndpointURL valeur correspond à votre port principal :

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

Pour obtenir des détails complets sur la configuration de la charge de travail, consultez la documentation relative à la prise en main du back-end d’extensibilité.

Exécuter l’application FastAPI

Démarrez votre application FastAPI sur le port 5000 (ou votre port choisi qui correspond à la configuration).

Pour Windows PowerShell :

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

Pour une invite de commande de Windows :

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

Pour macOS ou Linux :

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

Important

La définition PYTHONPATH est cruciale pour Python afin de trouver correctement les modules. Cette variable d’environnement affecte uniquement la session de terminal active.

Vous pouvez également exécuter la commande à partir du src répertoire :

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

Remarque

Le port 5000 est souvent utilisé par défaut dans les échantillons de développement de charges de travail de Microsoft Fabric. Si vous devez utiliser un autre port :

Modifiez la --port valeur dans votre uvicorn commande (par exemple, --port 5001).
Pour correspondre à ce nouveau port, mettez à jour la WorkloadEndpointURL valeur dans votre workload-dev-mode.json fichier (par exemple). "http://localhost:5001"

Vérifiez qu’une autre application de votre système n’utilise pas déjà votre port choisi.

Vérifiez que votre backend est accessible

Après avoir démarré l’application, vérifiez qu’elle s’exécute correctement :

Vérifiez la sortie de la console. Il doit être similaire à cet exemple :

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.

Testez la documentation de l’API :
1. Ouvrez votre navigateur et accédez à http://localhost:5000/docs.
2. Vérifiez que l’interface utilisateur Swagger affiche tous les points de terminaison disponibles.

Étape 7 : Tester l’API

Vous pouvez tester votre API à l’aide de commandes Curl ou de l’interface utilisateur Swagger intégrée que FastAPI fournit.

Curl

Exécutez la commande suivante dans votre 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"
      }
    }
  }'

Interface utilisateur Swagger

FastAPI génère automatiquement la documentation de l’API interactive. Vous pouvez donc tester vos points de terminaison directement à partir de votre navigateur :

Ouvrez votre navigateur et accédez à http://localhost:5000/docs.
Dans la ItemLifecycle section, recherchez le POST point de terminaison :
```
POST /workspaces/{workspaceId}/items/{itemType}/{itemId}
```
Sélectionnez le bouton Essayer.
Renseignez les paramètres requis.
- 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
Pour le corps de la demande, utilisez le code suivant :
```
{
    "display_name": "Test Item",
    "description": "This is a test item created via Swagger UI",
    "creation_payload": {
        "key1": "value1",
        "key2": "value2",
        "nested": {
        "data": "example"
        }
    }
}
```
Sélectionnez le bouton Exécuter pour envoyer la requête.

Votre console de serveur affiche une sortie similaire aux messages suivants :
```
=== 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'}}
===========================
```
Les détails de la réponse s’affichent également directement dans l’interface utilisateur Swagger.

Conseil / Astuce

L’utilisation de l’interface utilisateur Swagger est souvent plus facile et plus rapide pendant le développement, car elle fournit une interface conviviale pour tester les points de terminaison d’API sans créer manuellement des commandes Curl.

Étape 8 : Explorer la documentation de l’API

FastAPI génère automatiquement la documentation de l’API interactive :

Ouvrez votre navigateur et accédez à http://localhost:5000/docs.
Sur l’interface utilisateur Swagger qui s’affiche, vous pouvez explorer et tester tous les points de terminaison.
Pour afficher les endpoints de création, d’obtention, de mise à jour et de suppression, sélectionnez la section ItemLifecycle.

L’image suivante montre un exemple de l’interface utilisateur Swagger avec les points de terminaison de l’API Fabric.

Étape 9 : Implémenter des fonctionnalités plus avancées

Les étapes précédentes ont fourni un exemple de base de l’implémentation de l’API à l’aide ItemLifecycle de Python avec FastAPI. N’oubliez pas que cet article est un exemple fondamental qui illustre uniquement les concepts fondamentaux. Pour un back-end robuste de qualité de production, vous implémentez généralement davantage de fonctionnalités, telles que :

Créez des classes de service pour gérer la logique métier, les opérations de base de données et d’autres éléments d’une couche de service :

# 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

Utilisez l’injection de dépendances dans votre contrôleur :

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

Ajouter une gestion des erreurs :

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

Voici d’autres considérations relatives à un back-end robuste :

Implémentation des contrôleurs restants : par exemple, implémentez l'API des tâches et l'API de résolution d'endpoint.
Authentification et autorisation : sécurisez vos points de terminaison en validant les jetons et les autorisations. Pour plus d’informations, consultez la vue d’ensemble de l’authentification et de l’autorisation du back-end.
Stockage persistant : intégrer des bases de données ou d’autres solutions de stockage pour la persistance des données.
Journalisation et surveillance : implémentez une journalisation et une surveillance complètes pour suivre l’intégrité et les performances des applications.
Tests : écrivez des tests unitaires et d’intégration pour garantir la fiabilité et la justesse.

Conclusion

Vous avez maintenant configuré un back-end d’API de charge de travail Microsoft Fabric à l’aide de Python avec FastAPI. Cette implémentation :

Utilise l’outil Générateur OpenAPI pour créer un projet FastAPI.
Implémente les contrôleurs nécessaires pour gérer les demandes d’API Fabric.

Cet article est un exemple de base qui montre comment implémenter une API pour ItemLifecycle en utilisant Python. D’autres améliorations et considérations, telles que celles décrites à l’étape 9 : Implémenter des fonctionnalités plus avancées, sont nécessaires pour créer un back-end de haute qualité, robuste et sécurisé adapté à un environnement de production.

Une intégration complète à Microsoft Fabric nécessite l’implémentation d’une gestion d’authentification appropriée, d’un stockage persistant, d’une gestion complète des erreurs et d’une logique métier personnalisée spécifique à votre charge de travail.