Couplage du site avec les SAD

De OpenESubWiki.

Sommaire

Généralités

Dans openESub 1.2, il a été décidé de faciliter au maximum le couplage du site officiel avec les SADs. Seule exception pour l'instant : le passage des ordres que l'on ne souhaite pas encourager au travers d'un SAD.

Les facilités offertes

Fichiers XML

Sont publiés et maintenus sur le site :

Services WEB / SOAP

Il est désormais possible d'utiliser des fonctions du site à distance depuis un programme local. Cette fonctionnalité nouvelle s'appuie sur les services web/SOAP. Pour les utiliser, vous devez donc vous munir d'une bibliothèque "client SOAP" (il en existe pour tous les langages récents). Les exemples qui vont suivre seront donnés en python (dispo sous linux et windows) muni de la bibliothèque SOAPpy. Veillez à les installer tous les deux avant d'essayer les exemples. Ces exemples sont bien sûr transposables en n'importe quel langage et le choix du python n'est donc pas obligatoire. Dans ce cas, je vous invite à consulter le document complémentaire d'Aerics Se connecter au SOAP openESub depuis un programme VB6.

Les services web sont disponibles sur l'URL http://www.openesub.org/jeu/asynchrone/site/soap/soap.php avec le namespace "http://www.openesub.org". Si votre librairie SOAP cliente vous demande un WSDL, il est disponible à l'adresse http://www.openesub.org/jeu/asynchrone/site/soap/soap.php?wsdl. Voici la liste des méthodes disponibles :

(string) ping()

Cette fonction retourne 'pong' et permet de tester très simplement le fonctionnement du service.

>>> import SOAPpy 
>>> url = 'http://www.openesub.org/jeu/asynchrone/site/soap/soap.php'
>>> namespace = 'http://www.openesub.org'
>>> server = SOAPpy.SOAPProxy(url, namespace)
>>> server.ping()
'pong'

Dans la suite de ce document, nous présupposerons que les 4 premières lignes de cet exemple ont été tapées au moins une fois.

(string) getPseudo((string) identifiantDuPacha)

Cette fonction retourne le pseudo du pacha dont l'identifiant est passé en argument.

>>> [...]
>>> server.getPseudo('4')
'The Fab'

(string) getZdops((string) identifiantDuPacha)

Retourne une chaine contenant la liste des id_zdop (séparée par des espaces) où le pacha dont l'id est passé en arguments a des sous-marins actifs.

>>> [...]
>>> server.getZdops('4')
'8 9 78 130 232 320'

(array) getZdop((string) identifiantDeLaZdop)

Retourne des informations sur la zdop dont l'id est passé en arguments. Le premier élément du tableau (int) est l'identifiant de la Zdop, le deuxième (int) est le numéro du tour, le troisième (string) est le statut de la Zdop et le dernier (string) est le nom de la Zdop.

>>> [...]
>>> server.getZdop('78')
<SOAPpy.Types.structType getZdopResponse at -1216450068>: {'numTour': 18, 'idZdop': 78, 'nom': 'School Rorqual
de Bryde 2', 'statut': 'Archivee'}
>>> server.getZdop('78')['nom']
'School Rorqual de Bryde 2'

(array) getGuilde((string) identifiantDeLaGuilde)

Retourne des informations sur la guilde dont l'id est passé en arguments. Le premier élément du tableau (int) est l'identifiant de la guilde, le deuxième (string) est le nom complet de la guilde, le troisième (string) est l'acronyme et le dernier (int) est l'identifiant du leader.

>>> [...]
>>> server.getGuilde('3')
<SOAPpy.Types.structType getGuildeResponse at -1216449748>: {'acronyme': 'CBA', 'nom': 'Cercle Des Blasteurs
Alpins', 'idLeader': 21, 'idGuilde': 3}
>>> server.getGuilde('3')['idLeader'] 
21

(array) getPacha((string) identifiantDuPacha)

Retourne des informations sur le pacha dont l'id est passé en arguments. Le premier élément du tableau (int) est l'identifiant du pacha, le deuxième (string) est le pseudo, le troisième (int) est l'identifiant de la guilde et le dernier (int) est l'identifiant du grade.

>>> [...]
>>> server.getPacha('4')
<SOAPpy.Types.structType getPachaResponse at -1216448212>: {'idPacha': 4, 'pseudo': 'The Fab', 'id_guilde': 1,
'id_grade': 14}

(array) getSoum((string) identifiantDuSousmarin)

Retourne des informations sur le sous-marin dont l'identifiant est passé en arguments. Le premier élément du tableau (int) est l'identifiant du sous-marin, le deuxième (string) est le nom du sous-marin, le troisième (int) est l'identifiant de la classe et le dernier (int) est l'identifiant du pacha.

>>> [...]
>>> server.getSoum('4')
<SOAPpy.Types.structType getSoumResponse at -1216448948>: {'nom': 'Ullrich', 'id_classe': 4, 'id_pacha': 3,
'idSoum': 4}

(array) identification((string) login, (string) password, [(string) statutMinimal])

Permet d'authentifier un couple login/password. La mention de statutMinimal est optionnelle est permet de vérifier un couple login/pass d'un pacha dont l'inscription ne serait pas encore complètement validée. Voir les détails du code pour comprendre. Dans la suite, on traitera le cas simple où il n'y a pas de troisième argument.

Le service retourne toujours un tableau à trois éléments :

  • (int) l'identifiant du pacha correspondant au couple login/password
  • (string) un identifiant de session qui sera valable pendant 1 heure
  • (string) un éventuel diagnostic si l'identification n'a pas pu se faire

>>> [...]
>>> server.identification('webmaster@openesub.org','XXXXXXXXX')
<SOAPpy.Types.structType identificationResponse at -1216449780>: {'sessionID': 'ddce35da87ff794284a65438b4c04ca1',
'diagnostic': , 'idPacha': 4}

>>> [...]
>>> server.identification('webmaster@openesub.org','mauvaisPassword')
<SOAPpy.Types.structType identificationResponse at -1216458804>: {'sessionID': , 'diagnostic': 'inexistant',
'idPacha': 0}

Il faut noter qu'après 10 tentatives infructueuses successives, l'adresse IP utilisée pour la requête sera automatiquement bloquée pendant 1 heure.

(string) getCR((string) identifiantDuPacha, (string) sessionID, (string) identifiantDeLaZdop, (string) num_tour)

Retourne le CR XML de la zdop concernée, pour le pacha et le num_tour spécifié. L'identifiant de session est celui retourné par un appel à la fonction "identification". Il doit avoir moins d'1 heure.

>>> [...]
>>> server.getCR('4', '1b0b621a02114d713db90c452048bbc6', '78', '18')
>>> [...]

NB : Pourquoi tous les arguments sont-ils en 'string' alors que certains pourraient être des entiers ? En fait, au départ, ils étaient déclarés en "integer" mais une incompatibilité avec la lib client SOAP sous VB6 handicapait certains. On a donc désormais changé tous les arguments en 'string' de manière à ce que le service web soit interopérable avec tout le monde.

Outils personnels