Guide de gestion des clés API TMAS

L'API Web TMAS permet aux utilisateurs d'accéder aux données de trafic et de les exporter de manière transparente, en s'intégrant à des outils et applications tiers. Ce guide fournit des instructions sur la création, la gestion et l'utilisation efficaces des clés API.

Limitations des appels API

• La plage de dates ne peut pas dépasser un mois.
• L'API Web TMAS a une limite de débit d'un appel toutes les deux secondes.
• Pour accéder aux données de trafic par intervalles d'une minute ou moins, la fonction Fast Push doit être activée sur la chaîne et le dispositif de comptage défini sur la configuration déclenchée. Remarque : ceci est UNIQUEMENT disponible avec l'abonnement TMAS en temps réel.

Recommandations d'appel d'API

Appels de données horaires

• Limitation : si votre application nécessite des mises à jour de données toutes les heures, veillez à une utilisation équitable.
• Optimisation : lors de la mise à jour des données pour plusieurs emplacements (par exemple, plus de 40), limitez vos appels d'API pour récupérer uniquement les données des trois dernières heures. Cette approche permet de gérer le volume de données et de garantir une utilisation efficace.

Mises à jour des données historiques

• Pratique recommandée : pour les mises à jour des données de trafic ou des mesures similaires sur plusieurs jours :
  • Plage de données : limitez les mises à jour pour qu'elles ne couvrent pas plus de 2 à 3 jours de données historiques.
  • Planification : effectuez ces mises à jour en dehors des heures de pointe, idéalement entre 22 h et 6 h, heure normale de l'Est (HNE). Cela minimise l'impact sur la charge du serveur et la bande passante pendant les heures ouvrables normales.

Exemple d'utilisation excessive (à éviter)

• Pratique inacceptable : Un exemple d'utilisation excessive consiste à effectuer des appels d'API toutes les 15 minutes pour des données provenant de plus de 40 emplacements, où chaque appel récupère deux semaines de données.
• Problème principal : Cette pratique est inefficace car elle implique une récupération redondante de grands ensembles de données, dont la plupart ne sont pas des informations nouvellement générées.

Créer une clé API

Connectez-vous à TMAS Sélectionnez l'emplacement de la chaîne dans les options d'emplacement Développer Configurer Sélectionnez Gérer les emplacements Sélectionner la ou les clés API Sélectionnez Ajouter une clé Nom de la clé API d'entrée Cochez la case Traffic WEB API dans les autorisations Cliquez sur Ajouter – la clé apparaîtra désormais dans la liste des clés.

Localisation de l'ID d'emplacement pour la chaîne et les emplacements

Pour trouver l'ID d'emplacement d'une chaîne ou d'emplacements individuels : Connectez-vous à TMAS. Accédez à : Administration > Gérer les emplacements . La liste des emplacements sera affichée, y compris les districts, les régions et les emplacements . L' ID d'emplacement se trouve dans la colonne correspondante à côté de chaque nom d'emplacement. Utilisez l’ ID d’emplacement approprié dans vos requêtes API.

Obtention d'un identifiant de groupe (facultatif)

Pour créer un groupe et récupérer son ID de groupe : Rechercher la section Gestion des groupes Dans TMAS, la section Gestion des groupes se trouve dans le menu de gauche et sélectionnez le groupe souhaité dans le menu déroulant . Modifier le groupe Cliquez sur l’ icône d’édition (crayon) à côté du groupe sélectionné. Trouver l'ID du groupe L' ID de groupe s'affiche à côté de l'étiquette d'ID dans la section Importer des données à partir d'un groupe existant . Copiez cet ID de groupe pour l'utiliser dans les requêtes API. Cet ID de groupe peut être utilisé dans les appels d'API pour filtrer les données des emplacements au sein du groupe sélectionné.

Affichage des clés API

• Seul l' utilisateur qui a créé une clé API peut la visualiser et la copier.
• Les autres utilisateurs verront la clé API masquée par des astérisques ( * ) et ne pourront pas y accéder ni la copier.
• La colonne Créé par l'utilisateur affiche le nom de l'utilisateur qui a généré la clé.

Modification ou suppression d'une clé API

• Pour modifier une clé API, cliquez sur l' icône en forme de crayon (modifier) .
• Pour désactiver une clé API, décochez ses autorisations.
• Pour supprimer une clé API, cliquez sur l' icône de la corbeille . Remarque : les clés supprimées ne peuvent pas être restaurées.

Suppression d'utilisateur et gestion des clés API

• Si un utilisateur est supprimé de TMAS , une invite apparaîtra pour les administrateurs de la chaîne et de l'utilisateur .
• L'invite propose deux options :
  1. Désactiver le compte utilisateur mais garder la clé API active – Cela permet à la clé API de continuer à fonctionner tout en empêchant l'utilisateur de se connecter.
  2. Supprimer le compte utilisateur et révoquer la clé API – Cela supprime à la fois l’utilisateur et la clé API.

Cela garantit que l’accès à l’API reste contrôlé même lorsque les comptes d’utilisateurs sont supprimés.

Utilisation des clés API pour les demandes de données de trafic

Les appels API suivent un format d'URL standardisé, personnalisable en fonction de paramètres tels que l'entreprise, l'emplacement, la plage de dates et l'intervalle de données.

Structure de l'URL de l'API :

https://www.smssoftware.net/tmas/manTrafExp?fromDate=[1]&toDate=[2]&interval=[3]&hours=[4]&reqType=[5]&apiKey=[6]&locationId=[7]&groupId=[8]

Répartition des paramètres :

