Cloud y automatización
Arquitectura de un motor de informes: de la solicitud al resultado
Sigue una solicitud de informe a través de la pasarela, la seguridad, la validación, la caché, la consulta a Fabric, la generación del resultado y el monitoreo.
En este artículo
Respuesta corta: una solicitud de informe pasa por seis etapas: puerta de enlace, autorización, validación, búsqueda en caché, consulta y entrega del resultado. Cada etapa debe fallar con su propia respuesta explícita y dejar un registro de log que la identifique. Las respuestas síncronas sirven para informes pequeños y rápidos; todo lo que pueda superar un tiempo de espera HTTP debe convertirse en un trabajo asíncrono que el cliente consulta.
Ciclo de vida de la solicitud
API Management
Paso 1: Recibir la solicitud
Asignar un ID de solicitud y aceptar un ID de correlación
Motor de informes
Paso 2: Validar la solicitud
Informe, formato, intervalo de fechas, límites de filas y bytes
Motor de informes
Paso 3: Resolver tenant y seguridad
Tenant a partir de claims confiables; autorizar informe y filtros
Cuenta de almacenamiento
Paso 4: Consultar la caché
Clave por tenant; salida vigente → pasar al paso 6 u 8
Microsoft Fabric
Paso 5: Consultar Fabric si hace falta
Plantilla aprobada, parámetros enlazados, tiempo límite
Solo si no está en caché
Motor de informes
Paso 6: Generar el resultado
Convertir las filas en JSON, CSV o Parquet
Cuenta de almacenamiento
Paso 7: Guardar la salida en caché
Escribir en la carpeta del tenant con un TTL
Motor de informes
Paso 8: Devolver la respuesta
Cuerpo JSON o enlace de descarga de corta duración
El cliente llega a API Management o a una pasarela, que establece la identidad, los límites de tamaño de la solicitud y una limitación de frecuencia general. El motor de informes aplica la autorización del informe, la validación del tenant, la validación de parámetros y límites de carga más precisos antes de iniciar cualquier consulta. Si necesitas el contexto general, ¿Qué es un motor de informes? describe sus responsabilidades.
Decisión de caché
- SolicitudValidada, tenant identificado
- Clave de caché
tenantinformeparámetrosformatoversión - BuscarEn
report-cache, bajo{tenant}/{report}/… - ¿Está en caché y sigue vigente?Dentro del TTL del informe
Sí Acierto de caché
- Volver a autorizar a este solicitante
- Leer la salida almacenada
- Devolver el resultado
No Sin resultado en caché
- Consultar Fabric (plantilla aprobada)
- Generar la salida: JSON, CSV o Parquet
- Guardar en la ruta del tenant con un TTL
- Devolver el resultado
Aislamiento por tenant: mismo informe, mismos parámetros, distintos tenants
- 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/…
Dos claves, dos carpetas: no se comparten.
Construye una clave de caché canónica a partir de la identidad confiable del tenant, el tipo de informe, el intervalo de fechas normalizado, las dimensiones, los filtros, el formato y la versión del informe. La misma solicitud lógica y segura produce la misma clave. Un acierto de caché también requiere autorización. Si no hay resultado en caché, la solicitud continúa hacia la capa de consultas controlada y puede guardar el resultado terminado con un TTL y metadatos de vigencia. Informes precalculados o consultas en tiempo real: cómo elegir analiza cuándo conviene servir resultados almacenados.
Consulta y resultado
La capa de consultas selecciona una plantilla de consulta aprobada para Fabric Warehouse o para el SQL endpoint de un Lakehouse y enlaza los valores validados. El generador de resultados aplica los límites de filas y bytes, produce JSON, CSV, Parquet u otro formato permitido y guarda los artefactos grandes en almacenamiento privado. Las URL de descarga tienen una vida corta y se comprueban con la identidad del tenant.
Observabilidad
Registra 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 y error_code. Estos campos se conectan directamente con el pilar de monitoreo y permiten analizar capacidad, fiabilidad, auditoría y costos.
Gestión de fallos por etapa
Una solicitud que falla debe decirle al llamante qué hacer a continuación y al operador dónde se detuvo.
| Etapa | Fallo típico | Respuesta | Registro |
|---|---|---|---|
| Puerta de enlace | Credenciales ausentes o no válidas; consumidor por encima de su límite | 401, o 429 con Retry-After |
ID del consumidor, límite alcanzado |
| Autorización | Llamante sin permiso para este tenant o informe | 403 | Llamante, tenant, informe; nunca los datos que se habrían devuelto |
| Validación | Dimensión desconocida, fin anterior al inicio, límite de rango o de filas superado | 400 con la regla que falló | La regla y el parámetro culpable, con los valores sensibles ocultos |
| Caché | Entrada ilegible o escrita a medias | Tratar como fallo de caché; no hacer fallar la solicitud | Clave de caché, error de lectura |
| Consulta | Tiempo de espera agotado, limitación de capacidad, error de conexión transitorio | 503 o 504, con Retry-After cuando reintentar tiene sentido |
Plantilla de consulta, duración, código de error, filas leídas si se conocen |
| Resultado | Salida mayor de lo permitido; fallo al escribir en el almacenamiento | 400 indicando que se acote la solicitud o se use una exportación; 500 si falla el almacenamiento | Filas y bytes producidos, ruta de almacenamiento |
Dos reglas hacen fiable esta tabla. Devuelve el fallo de validación antes de ejecutar ninguna consulta, para que una solicitud incorrecta no cueste nada. Y fija el tiempo de espera de la consulta por debajo del de la puerta de enlace, para que sea el motor, y no la puerta de enlace, quien decida qué recibe el llamante.
Cuándo pasar a una solicitud asíncrona
Si un informe puede tardar más de lo que el cliente o la puerta de enlace están dispuestos a esperar, devuelve un trabajo en lugar de mantener la conexión abierta. El patrón de solicitud-respuesta asíncrona describe el intercambio:
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
El trabajo lleva el mismo ID de solicitud que la llamada original, de modo que el log y el estado del trabajo describen una sola ejecución. La cancelación debe detener la consulta, no solo el sondeo: un cliente que se rinde no debe dejar una consulta corriendo sobre tu capacidad.
Un registro de log por solicitud
{
"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 es el campo que convierte un recuento de fallos en un diagnóstico: un pico de fallos en la validación es un problema del cliente; en la consulta, de capacidad o del almacén; en el resultado, de tamaño o de almacenamiento. Cómo medir el volumen de solicitudes de API e informes muestra cómo agregar estos registros.
Relacionado
- ¿Qué es un motor de informes?
- Informes precalculados o consultas en tiempo real
- Construir un motor de informes multi-tenant en Azure y Microsoft Fabric, secciones 13 (generación asíncrona) y 14 (una solicitud de extremo a extremo)
- Report engine architecture reference (en inglés)
Fuentes
- Azure Architecture Center: patrón de solicitud-respuesta asíncrona, patrón de limitación, patrón de reintento
- Microsoft Learn: directiva rate-limit-by-key (respuestas 429), información general sobre SAS
Revisado en noviembre de 2026. Los códigos de estado siguen la práctica HTTP habitual; alinéalos con las convenciones de tu API.
¿Te resultó útil este contenido?
¿Qué podríamos mejorar?
Gracias — esto me ayuda a mejorar Javi Builds.
Sigue aprendiendo
- Guía rápidaContenido en inglésMicrosoft 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.Abrir guía rápida
- ArtículoDiseñar un motor de informes para consumidores de interfaz y de APIDiseña un único backend de informes gobernado para páginas de interfaz interactivas, API externas, descargas y grandes exportaciones asíncronas.Leer artículo
¿Qué debería crear después?
Estoy construyendo Javi Builds alrededor de problemas reales que enfrentan los ingenieros de datos. Dime qué tema te gustaría ver después.
Mantente al día
Recibe solo las novedades de Javi Builds que realmente te interesan.
Revisa tu bandeja de entrada
Te he enviado un enlace de confirmación. Tu suscripción se activará cuando la confirmes.