Saltar al contenido principal
CloudStudio

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=10

Ejecución de la API

Para ejecutar la API, revise cada una de las secciones siguientes, que contienen la información relacionada:

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 con DeleteClientAccessToken, usando el ClientAccessTokenID que devolvió la creación, y el token queda revocado de inmediato.
  • Reintentar la creación con la misma Description no 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:

FaultCodeSignificadoQué hacer
8001Falta el access token, no existe o ha caducadoRevisar el token o crear uno nuevo
8002El access token es válido, pero su cuenta está deshabilitadaReactivar la cuenta o usar el token de otra cuenta
8000El token no tiene permiso para esta APICrear el token con una cuenta que tenga ese permiso
8004El token no tiene permiso sobre el recurso pedido (cliente, facility, dispositivo o endpoint)Pedir solo recursos a los que la cuenta tiene acceso
100000Falta un dato obligatorioRevisar los parámetros de la llamada
100004Un parámetro tiene un valor no válido o supera un límiteRevisar el valor indicado en Message
100001Error inesperado en el servidorReintentar 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

En esta página