Autenticación
Un solo esquema protege cada operación: un token bearer en el encabezado
Authorization.
403 al crear uno. Los fallos responden con application/problem+json, así que analiza el documento de error en lugar de basarte solo en la línea de estado.
El token también lleva el ámbito de aislamiento de la llamada. Reporter lo resuelve a partir de la credencial misma, de modo que ninguna operación toma un encabezado de ámbito desde tu cliente, y ningún encabezado amplía lo que un token ya permite.
URL base
La ruta base es
/v1, sin ningún segmento de producto delante. Cada ruta de esta página se agrega a esa base:
multipart/form-data, porque una plantilla es un archivo .tpl. La creación de informes es application/json. Una descarga transmite los bytes renderizados con el Content-Type del formato de salida y un nombre de archivo Content-Disposition.
Las operaciones de listado toman limit y page, con valores predeterminados de 10 y 1. La página más grande es MAX_PAGINATION_LIMIT, que cada despliegue configura y que por defecto es 100. Un limit por encima de ese límite se rechaza, no se reduce.
Tu primera llamada
1
Confirma el token y la URL base
200 con una lista de plantillas confirma ambos. Un 401 señala el token. Un 404 señala la URL base.2
Solicita un informe
201 con el informe en estado Processing. La generación se ejecuta de forma asíncrona.3
Espera un estado terminal y luego descarga
Finished.X-Idempotency en cada solicitud de informe, y en la carga de plantillas por la misma razón. Si repites una solicitud que todavía está en curso, obtienes un error en lugar de un segundo informe. Si repites una que ya terminó, Reporter reproduce el informe original y marca la respuesta con X-Idempotency-Replayed: true. Deriva la clave de tu propio identificador de solicitud y un reintento no cuesta nada.
Un informe se crea una vez y se conserva: crear, obtener, listar y descargar son sus cuatro operaciones. Cuánto tiempo vive un archivo renderizado es una política de ciclo de vida del bucket de almacenamiento, no una llamada a la API.
Gestión de fuentes de datos
La API gestiona el registro persistente de fuentes de datos. Úsala para listar o crear conexiones, obtener o actualizar parcialmente una por
dataSourceId, inspeccionar su esquema en vivo, probarla o eliminarla de forma lógica:
configName estable que las plantillas referencian. Las respuestas nunca contienen contraseñas. Obtén una por identificador con /v1/data-sources/{dataSourceId} e inspecciona sus tablas o colecciones en vivo con /v1/data-sources/{dataSourceId}/schema.
El SDK de Go
lerian-sdk-golang incluye un paquete reporter junto con los demás productos de Lerian. Es una capa de conveniencia sobre las llamadas anteriores para el trabajo con plantillas e informes. Adquiere un token OAuth2 de credenciales de cliente, lo renueva y devuelve resultados tipados e iteradores paginados.
Configúralo con la misma URL base https://<host>/v1 que usas con cURL. Agrega el ID de cliente, el secreto de cliente, la URL de token de tu servidor de autorización y un tiempo de espera de solicitud.
Download devuelve los bytes renderizados en el formato propio del informe. Escríbelos en disco, como arriba, o transmítelos a quien te llamó.
El SDK cubre una parte del producto, no todo. Incluye crear, obtener, listar y eliminar plantillas, y crear, obtener, listar y descargar informes. Las fuentes de datos, la actualización de plantillas, los plazos, el generador de plantillas, las métricas y el manifiesto de streaming son llamadas REST. Combinar ambos en una misma integración es normal: usa el paquete donde encaje y HTTP simple en todo lo demás.
Ejecutar Reporter detrás de tu propio servicio
Reporter es un servicio que despliegas, no una biblioteca que enlazas. Para ponerlo detrás de una aplicación que tus clientes ya usan, mantén las credenciales de tu lado y llama a Reporter de servidor a servidor. Cuatro reglas mantienen ese límite claro. Nunca entregues un token de Reporter a un navegador. Tu servicio autentica a tu usuario y decide si ese usuario puede ejecutar este informe. Luego hace la llamada con su propio token. Responde de inmediato con un identificador. La creación del informe devuelve el estado
Processing. Devuelve ese identificador a quien te llamó y deja que tu propio endpoint de estado exponga el progreso.
Entérate de la finalización una sola vez. Consulta GET /v1/reports/{id} con un intervalo moderado, o suscríbete a los eventos de informes de Reporter y deja de consultar. Consulta Eventos de Reporter.
Haz de proxy en la descarga. El endpoint de descarga transmite los bytes a un solicitante autenticado, así que tu servicio los obtiene y los vuelve a servir bajo su propia autenticación.
Un informe
Partial significa que algunas secciones de datos fallaron mientras otras tuvieron éxito, y sus metadatos nombran las secciones que fallaron. Trátalo como una señal sobre una fuente de datos o un filtro, y decide en tu propio servicio qué se recomienda que vean tus usuarios.Próximos pasos
API REST de Reporter
Cada operación, agrupada según la tarea que hace.
Eventos de Reporter
El contrato de eventos, y cómo suscribirte en lugar de consultar repetidamente.
Inicio rápido de la API
Carga una plantilla y genera un informe con cURL.
Lista de errores
Los códigos de error de Reporter y qué los resuelve.