1. fromDate : Date de début ( MM/dd/YYYY-HH|mm ). L'heure est facultative. L'ajout de « i » renvoie des données pour les jours incomplets.
2. toDate : Date de fin ( MM/dd/YYYY-HH|mm ).
3. intervalle : Niveau d’agrégation des données :
   • 0 = Trafic brut
   • 15 = 15 minutes
   • 30 = 30 minutes
   • 60 = Horaire
   • 1440 = Quotidien
   • 10080 = Hebdomadaire
   • 32767 = Informations sur le tableau de bord d'occupation
4. heures : Filtrage des heures d'ouverture :
   • 0 = Utiliser les heures d'ouverture prédéfinies
   • 1 = Utiliser les heures dans fromDate
   • 2 = Horaires personnalisés sur plusieurs jours
5. reqType : Type d'exportation de données :
   • td = Données de trafic résumées
   • tdd = Données de trafic récursives par localisation
   • tdl = Données de trafic par appareil (intervalle ≥ 15)
   • tds = Données de trafic par capteur (intervalle ≥ 15)
   • tdo = Informations sur le tableau de bord d'occupation (intervalle = 32767)
   • tdor = Données brutes d'occupation (intervalle = 32767)
6. apiKey : votre clé API unique.
7. locationId : L'ID d'emplacement TMAS (niveau chaîne, région, district ou emplacement).
8. groupId (facultatif) : filtre les données pour les emplacements au sein d'un groupe spécifique.

Limites d'appels API et bonnes pratiques

• Limite de plage de dates : ne peut pas dépasser un mois.
• Limite de débit : un appel toutes les deux secondes .
• Données au niveau des minutes : nécessite une configuration Fast Push (package LIVE DATA).

Conseils d'optimisation :

• Mises à jour des données horaires : limitez les appels d'API aux trois dernières heures pour réduire la charge du système.
• Requêtes de données historiques : lors de la récupération de données sur plusieurs jours, limitez les requêtes à 2 ou 3 jours et planifiez-les en dehors des heures de pointe (22 h 00 - 6 h 00 HNE).

Exemples en direct (lien de démonstration)

Questions fréquemment posées

Q : Puis-je récupérer les données d’occupation sans spécifier de plage de dates ?

• Oui, pour reqType=tdo ou tdor , le champ occDate renvoie l'heure d'appel.

Q : Comment le paramètre « heures » affecte-t-il les appels d'occupation ?

• Les compteurs fournissent des rapports en continu, mais l'application des heures ouvrables filtre les périodes non opérationnelles.

Q : Que signifient les paramètres de niveau d’occupation ?

• occLevelNow : Occupation actuelle.
• occLevel-1 à occLevel-4 : occupation aux intervalles précédents.
• occLevelMax : Seuil d'occupation maximal.
• occLevelPct : Pourcentage d'occupation par rapport au max.

Dépannage des problèmes d'API

Problème : la clé API ne fonctionne pas

• Assurez-vous que la clé API correcte est utilisée et qu’elle n’a pas été révoquée.
• Vérifiez que les autorisations appropriées sont attribuées à la clé API.

Problème : Réception d'une réponse « Non autorisé » ou « Interdit »

• Vérifiez que la clé API est associée à l’emplacement correct de la chaîne.
• Confirmez que la clé API n’est pas expirée ou désactivée.

Problème : Problèmes de récupération des données

• Vérifiez que la plage de dates ne dépasse pas la limite d’un mois.
• Assurez-vous que le paramètre d’intervalle correspond au format requis.
• Si vous récupérez des données en temps réel, vérifiez que Fast Push est activé et qu'il existe un plan d'abonnement actif en temps réel valide. Le compteur doit également disposer d'une licence en temps réel attribuée.

Problème : limite de débit d'API dépassée

• Les appels API doivent être espacés d'au moins deux secondes .
• Réduisez la fréquence des appels d’API en regroupant les demandes de données.

Problème : réponse vide inattendue

• Vérifiez les paramètres d’ID d’emplacement et d’ID de groupe.
• Assurez-vous que des données sont disponibles pour la plage horaire spécifiée.

Problème : les données de trafic affichent des valeurs de -1,0

•  -1,0 Les données de trafic renvoyées indiquent qu'aucun trafic n'a été signalé par le compteur pour cet intervalle de temps.
• Vérifiez la date/heure demandée et/ou
• Vérifiez si le matériel du compteur fonctionnait correctement pendant cette période et suivez le processus de dépannage approprié.

Problème : Message d'erreur : « Les paramètres de date indiqués dans (DATE RANGE) sont soit formatés de manière erronée, soit se situent dans le futur, soit n'ont aucun sens pour le système »

• ✓ Assurez-vous d’avoir entré une date valide et que le dernier intervalle ne se situe pas à une date future.
• ✓ Assurez-vous que la plage de dates ne dépasse pas un mois

Problème : Message d'erreur : « Les paramètres ( intervalle et/ou heures) donnés ne respectent pas les valeurs autorisées »

• Assurez-vous que l'intervalle est valide, comme expliqué dans la section Utilisation

Problème : Message d'erreur : « Un problème de base de données sous-jacent empêche le serveur d'afficher des données. Veuillez contacter votre administrateur de base de données. »

• Vérifiez que le format de votre plage de dates (DE&À) est MM/JJ/AAAA dans l'URL d'appel d'API
  • Incorrect : &fromDate=12/06/18&toDate=12/06/18
  • Correct : &fromDate=6/12/2018&toDate=6/12/2018

Problème : Message d'erreur : « L'emplacement indiqué n'a aucune file d'attente ».

• Assurez-vous que l'emplacement que vous saisissez est configuré avec des fonctions d'occupation

Ce guide fournit un aperçu complet de la gestion des clés API dans TMAS. Pour obtenir de l'aide, contactez le support via le chat help.storetraffic.com . directement depuis TMAS