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.

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.
ReportTemplates_Response.PNG

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.

GetReport_Response.PNG

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':

Screenshot_2021-05-28_at_13.17.51.pngCreateReport_Response.PNG

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.

UpdateReport_Request.PNGUpdateReport_Response.PNG

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.

DeleteReport_Request.PNGDeleteReport_Response.PNG

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.

ReportFormats_Request.PNGReportFormats_Response.PNG

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.

CreateRendering_Request.PNG

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.

CreateRendering_Response.PNG

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.

GetRendering_Request.PNG

La respuesta contiene detalles sobre el estado de la generación como se muestra a continuación.

GetReport_Response.PNG

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.

CancelRendering_Request.PNGCancelRendering_Response.PNG