Aperçu

Cet article explique comment utiliser le système SMS Web API Export On Demand pour accéder et exporter rapidement les données de trafic TMS à partir d'une interface Web au format XML. L'API WEB est un outil puissant car elle permet un accès direct et instantané aux données de la base de données sans avoir besoin d'un export personnalisé ou de génération de rapport. Une fois exportées, les données peuvent être facilement personnalisées pour permettre l'intégration avec une multitude d'outils, de logiciels ou de bases de données tiers.

Dans Gérer les emplacements sous administration, Chaîne / Facturation à (niveau supérieur de l'arborescence des emplacements) doit être sélectionné.

L'utilisateur doit disposer du type d'autorisation Chaîne et Utilisateur et pointer vers le niveau supérieur de l'arborescence d'emplacement pour pouvoir y accéder.

EN SAVOIR PLUS >> Sur la gestion des autorisations des utilisateurs

Modification et suppression de clés API existantes

• Cliquez sur l' icône en forme de crayon à côté de la ligne de clé API à modifier (utilisez pour désactiver en décochant l'autorisation)
• Cliquez sur l'icône de la corbeille à côté de la ligne de la clé API pour supprimer

*REMARQUE* Les clés supprimées ne peuvent pas être réutilisées.

Utilisation de la ou des clés API pour les appels de trafic

L'API WEB est appelée à l'aide d'une URL standard personnalisée pour votre entreprise, votre emplacement, votre plage de dates, votre intervalle, votre filtre d'heures de travail et votre type d'exportation. La structure de base de l'URL est présentée dans le lien ci-dessous :

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

Chacun des chiffres en surbrillance entre parenthèses représente une zone personnalisable :

• [1] Date de début de la plage de dates à partir de laquelle vous souhaitez exporter les données. Le format complet est MM/jj/AAAA-HH|mm mais les HH et mm ne sont pas obligatoires et peuvent être ignorés si vous sélectionnez le trafic uniquement par heures ou par jour. l'ajout de I à la fin de fromDate renverra le trafic pour les endroits où la journée était incomplète. Exemple : si un emplacement qui vient d'ouvrir ne commençait à signaler le trafic que dans l'après-midi de la journée, il n'apparaîtrait que si j'étais à la fin de la période fromDate=02/26/2020 i.

• [2] La date de fin de la plage de dates à partir de laquelle vous souhaitez exporter les données. Le format est exactement le même que la date de début décrite ci-dessus.

• [3] L'intervalle auquel les données de trafic seront générées.
  • 0 = Intervalle non applicable (Trafic brut)
  • 15 = 15 minutes
  • 30 = 30 minutes
  • 60 = horaire
  • 1440 = Quotidien
  • 10080 = Hebdomadaire
  • 32767 = Informations sur le tableau de bord d'occupation

