Cloud et automatisation
Architecture d’un moteur de rapports : de la demande au résultat
Suivez une demande de rapport à travers la passerelle, la sécurité, la validation, le cache, la requête Fabric, la construction du résultat et la supervision.
Dans cet article
Réponse courte : une demande de rapport traverse six étapes : passerelle, autorisation, validation, recherche dans le cache, requête et livraison du résultat. Chaque étape doit échouer avec sa propre réponse explicite et laisser un enregistrement de journal qui la nomme. Les réponses synchrones conviennent aux petits rapports rapides ; tout ce qui peut dépasser un délai HTTP doit devenir une tâche asynchrone que le client interroge.
Cycle de vie de la demande
API Management
Étape 1: Recevoir la demande
Attribuer un ID de demande, accepter un ID de corrélation
Moteur de rapports
Étape 2: Valider la demande
Rapport, format, période, limites de lignes et d’octets
Moteur de rapports
Étape 3: Résoudre tenant et sécurité
Tenant issu de claims fiables ; autoriser rapport et filtres
Compte de stockage
Étape 4: Consulter le cache
Clé par tenant ; sortie valide → passer à l’étape 6 ou 8
Microsoft Fabric
Étape 5: Interroger Fabric si nécessaire
Modèle approuvé, paramètres liés, délai maximal
Uniquement en cas de cache miss
Moteur de rapports
Étape 6: Construire le résultat
Mettre les lignes en forme : JSON, CSV ou Parquet
Compte de stockage
Étape 7: Stocker et mettre en cache
Écrire dans le dossier du tenant avec un TTL
Moteur de rapports
Étape 8: Renvoyer la réponse
Corps JSON ou lien de téléchargement de courte durée
Le client atteint API Management ou une passerelle, qui établit l’identité, les limites de taille des demandes et une limitation de débit globale. Le moteur de rapports applique l’autorisation du rapport, la validation du tenant, la validation des paramètres et des limites de charge plus fines avant tout travail de requête. Pour le contexte général, Qu’est-ce qu’un moteur de rapports ? décrit ses responsabilités.
Décision de cache
- DemandeValidée, tenant identifié
- Clé de cache
tenantrapportparamètresformatversion - RechercheDans
report-cache, sous{tenant}/{report}/… - En cache et encore valide ?Avant l’expiration du TTL du rapport
Oui Résultat en cache
- Réautoriser cet appelant
- Lire la sortie stockée
- Renvoyer le résultat
Non Absence dans le cache
- Interroger Fabric (modèle approuvé)
- Générer la sortie : JSON, CSV ou Parquet
- Stocker sous le chemin du tenant, avec un TTL
- Renvoyer le résultat
Isolation par tenant : même rapport, mêmes paramètres, tenants distincts
- contoso
contoso · sales-by-region · 2026-09 · csv · v3report-cache/contoso/sales-by-region/… - fabrikam
fabrikam · sales-by-region · 2026-09 · csv · v3report-cache/fabrikam/sales-by-region/…
Deux clés, deux dossiers : aucun partage.
Construisez une clé de cache canonique à partir de l’identité fiable du tenant, du type de rapport, de la période normalisée, des dimensions, des filtres, du format et de la version du rapport. La même demande logique et sûre produit la même clé. Un résultat trouvé en cache reste soumis à autorisation. En cas de cache miss, la demande passe à la couche de requêtes contrôlée et peut mettre en cache le résultat final avec un TTL et des métadonnées de fraîcheur. Rapports précalculés ou requêtes en direct : comment choisir examine quand servir des résultats stockés.
Requête et résultat
La couche de requêtes sélectionne un modèle de requête approuvé pour Fabric Warehouse ou le SQL analytics endpoint d’un Lakehouse et lie les valeurs validées. Le générateur de résultats applique les limites de lignes et d’octets, produit du JSON, du CSV, du Parquet ou un autre format autorisé, et stocke les artefacts volumineux dans un stockage privé. Les URL de téléchargement ont une durée de vie courte et sont vérifiées par rapport à l’identité du tenant.
Observabilité
Enregistrez request_id, correlation_id, tenant_id, client_id, api_key_id, report_name, requested_at, started_at, completed_at, duration_ms, cache_hit, query_duration_ms, rows_returned, output_bytes, status et error_code. Ces champs se rattachent directement au pilier de supervision et permettent d’analyser la capacité, la fiabilité, l’audit et les coûts. Mesurer le volume de requêtes API et de rapports montre comment les exploiter.
Gestion des échecs par étape
Une demande qui échoue doit dire à l’appelant quoi faire ensuite, et à l’exploitant où elle s’est arrêtée.
| Étape | Échec typique | Réponse | Enregistrement |
|---|---|---|---|
| Passerelle | Identifiants absents ou invalides ; consommateur au-delà de sa limite | 401, ou 429 avec Retry-After |
Identifiant du consommateur, limite atteinte |
| Autorisation | Appelant non autorisé pour ce locataire ou ce rapport | 403 | Appelant, locataire, rapport ; jamais les données qui auraient été renvoyées |
| Validation | Dimension inconnue, fin avant le début, limite de plage ou de lignes dépassée | 400 avec la règle en échec | La règle et le paramètre fautif, valeurs sensibles masquées |
| Cache | Entrée illisible ou partiellement écrite | Traiter comme une absence ; ne pas faire échouer la demande | Clé de cache, erreur de lecture |
| Requête | Délai dépassé, limitation de capacité, erreur de connexion transitoire | 503 ou 504, avec Retry-After quand une nouvelle tentative a du sens |
Modèle de requête, durée, code d’erreur, lignes lues si connues |
| Résultat | Sortie plus grande qu’autorisé ; échec d’écriture dans le stockage | 400 invitant à restreindre la demande ou à passer par un export ; 500 pour un échec de stockage | Lignes et octets produits, chemin de stockage |
Deux règles rendent ce tableau fiable. Renvoyez un échec de validation avant toute requête, pour qu’une mauvaise demande ne coûte rien. Et fixez le délai de requête plus court que celui de la passerelle, pour que ce soit le moteur, et non la passerelle, qui décide de ce que reçoit l’appelant.
Quand passer à une demande asynchrone
Si un rapport peut durer plus longtemps que ce que le client ou la passerelle acceptent d’attendre, renvoyez une tâche au lieu de garder la connexion ouverte. Le modèle Requête-Réponse asynchrone décrit l’échange :
POST /reports/revenue-by-channel/runs
→ 202 Accepted
Location: /reports/runs/7d1f…
Retry-After: 10
GET /reports/runs/7d1f…
→ 200 OK {"status": "running"}
GET /reports/runs/7d1f…
→ 303 See Other
Location: /reports/runs/7d1f…/result
La tâche porte le même identifiant de demande que l’appel initial, de sorte que le journal et le statut de la tâche décrivent une seule exécution. L’annulation doit arrêter la requête, pas seulement l’interrogation : un client qui abandonne ne doit pas laisser une requête tourner sur votre capacité.
Un enregistrement de journal par demande
{
"request_id": "7d1f…",
"correlation_id": "c41a…",
"tenant_id": "contoso",
"client_id": "partner-portal",
"report_name": "revenue-by-channel",
"report_version": 3,
"stage_reached": "result",
"status": "succeeded",
"cache_hit": false,
"requested_at": "2026-11-06T08:14:03.120Z",
"completed_at": "2026-11-06T08:14:05.902Z",
"duration_ms": 2782,
"query_duration_ms": 2410,
"rows_returned": 3120,
"output_bytes": 188416,
"error_code": null
}
stage_reached est le champ qui transforme un nombre d’échecs en diagnostic : un pic d’échecs à la validation est un problème client ; à la requête, un problème de capacité ou d’entrepôt ; au résultat, un problème de taille ou de stockage. Mesurer le volume de requêtes API et de rapports montre comment agréger ces enregistrements.
Voir aussi
- Qu’est-ce qu’un moteur de rapports ?
- Rapports précalculés ou requêtes en direct
- Construire un moteur de rapports multi-locataire sur Azure et Microsoft Fabric, sections 13 (génération asynchrone) et 14 (une demande de bout en bout)
- Report engine architecture reference (en anglais)
Sources
- Azure Architecture Center : modèle Requête-Réponse asynchrone, modèle de limitation, modèle Nouvelle tentative
- Microsoft Learn : stratégie rate-limit-by-key (réponses 429), vue d’ensemble des SAS
Vérifié en novembre 2026. Les codes de statut suivent les usages HTTP courants ; alignez-les sur les conventions de votre API.
Ce contenu vous a-t-il été utile ?
Que pourrions-nous améliorer ?
Merci — cela m’aide à améliorer Javi Builds.
Continuer à apprendre
- Aide-mémoireContenu en anglaisMicrosoft Fabric Workspace Settings Cheat SheetThe Microsoft Fabric workspace settings that change how a data engineering workspace behaves: Spark pools, environments and jobs, domain assignment, OneLake shortcut caching and diagnostics, and data workflow (Apache Airflow job) runtime pools, with what to verify for each.Ouvrir l’aide-mémoire
- ArticleConcevoir un moteur de rapports pour les consommateurs d’interface et d’APIConcevez un backend de rapports unique et gouverné pour les pages d’interface interactives, les API externes, les téléchargements et les gros exports asynchrones.Lire l’article
Que devrais-je créer ensuite ?
Je développe Javi Builds autour des problèmes concrets rencontrés par les data engineers. Dites-moi quel sujet vous aimeriez voir ensuite.
Restez au courant
Recevez uniquement les nouvelles de Javi Builds qui vous intéressent.
Consultez votre boîte de réception
Je vous ai envoyé un lien de confirmation. Votre abonnement sera actif après confirmation.