APIs de extracción de datos
Introducción
Esta sección explica cómo extraer datos de la plataforma Gear Studio utilizando la API HTTP, como por ejemplo:
- Alertas: la API permite extraer la definición de todas las alertas creadas en la plataforma, filtrándolas de diferentes formas.
- Alarmas: la API permite extraer todas las alarmas registradas en la plataforma, en forma histórica, filtrándolas de diferentes formas.
- Datos de endpoints: la API permite extraer toda la información asociada a los endpoints, en forma histórica, filtrándola de diferentes formas.
- Geozonas: la API permite extraer la lista de geozonas configuradas para cada cliente, incluyendo la lista de vehículos contenidos en ellas.
Primeros pasos
Creación de un access token
Al igual que con cualquier otra integración por HTTP, será necesario crear un token de acceso (access token). Esta página contiene más información sobre la administración de tokens de acceso. Los access tokens permiten controlar el acceso y los permisos utilizados para cualquier operación.
Autentificación mediante un access token
En todas las APIs es posible enviar el access token como parte del encabezado, utilizando un encabezado Authorization, como se ve a continuación:
Authorization: Bearer {accessToken}Alternativamente, cuando no es posible enviar el token a través del encabezado Authorization, el access token puede enviarse como parte de la url, a través del parámetro “accessToken”, como en el siguiente ejemplo:
https://gear.cloud.studio/api/v2/alarms?accessToken={accessToken}&clientID=4&maxCount=10Ejecución de la API
Para ejecutar la API, revise cada una de las secciones siguientes, que contienen la información relacionada:
- Extracción de alertas.
- Extracción de alarmas.
- Extracción de datos de endpoints.
- Extracción de datos de geozonas.
Reversibilidad de las operaciones
- La API de extracción (
/api/v2: alertas, alarmas, datos de endpoints, geozonas y mapa de la instancia) es de solo lectura. Ninguna llamada cambia datos de la plataforma. - La única escritura documentada es la creación de access tokens persistentes (
CreateClientAccessTokenAllIntegrations). Se deshace conDeleteClientAccessToken, usando elClientAccessTokenIDque devolvió la creación, y el token queda revocado de inmediato. - Reintentar la creación con la misma
Descriptionno crea un segundo token: devuelve un error de descripción duplicada. - Revocar un token no borra ningún dato. Solo deja de dar acceso.
Errores
Cuando una llamada falla, la API responde con el código HTTP 500 y un cuerpo JSON con este formato, sea cual sea la causa del error (token inválido, permiso insuficiente o parámetro incorrecto):
{
"Exception": {
"ClassName": "ServiceException",
"FaultCode": "8001",
"FaultData": "",
"Message": "Texto descriptivo del error"
}
}- FaultCode: código numérico del error. Es estable entre versiones y es el campo que debe usar una integración para decidir qué hacer.
- Message: descripción del error para una persona. Puede cambiar de redacción y se devuelve traducida, así que no conviene que una integración dependa de su texto.
- FaultData: datos adicionales del error. Suele venir vacío.
Los códigos más habituales son:
| FaultCode | Significado | Qué hacer |
|---|---|---|
| 8001 | Falta el access token, no existe o ha caducado | Revisar el token o crear uno nuevo |
| 8002 | El access token es válido, pero su cuenta está deshabilitada | Reactivar la cuenta o usar el token de otra cuenta |
| 8000 | El token no tiene permiso para esta API | Crear el token con una cuenta que tenga ese permiso |
| 8004 | El token no tiene permiso sobre el recurso pedido (cliente, facility, dispositivo o endpoint) | Pedir solo recursos a los que la cuenta tiene acceso |
| 100000 | Falta un dato obligatorio | Revisar los parámetros de la llamada |
| 100004 | Un parámetro tiene un valor no válido o supera un límite | Revisar el valor indicado en Message |
| 100001 | Error inesperado en el servidor | Reintentar más tarde; si persiste, contactar con soporte |
Los errores 8000, 8001, 8002, 8004, 100000 y 100004 no se solucionan reintentando la misma llamada: primero hay que corregir la petición o el token.
Última actualización
Personalización de Exportación de Reportes
Cómo personalizar el asunto y el cuerpo del correo de un reporte programado, el nombre del adjunto y su encabezado y pie de página.
Alertas
Cómo consultar con la API la definición de las alertas creadas en Gear Studio, las condiciones que generan alarmas, por ID o por parámetros.