Skip to content

WebServices

Jump to bottom Edit New page
sbsrouteur edited this page May 8, 2016 · 7 revisions

Webservices offerts par Vlm.

  • Les webservices travaillent avant tout en json.
    • Le format texte est gardé pour la compatibilité provisoirement mais n'est pas garanti.
    • Si le format retourné est texte et que vous nécessitez JSON :
      • Méthode recommandée : Utilisez le header Accept : application/json;
      • Méthode non recommandée : utiliser l'argument ?forcefmt=json (ou &... s'il y'a déja un argument).
    • protections anti XSS : rester propre sur la correspondance {URL du web service appelé, URL de la page consommatrice} au niveau du nom de domaine. Le navigateur peut refuser cette utilisation de ressources (risque de sécurité).
  • les requêtes http doivent avoir un User-Agent correct (ou bien celui du navigateur client, ou bien un User-Agent qui identifie l'outil et sa version).
    • Voir la page VlmHttp (bonnes pratiques)

A partir de la version 0.14 de VLM, l'authentification sur un login par joueur (player mode). Par défaut, un player est loggué sur son premier bateau et les webservices concernent ce bateau.

  • Pour "switcher" de bateau, il faut ajouter select_idu=XXX dans les paramètres http.
  • Ce switch est persistant, c'est à dire qu'il n'a pas besoin d'être réitéré pour une série d'appel de webservices concernant le même bateau.
  • A noter que l'usage des ws est étendu à tous les bateaux manageable par le joueur (c'est à dire également ceux pour lesquels il a le droit de boatsitting).

Ws Racines.

NB: la création de WS racines n'est pas recommandé, et est même découragé.

login.php

