Cloud y automatización
Diseñar un motor de informes para consumidores de interfaz y de API
Diseña un único backend de informes gobernado para páginas de interfaz interactivas, API externas, descargas y grandes exportaciones asíncronas.
En este artículo
La mayoría de las plataformas de informes terminan con dos tipos de consumidor: personas que usan una interfaz web o móvil y sistemas que llaman a una API. Ambos quieren las mismas cifras de negocio, pero con una forma distinta. El objetivo del diseño es un único motor de informes que contenga la lógica de cada informe una sola vez y adapte solo la entrega a cada consumidor.
Un único backend
Siempre que sea posible, los consumidores de interfaz y de API usan el mismo motor de informes. El flujo interactivo va de la interfaz a la API, de ahí al motor de informes y termina en JSON o datos de página. La exportación va de la interfaz o la API a una solicitud de informe, un CSV o archivo generado y una URL de descarga protegida. Compartir la validación y la autorización evita que la interfaz y la API desarrollen reglas de datos contradictorias.
Lógica de informes compartida
La definición del informe pertenece al motor, no a ninguno de los consumidores: dimensiones y filtros permitidos, la plantilla de consulta aprobada, las reglas del intervalo de fechas, los límites de filas y el significado de cada medida. Tanto la interfaz como la API envían su intención a esa definición. Si la aplicación web calcula sus propios totales o aplica sus propios filtros, tarde o temprano la interfaz y la API discreparán sobre el mismo informe.
Evita implementaciones duplicadas de un mismo informe, como una consulta para el dashboard y otra para el endpoint de exportación. Los duplicados divergen: la corrección de un filtro o de una medida llega a un camino y no al otro, y los consumidores reciben respuestas distintas a la misma pregunta. Una sola definición con varios contratos de entrega es más fácil de probar, proteger y modificar.
Contratos por consumidor
Las pantallas interactivas necesitan paginación, ordenación estable, proyecciones compactas, cancelación y una latencia predecible. Las exportaciones necesitan selección de formato, límites más amplios, ejecución asíncrona, almacenamiento, caducidad y autorización de descarga. La misma definición lógica del informe puede atender ambos casos con contratos de entrega diferentes.
| Necesidad | Consumidor de interfaz | Consumidor de API |
|---|---|---|
| Forma de la respuesta | Página JSON compacta solo con las columnas visibles | Esquema completo y documentado |
| Tamaño | Páginas pequeñas para una pantalla | Páginas más grandes o una exportación a archivo |
| Latencia | Lo bastante rápida para una vista interactiva | Puede esperar a que termine una ejecución asíncrona |
| Formatos | JSON o datos de página | JSON, CSV u otro formato de archivo permitido |
| Vida útil | Se descarta cuando el usuario sale de la página | Resultado almacenado con caducidad y enlace de descarga |
Paginación y ordenación
La paginación mantiene las respuestas interactivas pequeñas y acotadas. Cada página debe salir de una ordenación estable, para que la misma solicitud devuelva las mismas filas en el mismo orden; añade una clave única como última columna de ordenación cuando la columna visible tenga empates. Acepta los campos de ordenación desde una lista permitida, igual que las dimensiones y los filtros, en lugar de pasar a una consulta un nombre de columna enviado por el cliente.
Los consumidores de API suelen necesitar el resultado completo y no una sola pantalla. Ofréceles páginas más grandes con la misma ordenación estable, o una exportación, en lugar de dejar que recorran miles de páginas pequeñas pensadas para la interfaz.
Validación
Convierte valores de agrupación como Date, Canal o Cuenta en un enum de valores permitidos. Valida las fechas de inicio y fin, el intervalo máximo, los filtros permitidos, el acceso al tenant, el formato y los límites de filas. El cliente envía su intención, nunca fragmentos de consulta. El backend usa instrucciones parametrizadas o generadores de consultas controlados.
Límites de autenticación y autorización
Los usuarios de la interfaz y los clientes de API se autentican de forma distinta: un usuario interactivo inicia sesión, mientras que una integración presenta una identidad de cliente o una clave de API. Ambos deben llegar a la misma decisión de autorización dentro del motor: a qué tenant pertenece el solicitante, qué informes puede ejecutar y qué filtros puede aplicar. Obtén la identidad del tenant a partir de claims autenticados o de una asignación confiable del servicio, nunca de un tenant_id enviado por el navegador o por el solicitante.
Las URL de descarga de resultados almacenados tienen una vida corta y se comprueban con el tenant que hace la solicitud. Registra un evento de auditoría para cada acceso a informes y mantén los secretos y los valores de filtros sensibles fuera de los logs ordinarios.
Reutilización de la caché
Como ambos consumidores llaman a un mismo motor, pueden compartir resultados en caché. Construye la clave de caché a partir de la identidad confiable del tenant, el tipo de informe, los parámetros normalizados, el formato y la versión del informe, para que la misma solicitud lógica desde la interfaz o desde la API llegue a la misma entrada. Incluye la identidad del tenant en todas las claves y autoriza un acierto de caché con el mismo rigor que una consulta nueva. La paginación y la ordenación cambian lo que devuelve una página, así que inclúyelas en la clave si guardas páginas en caché, o guarda el resultado completo y pagina sobre él.
Límites de solicitudes
Aplica los límites por consumidor a partir de la identidad autenticada: una ráfaga de llamadas de una integración no debería ralentizar a todos los usuarios interactivos. Las páginas interactivas y las grandes exportaciones también merecen presupuestos separados, porque una exportación puede costar tanto como muchas visitas a páginas. Devuelve una respuesta de limitación explícita con indicaciones en lugar de dejar que las solicitudes agoten el tiempo de espera, y deriva el trabajo pesado a la opción asíncrona que se describe a continuación. Cómo medir el volumen de solicitudes de API e informes explica cómo obtener las evidencias para fijar esos límites.
Opción asíncrona
Para trabajos grandes, POST /reports puede devolver 202 Accepted con un reportRequestId. GET /reports/{id} devuelve el estado y GET /reports/{id}/download devuelve un resultado autorizado de corta duración. Las solicitudes pequeñas y acotadas pueden seguir siendo síncronas; obligar a que todas las interacciones pasen por una cola de trabajos añade una complejidad innecesaria.
Compromisos y modos de fallo
Las solicitudes más flexibles son más útiles, pero amplían la superficie de seguridad y de rendimiento. Para cualquiera de los consumidores, prefiere contratos de informe explícitos y variaciones permitidas antes que una interfaz de consulta sin restricciones. Más caché reduce la carga de consultas, pero crea problemas de vigencia e invalidación que heredan ambos consumidores.
Ten en cuenta los éxitos parciales: un informe puede terminar después de que el solicitante se desconecte, y una escritura de caché puede fallar después de devolver un resultado válido. Modela esos casos de forma explícita y no permitas que una salida parcial se confunda con una exportación completa.
Preguntas para la revisión operativa
Antes de publicar, confirma que la interfaz y la API producen cifras idénticas para el mismo informe y los mismos parámetros, que ambos caminos pasan por la misma validación y autorización, y que un ID de solicitud conecta la pantalla de un usuario o una llamada de API con la ejecución correspondiente. Comprueba que los límites producen respuestas explícitas para ambos consumidores, que las exportaciones caducan según lo previsto y que un cambio en la definición de un informe llega a todos los consumidores a la vez. ¿Qué es un motor de informes? y Arquitectura de un motor de informes: de la solicitud al resultado completan la serie.
¿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ículoArquitectura de un motor de informes: de la solicitud al resultadoSigue 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.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.