• [4] Si vous avez défini des heures d'ouverture pour votre entreprise dans TMAS, vous pouvez utiliser cette option pour filtrer facilement les plages horaires. Remarque* S'applique UNIQUEMENT au Type=T* avec intervalle >0
  
  • 0 = Utiliser les heures de bureau (si les heures sont spécifiées dans l'appel API, cela remplace 1)
  • 1 = Utiliser les heures fournies dans les champs [1] uniquement et ignorer l'heure de fin dans [2], mais l'heure de fin doit toujours être présente.
    • Idéal pour les appels de trafic en temps réel afin d'actualiser les données et non pour appeler des données historiques.
  • 2 = Heures personnalisées sur plusieurs jours - Utilisez les heures fournies dans les champs [1] et [2]
    • Utilise les heures comme plage

• [5] Le type d'exportation de l'exportation de données.
  • td = Données de trafic (renvoie la somme totale du trafic pour l'emplacement et tous les sous-emplacements dont l'emplacement est un parent et où les capteurs de l'appareil sont marqués comme visibles dans les rapports TMAS) . Les valeurs renvoyées incluent (TrafficData, TrafficValue, StoreID).
    • tdd = Données de trafic récursives ou données de trafic brutes - (La sortie est similaire à TD, mais montre chaque emplacement individuel additionné et non les totaux par chaîne, district ou région)
      • Les valeurs renvoyées incluent (TrafficData, TrafficValue, StoreID).
    • tdl = Données de trafic récursives par appareil (l'intervalle doit être défini sur 15 ou plus)
      • Les valeurs renvoyées incluent (TrafficData, TrafficValue, StoreID|Device Label). Remarque : Ce type de sortie ne prend PAS en compte les appareils_sensors marqués comme NON visibles dans les rapports et renvoie la somme du trafic de tous les appareils actifs attribués à un emplacement.
    • tds = Données de trafic récursives par capteurs (l'intervalle doit être défini sur 15 ou plus)
      • Les valeurs renvoyées incluent (TrafficData, TrafficValue, StoreID|Sensor Label|Unique Sensor ID) . Remarque : Ce type de sortie ne prend PAS en compte les capteurs marqués comme NON visibles dans les rapports et renvoie les sommes individuelles de tous les capteurs actifs attribués à un emplacement. Voir type=tdv
    • tdv = Données de trafic récursives Données de trafic récursives par capteur (l'intervalle doit être réglé sur 15 ou plus)
      • Les valeurs renvoyées incluent (TrafficData, TrafficValue, StoreID|Sensor Label|Unique Sensor ID) . Remarque : Ce type de sortie prend en compte les capteurs marqués comme NON visibles dans les rapports et renvoie les sommes individuelles de tous les capteurs actifs attribués à un emplacement. Voir type=tds si vous souhaitez inclure des capteurs marqués comme NON visibles dans les rapports de l'appel.
    • tdo = Informations sur le tableau de bord d'occupation avec décomptes ajustés
      • Les valeurs renvoyées incluent (storeId, color, occDate, occLevelNow, occLevel-1, occLevel-2, occLevel-3, occLevel-4, occLevelMax, occLevelPct. Remarque : l'intervalle = 32767 doit être utilisé dans l'appel .
    • tdor = Tableau de bord d'occupation Informations brutes avec décomptes non ajustés
      • Les valeurs renvoyées incluent (storeId, color, occDate, occLevelNow, occLevel-1, occLevel-2, occLevel-3, occLevel-4, occLevelMax, occLevelPct. Remarque : l'intervalle = 32767 doit être utilisé dans l'appel .
  • qd = Données de file d'attente
    • qdd = Récursif
    • qdc = les trois derniers
      • Peut également ajouter & queuename= pour spécifier un seul nom de file d'attente
  • dw = Données sur le logement
    • dwc = Agrégé

• [6] apiKey= fourni par l'application TMAS

• [7] L'ID d'emplacement TMAS de l'emplacement à partir duquel vous souhaitez exporter les données de trafic. Peut utiliser le type d'emplacement ID de chaîne, de région ou de niveau de magasin. Trouvé dans la section Gérer les emplacements sous Configurer.

• [8] groupid = (facultatif) (Renvoie les valeurs uniquement pour les emplacements qui font partie du groupe. Lorsqu'elles sont combinées avec un district ou une région, les valeurs renvoyées concernent uniquement les emplacements qui font partie de ce district ou de cette région et les membres du groupe.)
  • L'ID de groupe peut être trouvé dans la fonction de gestion de groupe.
    1. Sélectionnez le groupe précédemment créé dans la liste déroulante de gestion des groupes
    2. Cliquez sur le bouton Modifier
    3. L'ID est mis en évidence dans l'image ci-dessous.

Limites 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 poussée rapide doit être configurée pour la chaîne dans TMAS . Remarque : Ceci est UNIQUEMENT disponible avec le package LIVE DATA TMAS.

Recommandations d'appel d'API

Appels de données horaires

• Limitation : si votre application nécessite des mises à jour des données toutes les heures, veillez à une utilisation équitable.
• Optimisation : lors de la mise à jour des données pour de nombreux 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 garantit une utilisation efficace.

Mises à jour des données historiques

• Pratique recommandée : pour des mises à jour des données de trafic ou des mesures similaires sur plusieurs jours :
• Plage de données : limitez les mises à jour à 2 à 3 jours maximum de données historiques.
• Planification : effectuez ces mises à jour pendant les heures creuses, idéalement entre 22 h 00 et 6 h 00, heure normale de l'Est (EST). Cela minimise l'impact sur la charge du serveur et la bande passante pendant les heures normales de bureau.
   

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 clé : 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.

Exemples en direct (lien démo)

FAQ

Q : Une plage de dates est-elle requise lors d’un appel pour occupation ?

R : Non , cela n'est pas requis pour les appels de Type=tdo ou Type=tdor car un occDate= sera renvoyé indiquant quand l'appel a été effectué. Tous les autres types d’appels pour la plage de dates (To/From) sont requis.

_______

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

R : Les guichets communiquent 24 heures sur 24 et 7 jours sur 7 au TMAS et les décomptes sont filtrés par heures d'ouverture, pour éviter d'inclure le décompte des personnes qui arrivent avant et après l'ouverture.

• 0 = Utiliser les heures de bureau (si les heures sont spécifiées dans l'appel API, cela remplace 1)
• 1 = Utiliser uniquement les heures fournies dans les champs [1] et ignorer l'heure de fin dans [2], mais l'heure de fin doit toujours être présente.
  • Idéal pour les appels de trafic en temps réel afin d'actualiser les données et non pour appeler des données historiques.
• 2 = Heures personnalisées sur plusieurs jours - Utilisez les heures fournies dans les champs [1] et [2]
  • Utilise les heures comme plage

_______

Q : Compréhension - occLevelNow, occLevel-1, occLevel-2, occLevel-3, occLevel-4, occLevelMax, occLevelPct

UN:

occLevelNow = Valeur d'occupation au moment de l'appel

occLevel-1, occLevel-2, occLevel-3, occLevel-4 = 4 derniers intervalles d'occupation pour les tendances.

occLevelMax = Seuil d'occupation maximum défini dans TMAS pour l'emplacement.

occLevelPct = occLevelNow/occLevelMax pour le pourcentage d'emplacement utilisé en fonction du seuil d'occupation.

_______

Q : Quelle est la différence entre ajusté et non ajusté ?

R :  Type=TDO correspond aux valeurs d'occupation brutes non ajustées sans modifications manuelles tout au long de la journée,

Type=TDOR inclut tous les ajustements manuels effectués tout au long de la journée (recommander ce type) .

Dépannage

Problème : Erreur 400 - Site Web introuvable

Solution : Vérifiez l'URL de l'API - Assurez-vous qu'elle est correctement formatée selon l'exemple de cet article et que la clé API complète est générée à partir de l'application TMAS.

_____________________________________________________

Problème : les données de trafic affichent 0

Solution : assurez-vous qu'il existe des données pour cette plage de dates en exécutant un rapport de totalisation dans TMAS.

_____________________________________________________

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

Solution : -1,0 Les données de trafic renvoyées indiquent qu'aucun trafic n'a été signalé par le compteur pendant 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 par erreur, sont dans le futur ou n'ont pas de sens pour le système »

Solution:

• ✓ Assurez-vous d'avoir saisi une date valide et que le dernier intervalle n'est pas à une heure ultérieure.
• ✓ 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 »

Solution : 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. »

Solution : Vérifiez que le format de votre plage de dates (FROM&TO) est MM/JJ/AAAA dans l'URL de l'appel API.

• Incorrect : &fromDate=6/12/18&toDate=6/12/18
• Correct : &fromDate=6/12/2018&toDate=6/12/2018

_____________________________________________________

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

Solution : assurez-vous que l'emplacement que vous saisissez est configuré avec des fonctions d'occupation.

_____________________________________________________

Problème : Message d'erreur : "Accès interdit"

Solution : Vérifiez que la clé API et/ou l'ID d'emplacement sont corrects et existent

_____________________________________________________