API d'extraction de données

Introduction

Cette section explique comment extraire des données de la plateforme Gear Studio à l'aide de l'API HTTP, par exemple :

• Alertes : l'API permet d'extraire la définition de toutes les alertes créées dans la plateforme, en les filtrant de différentes manières.
• Alarmes : l'API permet d'extraire toutes les alarmes enregistrées dans la plateforme, de manière historique, en les filtrant de différentes manières.
• Données d'endpoints : l'API permet d'extraire toutes les informations associées aux endpoints, de manière historique, en les filtrant de différentes manières.
• Géozones : l'API permet d'extraire la liste des géozones configurées pour chaque client, y compris la liste des véhicules qu'elles contiennent.

Premiers pas

Création d'un token d'accès

Comme pour toute autre intégration HTTP, il est nécessaire de créer un token d'accès. Cette page contient plus d'informations sur la gestion des tokens d'accès. Les tokens d'accès permettent de contrôler l'accès et les permissions utilisés pour toute opération.

Authentification avec un token d'accès

Dans toutes les API, le token d'accès peut être envoyé dans l'en-tête, au moyen d'un en-tête Authorization, comme indiqué ci-dessous :

Authorization: Bearer {accessToken}

Sinon, lorsqu'il n'est pas possible d'envoyer le token dans l'en-tête Authorization, le token d'accès peut être envoyé dans l'URL, au moyen du paramètre « accessToken », comme dans l'exemple suivant :

https://gear.cloud.studio/api/v2/alarms?accessToken={accessToken}&clientID=4&maxCount=10

Exécution de l'API

Pour exécuter l'API, consultez chacune des sections suivantes, qui contiennent les informations correspondantes :

• Extraction des alertes.
• Extraction des alarmes.
• Extraction des données d'endpoints.
• Extraction des données de géozones.

Erreurs

Lorsqu'un appel échoue, l'API répond avec le code de statut HTTP 500 et un corps JSON au format suivant, quelle que soit la cause de l'erreur (token invalide, permission manquante ou paramètre invalide) :

{
    "Exception": {
        "ClassName": "ServiceException",
        "FaultCode": "8001",
        "FaultData": "",
        "Message": "Description of the error"
    }
}

• FaultCode : code d'erreur numérique. Il reste stable d'une version à l'autre et c'est le champ qu'une intégration doit utiliser pour décider de la marche à suivre.
• Message : description lisible de l'erreur. Sa formulation peut changer et elle est renvoyée traduite ; les intégrations ne doivent donc pas se fier à son texte.
• FaultData : données supplémentaires sur l'erreur. Ce champ est généralement vide.

Les codes les plus courants sont :

Les erreurs 8000, 8001, 8002, 8004, 100000 et 100004 ne se résolvent pas en répétant le même appel : corrigez d'abord la requête ou le token.