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.

Par JaviPublié Mis à jour 7 min de lectureIntermédiaire

Cycle de vie d’une demande de rapport, de l’authentification à l’exécution et à la supervision

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

  1. API Management

    Étape 1: Recevoir la demande

    Attribuer un ID de demande, accepter un ID de corrélation

  2. Moteur de rapports

    Étape 2: Valider la demande

    Rapport, format, période, limites de lignes et d’octets

  3. Moteur de rapports

    Étape 3: Résoudre tenant et sécurité

    Tenant issu de claims fiables ; autoriser rapport et filtres

  4. Compte de stockage

    Étape 4: Consulter le cache

    Clé par tenant ; sortie valide → passer à l’étape 6 ou 8

  5. 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

  6. Moteur de rapports

    Étape 6: Construire le résultat

    Mettre les lignes en forme : JSON, CSV ou Parquet

  7. Compte de stockage

    Étape 7: Stocker et mettre en cache

    Écrire dans le dossier du tenant avec un TTL

  8. Moteur de rapports

    Étape 8: Renvoyer la réponse

    Corps JSON ou lien de téléchargement de courte durée

Le cycle de vie d’une demande de rapport. Les étapes 1 à 4 s’exécutent toujours ; l’étape 5 seulement en cas de cache miss ; chaque demande se termine par une sortie stockée ou réutilisée et une réponse qui porte son ID de demande.

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

  1. DemandeValidée, tenant identifié
  2. Clé de cachetenantrapportparamètresformatversion
  3. RechercheDans report-cache, sous{tenant}/{report}/…
  4. En cache et encore valide ?Avant l’expiration du TTL du rapport

Oui Résultat en cache

  1. Réautoriser cet appelant
  2. Lire la sortie stockée
  3. Renvoyer le résultat

Non Absence dans le cache

  1. Interroger Fabric (modèle approuvé)
  2. Générer la sortie : JSON, CSV ou Parquet
  3. Stocker sous le chemin du tenant, avec un TTL
  4. Renvoyer le résultat

Isolation par tenant : même rapport, mêmes paramètres, tenants distincts

  • contosocontoso · sales-by-region · 2026-09 · csv · v3report-cache/contoso/sales-by-region/…
  • fabrikamfabrikam · sales-by-region · 2026-09 · csv · v3report-cache/fabrikam/sales-by-region/…

Deux clés, deux dossiers : aucun partage.

Cache hit ou cache miss. Le tenant est le premier élément de la clé de cache et du chemin de stockage : deux tenants qui demandent le même rapport avec les mêmes paramètres ne partagent jamais une entrée. Un résultat en cache reste soumis à autorisation ; en cas de cache miss, Fabric est interrogé et la nouvelle sortie est stockée pour la prochaine demande.

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

Sources

Vérifié en novembre 2026. Les codes de statut suivent les usages HTTP courants ; alignez-les sur les conventions de votre API.

Étiquettes

  • Architecture de données
  • API
  • Rapports
  • Microsoft Fabric
  • Mise en cache
  • Multi-locataire
  • Observabilité