Permet de se logguer en mode applicatif & http (ne fait rien d'autre). Necessite une auth http et de poster les champs suivants:

  • VLM_AUTH_USER: player name (ie adresse email du joueur)
  • VLM_AUTH_PW : mot de passe

logout.php

Déconection et suppression de la session. Il faut passer "test" en username et "ko" en password.

boatinfo.php

Web service historiquement appellé getinfo. Le paramètre select_idu est obligatoire pour ce webservices pour éviter des confusions historiques.

polarlist.php

Renvoie la liste de toutes les polaires chargées dans VLM.

raceinfo.php

Renvoie toutes les infos sur la définition d'une course

Autres

  • windinfo (NE PLUS UTILISER)

boatinfo /

boatinfo/prefs.php

Donne la pref correspondante à un joueur. paramètres :

  • idu
  • prefs

boatinfo/tracks.php

Donne les dernières traces pour un idu donné. Paramètres :

  • idu
  • (optionnel) idr
  • (optionnel) starttime
  • (optionnel) endtime

Voir la page les webservices autour des tracks

realinfo /

realinfo/profile.php

  • arguments : idreals = id du réel tel que renvoyé par raceinfo/reals.php
  • renvoie les infos disponibles sur le réel, dans un array 'profile'

realinfo/tracks.php

Donne les dernières traces pour un idu donné. Paramètres :

  • idreals
  • (optionnel) idr
  • (optionnel) starttime
  • (optionnel) endtime

playerinfo /

playerinfo/profile.php

Renvoie le profile d'un joueur

playerinfo/fleet.php & fleet_private.php

Le WS de gestion de la flotte d'un joueur est défini à la page GestionFlotteJoueur

raceinfo /

raceinfo/list.php

Liste des courses

raceinfo/ranking.php

raceinfo/results.php

raceinfo/reals.php

  • arguments : idr = numérique entier > 0 représentant le numéro de la course.
  • retour : une liste de réels dans le champ 'reals', avec en prime la date de la dernière mise à jour des tracks

windinfo /

boatsetup /

généralités

  • requête http vers /ws/boatsetup/<sujet_verb>.php

  • <sujet_verb> permet de choisir l'action parmi : (pilot_set_', '''target_set''', '''pilototo_add''', '''pilototo_delete''', '''pilototo_update''', '''prefs_set''','_race_subscribe)

  • paramètre unique en POST : parms un dictionnaire json

    • exemple :

    {"pim":3,"pip":{"targetlat":1.1,"targetlong":-2.2,"targetandhdg":3.3},"debug":true,"idu":9343}

  • le GET est accepté pour l'instant, mais attention à l'encodage des urls (idem que pour le POST, même si les navigateurs le font automatiquement en général)

  • Le POST doit être encodé en ASCII, mais le champ JSON contenant les données doît être URL encodé. Ce qui donne un POST dans le genre ci-dessous envoyé au serveur:

    parms=%7B%22taskid%22%3A98254%2C%20%22pim%22%3A2%2C%22pip%22%3A123%2C%22debug%22%3Atrue%2C%22tasktime%22%3A1324567890%2C%22idu%22%3A10548%7D

Il ne faut bien sur pas URLencoder le parms=, sinon le = devient un %3B et la requete ne passe pas

liste des clefs disponibles

Pour le dictionnaire parms pour les verbs pilot_set_', '''target_set''', '''pilototo_add''', '''pilototo_delete''', '''pilototo_update''', '_prefs_set

  • idu : int (id du boat loggué, pour être sur qu'un programme tiers n'envoie pas un ordre sur un bateau non désiré)
    • obligatoire
  • pim : int
    • obligatoire pour boat, pilototo_add, pilototo_update
  • pip :
    • float (hdg pour le pim=1, twa pour pim=2) (obligatoire pour action=boat)
    • dict (pour pim = 3, 4, 5) (optionnel pour action=boat, obligatoire pour target, pilototo_add et _update)
      • targetlat : float (obligatoire)
      • targetlong : float (obligatoire)
      • targetandhdg float (optionnel)
  • tasktime : int
    • obligatoire pour pilototo_add et _update
  • taskid : int * optionnel pour pilototo_update
    • obligatoire pour pilototo_delete et pilototo_update
  • prefs : dictionnaire (key => value)
    • obligatoire pour l'action "prefs"
  • debug : boolean, optionnel

Engagement en course (verb race_subscribe)

Fournir les deux paramètres suivants tous les deux obligatoires:

  • idu : (int) L'idu du boat à engager
  • idr : (string) L'Id de la course à laquelle engager le bateau

Bonnes pratiques

  • le paramètre debug = true listé dans les exemples ou plus haut ne doit être utilisé que lors de la mise au point ou en cas de bug.
  • User-agent : Voir plus haut dans Format

Exemples

NB: Ces exemples sont des exemples de test (utilisation du GET sans urlencodage et du mode debug). Il faut utiliser le POST sans debug (voir plus haut) en production.

Définition du mode de navigation

  • MAJ WP ET PIM3
    • /ws/boatsetup/pilot_set.php?parms={"pim":3,"pip":{"targetlat":42.8,"targetlong":-7,"targetandhdg":180},"debug":true,"idu":10573}
  • MAJ CAP PIM1
    • /ws/boatsetup/pilot_set.php?parms={"pim":1,"pip":340,"debug":true,"idu":10573}
  • MAJ ANGLE PIM2
    • /ws/boatsetup/pilot_set.php?parms={"pim":2,"pip":50,"debug":true,"idu":10573}
  • MAJ SIMPLE PIM3, 4 et 5
    • /ws/boatsetup/pilot_set?parms={"pim":3,"idu":10573}
    • /ws/boatsetup/pilot_set.php?parms={"pim":4,"idu":10573}
    • /ws/boatsetup/pilot_set.php?parms={"pim":5,"idu":10573}

Définition du WP

  • MAJ WP UNIQUEMENT
    • /ws/boatsetup/target_set.php?parms={"pip":{"targetlat":42.8,"targetlong":-7,"targetandhdg":180},"debug":true,"idu":10573}

Configuration du Pilototo

  • PILOTOTO_ADD un pim3 et passage du WP /ws/boatsetup/pilototo_add.php?parms={"tasktime":1275307500,"pim":3,"pip":{"targetlat":42.8,"targetlong":-7,"targetandhdg":180},"debug":true,"idu":10573}

  • PILOTOTO_UPDATE

    • PIM 3,4 ou 5 /ws/boatsetup/pilototo_update.php?parms={"taskid":98237,"tasktime":1275313000,"pim":3,"pip":{"targetlat":42.8,"targetlong":-7,"targetandhdg":180},"debug":true,"idu":10573}
    • PIM 1 ou 2 : "pip":-45

  • PILOTOTO_DELETE

    • /ws/boatsetup/pilototo_delete.php?parms={"taskid":98237,"debug":true,"idu":10573}

  • Vous pouvez obtenir la liste des ordres *après''' mise à jour en passant en outre le paramètre *"list_on_success":true

Gestion des préférences utilisateur sur le serveur

PREFS_SET

/ws/boatsetup/prefs_set.php?parms={"idu":9343, "prefs" : {"maparea" : 13}, "debug":true}

PREFS_SET en switchant d'user

/ws/boatsetup/prefs_set.php?select_idu=9343&parms={"idu":9343, "prefs" : {"maparea" : 13}, "debug":true}

Liste des clefs

  • mapOpponents : Type d'affichage des concurrents C'est une chaine, un des éléments de la liste suivante : myboat, my5opps, my10opps, meandtop10, mylist, all
  • mapLayers (carte fusionnée ou pas) C'est une chaine, un des éléments de la liste suivante : merged ou multi
  • mapTools : Définit l'affichage du compas. C'est une chaine, un des éléments de la liste suivante : compas, floatingcompas, bothcompass, none
  • mapPrefOpponents : Liste des bateaux demandés sur la carte. C'est une liste d'idusers sous forme de chaine de caractère (une liste d'identifiant numérique des bateaux). Il faut utiliser la virgule comme séparateur, sans espace.
  • maparea
  • mapMaille
  • mapX
  • mapY
  • mapAge
  • mapEstime
  • mapDrawtextwp
  • mapCenter
  • mobiVlmDatas
  • blocnote
  • color
  • theme
  • country
  • boatname
  • frogDatas : la valeur peut dépasser 255 chars
  • sbsrouteurDatas : la valeur peut dépasser 255 chars
  • qtvlmDatas : la valeur peut dépasser 255 chars

serverinfo/translation.php

Renvoie la String table selon la langue du joueur.

Lire le résultat

  • La réponse à la requête http est un dictionnaire json.
  • exemple : {"request":{"action":"boat","pim":3,"pip":{"targetlat":1.1,"targetlong":-2.2,"targetandhdg":3.3},"debug":true,"idu":9343},"success":true}
  • champs disponibles dans la réponse :
  • request : si debug a été passé à true
  • success : boolean, indique le succès ou pas de l'opération
  • error : en cas d'erreur, un dictionnaire est renvoyé
    • code : le code de l'erreur
    • msg : le message associé
    • custom_error_string : optionnel, un message complémentaire
  • usage : en cas d'erreur, un renvoi vers la doc.

Il est recommandé de lire ce résultat afin de tenir compte du message d'erreur potentiel et de le logguer ou d'avertir l'utilisateur.

Add a custom footer
Clone this wiki locally