WebServicesTracks - v-l-m/vlm GitHub Wiki

Webservices pour les tracks

Au début, il n'y avait rien, ou pas grand chose, à savoir un pseudo ws utilisé par une ancienne implémentation pour Google Maps Puis, a été introduit le WS /boatinfo/tracks.php (et son pendant /boatinfo/tracks_private.php) A l'usage, ces ws consomment beaucoup de cpu et de bande passante, en partie parce que les outils cachent "mal" les données (ils redemmandent les mêmes positions), mais aussi parce que VLM ne les aide pas bien à les mettre en cache, et surtout parce que ces données elle même ne sont pas cachées coté VLM et sont donc systèmatiquement réextraites de la base de données.

Cette page explique les différents mécanismes disponibles.

A noter que pour l'instant : tracks_private.php n'est pas concerné, de même que les tracks des réels.

NOW se réfère à l'heure de la requête du WS.

/boatinfo/tracks.php

C'est le ws générique, le plus "souple", mais aussi le plus gourmand.

Arguments :

idu = id du bateau (par défaut, le bateau courant pour la session http en cours)
idr = id de la course (par défaut, la course associée à l'idu)
starttime = le timestamp EPOC du début des positions souhaitées (par défaut : NOW - 1h)
endtime = le timestamp EPOC du début des positions souhaitées (par défaut : NOW)

Spécificités :

Pour obtenir à la fois des tracks des dernières 48h et avant, il faut le faire en 2 fois.

/boatinfo/smarttracks.php

Ce ws a la même API que le ws tracks générique, sauf que l'idu et l'idr sont impératifs.

MERCI de ne pas envoyer de HEADERS AUTHENTIFIES afin de faciliter la mise en cache

Il retourne :

pour l'heure courante, exactement la même chose que le ws tracks.
une liste de suffixes d'url qui permettent de récupérer les tracks en cache de VLM.

Les url doivent être préfixées par "http://v-l-m.org/cache/tracks/" ou par "http://cX.v-l-m.org/tracks/", ou X vaut 1, 2, 3, ou 4. Les urls cX sont destinées en particulier aux clients qui parallélisent les transferts et qui "limitent" le nombre d'url accédées en parallèle.

Smarttracks est destiné à faciliter la vie des développeurs tout en leur faisant utiliser tous les niveaux de cache dispo afin de limiter la charge du serveur et de rendre plus réactifs les logiciels clients.

Il y a quelques raccourcis qui sont faits pour utiliser systématiquement le cache :

si la fin des tracks demandées n'est pas dans l'heure courante, on ne va renvoyer QUE des urls, en arrondissant à l'heure au dessus
le début des tracks demandées sera recalculé pour utiliser le cache statique au maximum.

A noter qu'il peut y avoir des recouvrements entre les différentes urls (les bornes sont incluses) donc il faut tester les doublons.

/boatinfo/statictracks.php

Ce ws à une API spécifique. Il n'est pas destinée à être accédé directement, mais uniquement par redirection du cache statique.

URL

Il est recommandé d'utilisé smarttracks de manière générale pour récupérer les url du cache correspondante. Cela permettra aussi de faire évoluer plus facilement les outils.

Les urls du cache statique sont de la forme /YYYYMM/DD/HH/R+/VV/U+.json :

YYYY = Année de la trace recherchée
MM = Mois
DD = Jour
HH = Heure de la trace (24 pour la journée complète, voir plus bas).
R+ = id de la course
VV 45)
U+ 123)

Si HH vaut 24, on renvoie les tracks de la journée complète (tracks qui "précèdent" la 24ème heure). Si HH est un multiple de 8 (mais pas 24), on renvoie les 8 dernières heures précédent l'heure concernée. Exemple : pour 16, on renvoie toutes les tracks entre 8h et 16h. Si HH est un multiple de 4 (mais pas de 8), ... même principe ... Si HH est pair (multiple de 2, mais pas de 4, ...idem .... Si HH est impair, on renvoie les tracks de l'heure qui précède. Par exemple : 5 renverra les positions entre 4h et 5h du jour concerné.

Quand c'est la première fois que le fichier tracks est demandé, une redirection (Code 302) est renvoyée, comprenant l'url à appeler par le client.

Le fichier comprends aussi un refurl qui permet de construire un cache local coté client facilement.

Exemple, a quoi ça sert ?

L'objectif du système est de trouver un compromis entre charge du serveur, nombre d'url, et bande passante. Les seuls tracks qui ne sont pas mis en cache statique sont celles de l'heure en cours.

Avec un exemple : (/ws/boatinfo/smarttracks.php?idu=10548&idr=60&starttime=1359159180&endtime=1359297951 ) Ce qui se traduit par smarttracks de Sun, 26 Jan 2013 00:13:00 GMT_' à '_Sun, 27 Jan 2013 14:43:04 GMT.

  {
  "request": {"time_request":1359298036,"idu":"10548","idr":"60","starttime":1359159180,"endtime":1359297951},
  "nb_tracks": (.../...),
  "tracks":[ (.../...)],                          =>Les tracks de 14:00 à 14:43
  "tracks_url":[
    "201301\/27\/14\/60\/48\/105.json",                 => Les tracks de 12h à 14h
    "201301\/27\/12\/60\/48\/105.json",                 => Les tracks de 8h à 12h
    "201301\/27\/08\/60\/48\/105.json",                 => Les tracks de 0h à 8h
    "201301\/26\/24\/60\/48\/105.json"                  => Les tracks du 26 janvier
    ],
  "success":true
  }

Si un autre joueur demande la même chose quelques minutes plus tard, le cache statique sera alimenté, et le serveur ne fera que renvoyer des fichiers. Si le même joueur demande 8h plus tard (à 22:43) des tracks sur la même période, la track de 16h, de 20h et de 22h seront généré, stockées renvoyées, le reste existant déjà.

Les tracks sont stockées dans mysql. Il y a différents niveau de cache/stockage :

SERVEUR : stockage mysql
SERVEUR : cache mysql (le résultat des requêtes courantes sont mis en cache, les requêtes sont volontairement arrondie à la vac la plus proche pour faciliter ce cache là)
SERVEUR : cache dynamique pour les ws (htcache) : le résultat d'une requête smartrack est mis en cache jusqu'à la prochaine vac
SERVEUR : cache statique (cf. plus haut)
CLIENT : cache du client http / du navigateur (stockage de la durée de vie des données)
CLIENT : mémoire