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.

Por JaviPublicado Actualizado 7 min de lecturaIntermedio

Ciclo de vida de una solicitud de informe, desde la autenticación hasta la ejecución y el monitoreo

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

  1. API Management

    Paso 1: Recibir la solicitud

    Asignar un ID de solicitud y aceptar un ID de correlación

  2. Motor de informes

    Paso 2: Validar la solicitud

    Informe, formato, intervalo de fechas, límites de filas y bytes

  3. Motor de informes

    Paso 3: Resolver tenant y seguridad

    Tenant a partir de claims confiables; autorizar informe y filtros

  4. Cuenta de almacenamiento

    Paso 4: Consultar la caché

    Clave por tenant; salida vigente → pasar al paso 6 u 8

  5. Microsoft Fabric

    Paso 5: Consultar Fabric si hace falta

    Plantilla aprobada, parámetros enlazados, tiempo límite

    Solo si no está en caché

  6. Motor de informes

    Paso 6: Generar el resultado

    Convertir las filas en JSON, CSV o Parquet

  7. Cuenta de almacenamiento

    Paso 7: Guardar la salida en caché

    Escribir en la carpeta del tenant con un TTL

  8. Motor de informes

    Paso 8: Devolver la respuesta

    Cuerpo JSON o enlace de descarga de corta duración

El ciclo de vida de una solicitud de informe. Los pasos 1 a 4 se ejecutan siempre; el paso 5 solo cuando no hay resultado en caché; cada solicitud termina con una salida almacenada o reutilizada y una respuesta que incluye su ID de solicitud.

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é

  1. SolicitudValidada, tenant identificado
  2. Clave de cachétenantinformeparámetrosformatoversión
  3. BuscarEn report-cache, bajo{tenant}/{report}/…
  4. ¿Está en caché y sigue vigente?Dentro del TTL del informe

Sí Acierto de caché

  1. Volver a autorizar a este solicitante
  2. Leer la salida almacenada
  3. Devolver el resultado

No Sin resultado en caché

  1. Consultar Fabric (plantilla aprobada)
  2. Generar la salida: JSON, CSV o Parquet
  3. Guardar en la ruta del tenant con un TTL
  4. Devolver el resultado

Aislamiento por tenant: mismo informe, mismos parámetros, distintos tenants

  • 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/…

Dos claves, dos carpetas: no se comparten.

Acierto o ausencia en caché. El tenant es la primera parte de la clave de caché y de la ruta de almacenamiento, por lo que dos tenants que solicitan el mismo informe con los mismos parámetros nunca comparten una entrada. El resultado en caché también requiere autorización; si no existe, se consulta Fabric y se guarda la nueva salida para la siguiente solicitud.

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

Fuentes

Revisado en noviembre de 2026. Los códigos de estado siguen la práctica HTTP habitual; alinéalos con las convenciones de tu API.

Etiquetas

  • Arquitectura de datos
  • API
  • Informes
  • Microsoft Fabric
  • Caché
  • Multiinquilino
  • Observabilidad