Cómo gestionar reportes utilizando la API REST
Puedes usar las API REST para gestionar y automatizar tus reportes. Este artículo cubrirá los requisitos previos para usar REST con reportes, explicará los recursos REST y te dará algunos casos de uso reales.
Requisitos previos
Debes haber leído los siguientes artículos y completado la configuración dentro de ellos para gestionar reportes a través de las API REST.
- Habilitar API REST
- Generar el token de API REST
- Obtener un token de API y autorización REST
- Obtener UserID usando API REST
Recursos de reportes REST
Leer ReportTemplates | GET /applications/{applicationid:int}/reporttemplates |
Leer Reportes | GET /applications/{applicationid:int}/reports |
Leer Reporte | GET /applications/{applicationid:int}/reports/{reportid:long} |
Crear Reporte | POST /applications/{applicationid:int}/reports |
Actualizar Reporte | PUT /applications/{applicationid:int}/reports/{reportid:long} |
Eliminar Reporte | DELETE /applications/{applicationid:int}/reports/{reportid:long} |
Leer ReportFormats | GET /applications/{applicationid:int}/reports/formats |
Renderizar Reporte | POST /applications/{applicationid:int}/reports/{reportid:int}/renderings |
Leer RenderingStatus | GET /applications/{applicationid:int}/reports/{reportid:int}/renderings/{renderingid:long} |
Cancelar Renderización | DELETE /applications/{applicationid:int}/reports/{reportid:int}/renderings/{renderingid:long} |
Recursos REST explicados
ReportTemplates | GET /applications/{applicationid:int}/reporttemplates |
Plantillas de Reporte (también conocidas como Definiciones de Reporte) son los reportes predefinidos en GpsGate. Una lista de todas las Plantillas de Reporte está disponible aquí. Puedes usar el recurso ReportTemplates para verificar qué plantillas de reporte están disponibles en tu servidor. Similar a la mayoría de los otros recursos, cada entidad (plantilla de reporte en este caso) tiene un identificador (reportTemplateId) que puede usarse para referirse a una plantilla de reporte específica.
Leer Reporte | GET /applications/{applicationid:int}/reports |
Leer Reportes | GET /applications/{applicationid:int}/reports/{reportid:long} |
Los recursos de lectura de reporte y lectura de reportes son para obtener un reporte específico o todos los reportes respectivamente. La respuesta contiene todos los detalles del reporte. Las tablas 1, 2 y 3 a continuación proporcionan una breve explicación de cada campo.
Tabla 1: campos del reporte
id | ID del reporte |
applicationId | ID de la aplicación que posee el reporte |
definitionId | ID de la plantilla del reporte |
name | nombre del reporte |
description | descripción del reporte |
showParameters | una bandera que indica si los parámetros son visibles para los usuarios |
reportFormatId | ID de formato predeterminado del reporte |
parameters | parámetros del reporte: para verificar los parámetros de cada reporte, debe iniciar sesión en la Administración del sitio y verificar la plantilla del reporte (ver tabla 2) |
schedule | objeto utilizado para reportes programados (ver tabla 3) |
Tabla 2: parámetros
parameterName | nombre del parámetro |
value | una propiedad utilizada solo para parámetros periódicos (diario, semanal, mensual o personalizado debe especificarse) y parámetros de valor único (por ejemplo, HarshTurnPoints, SeatBeltPoints); se ignora si se especifica para otros parámetros |
visible | una bandera que indica si el parámetro es visible |
periodStart | marca de tiempo de inicio de un parámetro de período ("parameterName" = "Period"); se utiliza solo para el parámetro de período y se ignora si se especifica para otros parámetros |
periodEnd | marca de tiempo de finalización de un parámetro de período ("parameterName" = "Period"); se utiliza solo para el parámetro de período y se ignora si se especifica para otros parámetros |
arrayValues | utilizado solo para parámetros de arreglo (lista de TagIDs, EventRuleIDs, etc.) y se ignora si se especifica para otros parámetros |
timeSpan | utilizado solo para parámetros de TimeStamp y se ignora si se especifica para otros parámetros |
Tabla 3: programación
transport | ya sea Email o FileSave |
scheduleType | tipo de programación; ya sea DayOfMonth o WeeksAndDays |
dayOfMonth | solo se usa si scheduleType es dayOfMonth |
weekInMonth | solo se usa si scheduleType es WeeksAndDays |
daysInWeek | solo se usa si scheduleType es WeeksAndDays |
hours | la hora en que se activa la programación |
minutes | el minuto en que se activa la programación |
seconds | el segundo en que se activa la programación |
recipients | IDs de Usuarios para quienes se activa la programación |
reportFormatId | Ofrece la posibilidad de renderizar el reporte en un formato diferente al formato predeterminado del reporte cuando es activado por el programador. Consulte la sección 'Formatos de Reporte' de este artículo para más información. |
ignoreSendingBlank | ignora el resultado si no hay datos en el reporte para el período especificado |
Crear Reporte | POST /applications/{applicationid:int}/reports |
El modelo para crear un reporte es el mismo que se utiliza en los recursos Leer Reporte y Leer Reportes. Para más detalles, consulte la sección 'Leer Reporte y Leer Reportes' de este artículo.
Al crear un reporte, el ID debe ser cero o debe eliminarse de la solicitud. Aquí hay un ejemplo que crea un reporte similar al reporte en el ejemplo de 'Leer Reporte y Leer Reportes':
Actualizar Reporte | PUT /applications/{applicationid:int}/reports/{reportid:long} |
Actualizar reporte utiliza el mismo modelo que las operaciones obtener reporte(s) y crear reporte. El siguiente ejemplo muestra cómo actualizar el reporte que creamos en el último ejemplo.
Tenga en cuenta que no puede actualizar ReportID, ApplicationID y DefinitionID.
Eliminar Reporte | DELETE /applications/{applicationid:int}/reports/{reportid:long} |
La API de eliminar reporte es para eliminar un reporte. Eliminará el reporte especificado y todas sus dependencias. En este ejemplo, eliminamos el reporte que creamos en el último ejemplo.
Formatos de Reporte | GET /applications/{applicationid:int}/reports/formats |
Un reporte puede ser generado en diferentes formatos. Actualmente GpsGate soporta los formatos "HTML", "PDF", "CSV" y "CSV ZIP". Cada formato tiene un identificador (reportFormatId) en el sistema. Cuando generas un reporte, debes especificar el formato pasando el reportFormatId. Este recurso es para obtener todos los reportFormatIds disponibles. En el siguiente ejemplo, puedes ver que hay cuatro formatos de reporte disponibles en esta aplicación. Nota que estos reportFormatIds se utilizan más adelante cuando activamos la generación de un reporte.
Generar Reporte | POST /applications/{applicationid:int}/reports/{reportid:int}/renderings |
El recurso de generación es para generar un reporte. Al generar un reporte, se pueden especificar nuevos parámetros que dan la posibilidad de generar un reporte con diferentes parámetros a los predeterminados. También es posible enviar por correo electrónico el resultado de la generación especificando una dirección de correo electrónico en el modelo y configurando la bandera "sendEmail" a "true" como se especifica en la siguiente figura. En este ejemplo, el reporte se enviará a support@gpsgate.com cuando esté listo. Nota que también podemos solicitar la generación en un formato diferente al formato predeterminado del reporte configurando "reportFormatId" a nuestro formato deseado.
El modelo de respuesta de una solicitud de generación es el mismo que la respuesta del recurso de obtención de generación. Contiene una propiedad ID que se utiliza para verificar el estado de esta generación. Consulta la sección 'Leer estado de generación' de este artículo para más detalles.
Leer estado de generación |
GET /applications/{applicationid:int}/reports/{reportid:int}/renderings/{renderingid:long} |
En el ejemplo anterior, el RenderID en la respuesta fue 1677 ("id": 1677). En esta API, usamos este id para verificar el estado de nuestra generación solicitada.
La respuesta contiene detalles sobre el estado de la generación como se muestra a continuación.
Tabla 4: definiciones de cada campo de la respuesta
reportID | el ID del reporte |
isReady | una bandera que indica si el resultado de la renderización está listo (es verdadero cuando los datos están procesados y el archivo está renderizado) |
outputFile | un enlace al archivo de resultado en su servidor (esto está disponible cuando la bandera isReady está establecida) |
percentage | el porcentaje de trabajo completado (el 90% del trabajo se asigna al procesamiento de datos y el 10% restante a la renderización) |
currentStep | el paso actual en ejecución |
steps | el número total de pasos |
reportFormatId | ID de formato solicitado (para más detalles, consulte la sección 'Formatos de Reporte' de este artículo) |
parameters | el conjunto de parámetros para los cuales se activa la renderización (consulte la sección 'Leer Reporte & Leer Reportes' para más detalles sobre el modelo de parámetros) |
id | identificador de renderización; obtenido de la respuesta de la solicitud 'renderizar reporte' |
Cancelar renderización | DELETE /applications/{applicationid:int}/reports/{reportid:int}/renderings/{renderingid:long} |
Cancelar renderización es para cancelar una solicitud de renderización en curso. Las solicitudes a este recurso para renderizaciones finalizadas son ignoradas.