Autenticación
Un solo esquema protege cada operación: un token bearer en la cabecera
Authorization.
403 al crear. Los fallos responden application/problem+json, así que analiza el documento de problema en lugar de quedarte con la línea de estado sola.
El token también lleva el alcance de aislamiento de la llamada. Reporter lo resuelve desde la propia credencial, así que ninguna operación toma una cabecera de alcance de tu cliente y ninguna cabecera 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 añade a eso:
multipart/form-data, porque una plantilla es un archivo .tpl. La creación de un informe es application/json. Una descarga transmite los bytes renderizados con el Content-Type del formato de salida y un nombre de archivo en Content-Disposition.
Las operaciones de listado aceptan limit y page, 10 y 1 por defecto. La página más grande es MAX_PAGINATION_LIMIT, que cada despliegue define y cuyo valor por defecto es 100. Un limit por encima de ese techo se rechaza, no se reduce.
Tu primera llamada
1
Confirma el token y la URL base
200 con una lista de plantillas prueba los dos. Un 401 señala el token; un 404, la URL base.2
Pide un informe
201 con el informe en Processing. La generación corre de forma asíncrona.3
Espera un estado terminal y descarga
Finished.X-Idempotency en cada solicitud de informe, y en la subida de una plantilla por la misma razón. Si repites una solicitud que todavía corre, 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 te cuesta nada.
Un informe se crea una vez y se conserva: crear, obtener, listar y descargar son sus cuatro operaciones. Cuánto vive un archivo renderizado es una política de ciclo de vida sobre el bucket de almacenamiento, no una llamada de la API.
Lectura de fuentes de datos
Un operador configura las fuentes de datos por variables de entorno, así que la API sobre ellas es de solo lectura. Úsala para descubrir a qué pueden hacer referencia tus plantillas:
/v1/data-sources/{dataSourceId}.
El SDK de Go
lerian-sdk-golang trae un paquete reporter junto a los demás productos de Lerian. Es una comodidad sobre las llamadas anteriores para el trabajo con plantillas e informes: obtiene un token OAuth2 de client credentials, lo refresca y devuelve resultados tipados e iteradores paginados.
Configúralo con la misma URL base https://<host>/v1 que usas con cURL, más el client ID, el client secret y la URL de token de tu servidor de autorización, y un timeout de solicitud.
Download devuelve los bytes renderizados en el formato del propio informe. Escríbelos en disco, como arriba, o transmítelos a quien te llama.
El SDK cubre una parte del producto, no todo. Trae crear, obtener, listar y borrar plantillas, y crear, obtener, listar y descargar informes. Las fuentes de datos, la actualización de plantillas, los plazos, el constructor de plantillas, las métricas y el manifiesto de streaming son llamadas REST. Mezclar los dos en una sola integración es normal y esperado: el paquete donde encaja, y HTTP plano 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, guarda las credenciales de tu lado y llama a Reporter de servidor a servidor. Cuatro reglas mantienen limpio ese límite. Nunca entregues un token de Reporter a un navegador. Tu servicio autentica a tu usuario, decide si ese usuario puede ejecutar este informe y después hace la llamada con su propio token. Responde de inmediato con un identificador. La creación de un informe vuelve en
Processing. Devuelve ese identificador a quien te llama y deja que tu propio endpoint de estado exponga el progreso.
Entérate del final una sola vez. Consulta GET /v1/reports/{id} en un intervalo moderado, o suscríbete a los eventos de informe de Reporter y deja de sondear. Mira Eventos de Reporter.
Haz de proxy en la descarga. El endpoint de descarga transmite bytes a un llamador autenticado, así que tu servicio los obtiene y los vuelve a servir bajo su propia autenticación.
Un informe en
Partial significa que algunas secciones de datos fallaron mientras otras tuvieron éxito, y sus metadatos nombran las que fallaron. Trátalo como una señal sobre una fuente de datos o sobre un filtro, y decide en tu propio servicio qué deben ver tus usuarios.Próximos pasos
API REST de Reporter
Cada operación, agrupada por el trabajo que hace.
Eventos de Reporter
El contrato de eventos, y cómo suscribirte en lugar de sondear.
Inicio rápido de la API
Sube una plantilla y genera un informe con cURL.
Lista de errores
Los códigos de error de Reporter y qué los resuelve.