Accueil – Tout dérouler

Communiquer avec BaseDeFiches via des scripts

BaseDeFiches propose une interface standard de saisie. Dans différents cas, celle-ci peut se révéler soit trop compliquée (pour un formulaire de saisie en ligne), soit trop limitée (si on veut disposer d’interface plus riche que celle d’un formulaire HTML). L’idée est d’alors de développer des scripts qui vont faire la passerelle entre BaseDeFiches et une autre interface.

Le développement de ces scripts repose sur un simple rappel : BaseDeFiches est basé sur le serveur Tomcat, toute la communication avec BaseDeFiches se fait avec le protocole HTTP et des requêtes POST et GET. Autrement dit, un langage de script capable de faire des requêtes POST et GET est capable de s’interfacer avec BaseDeFiches ! Il suffit de reproduire la même communication que celle que fait le navigateur avec le serveur.

Voici un exemple en PHP qui appelle http://bases.basedefiches.net:8080/basedefiches/Saisie :

$data //paramètres transmis
$host = "bases.basedefiches.net";
$port = "8080";
$context = "basedefiches";

$fp = fsockopen($host, $port);

fputs($fp, "POST ".$context."/Saisie HTTP/1.1\r\n");
fputs($fp, "Host: $host\r\n");
fputs($fp, "Content-type: application/x-www-form-urlencoded\r\n");
fputs($fp, "Content-length: ". strlen($data) ."\r\n");
fputs($fp, "Connection: close\r\n\r\n");
fputs($fp, $data);

$result = '';
while(!feof($fp)) {
//reception du résultat
$result .= fgets($fp, 128);
}

fclose($fp);

Dans notre exemple, $data est la variable dans lequel sont définis les paramètres de la requête POST (sachant que la syntaxe est param_1=...&param_2=...&param_3=...).

Pour savoir quels sont les paramètres à utiliser, le plus simple est de regarder le code source des pages HTML de l’interface d’administration : tous les paramètres s’y trouvent définis dans les balises <input>, <textarea>, etc. L’autre possibilité est de regarder le code source en Java. Avec le temps, les commandes les plus courantes seront documentées.

Authentification

Lorsqu’on se connecte à une base de fiches, on commence par un écran (/Session) où l’on demande le mot de passe. Une fois identifié, c’est grâce à un cookie comprenant un identifiant de session que l’on passe de page en page sans avoir besoin de rappeler son mot de passe à chaque fois.

En fait, à chaque fois qu’une requête est envoyée à la base, la vérification se fait en trois étapes :

C’est l’étape 2) qui peut être reproduite par un script. Il suffit d’ajouter dans sa requête les trois paramètres suivants :

La requête est alors acceptée.

Suivi par les cookies

Le seul souci de l’ajout des paramètres, c’est qu’une nouvelle session est créée à chaque requête. Pour éviter cela, il suffit que le script incorpore le suivi des cookies. Certains langages le proposent. Cela peut être programmé « à la main » en suivant la documentation du protocole HTTP. Il suffit de savoir que la réponse transmet dans son entête une paramètre Set-Cookie: avec la valeur du cookie et que la requête doit transmettre le paramètre Cookie:.

En cas de suivi de cookie, le mieux est de continuer de transmettre à chaque fois les trois paramètres de connexion vu ci-dessus. Ainsi, si la session a expiré, une nouvelle sera créée automatiquement.

Méthode GET ou POST

La différence visible entre une requête GET et POST est, dans le cas de la requête GET, la présence des paramètres dans l’URL. Le protocole HTTP indique qu’une requête GET ne doit pas changer l’état du système. En effet, l’URL d’une requête GET peut être conservé dans un serveur mandataire (proxy) : l’appel de cette requête risque alors d’être traitée par le serveur mandataire et de ne pas parvenir au serveur final. Toute requête qui modifie l’état du système (dans notre cas, qui change des données de la base) doit être réalisée avec la méthode POST.

La conséquence pour BaseDeFiches est la suivante :

Comprendre les URLs utilisées

Les URLs utilisés par BaseDeFiches sont de deux types : les instructions et les ressources

Les Instructions

Les Urls des instructions sont reconnaissables par le fait qu’elles commencent par une majuscule, n’ont pas d’extension, sont situées à la racine et sont souvent accompagnées de paramètres : elles représentent un jeu d’instructions qui ont des points communs. Il s’agit des Urls suivantes :

Les instructions ont des paramètres communs :

Chaque jeu d’instructions a ensuite des paramètres qui leur sont propres. par exemple, le paramètre corpus est utilisé dans presque toutes les instructions de /Corpus.

Enfin, chaque instruction peut posséder ses propres paramètres.

Par exemple, pour déclencher la modification d’une fiche, il faut invoquer l’URL /Saisie avec la méthode POST et, au minimum les paramètres cmd (qui aura la valeur FicheUpdate pour indiquer qu’il s’agit de la commande de mise à jour d’une fiche), corpus (avec le nom du corpus) et idcorpus (le numéro de la fiche).

Les ressources

Les URLs des ressources se reconnaissent au fait qu’elles comprennent toujours un sous-répertoire (exemple : /fiches/suivi-1.html), qu’elles ont toujours une extension et que l’on ne leur passe jamais de paramètres.

Elles sont construites comme si c’était de vrais fichiers dans une arborescence alors qu’en fait le contenu même est souvent générés à la volée par le serveur.

Ces URLs peuvent toujours être appelés avec la méthode GET.

Il n’y a pas de passage de paramètres : c’est le nom lui-même qui contient les paramètres (par exemple, l’URL d’une fiche est le composé du nom du corpus et de son identifiant dans le corpus).

Paramètres issus de la session

L’utilisateur avec lequel est établi la connexion influe sur les paramètres suivants :

Il n’est pas possible de modifier ces paramètres pour la commande en cours. Si on veut jouer avec ces paramètres, il faut des utilisateurs différents.

Prenons, par exemple, une base avec deux langues de travail : l’espagnol et le français. Imaginons un script PHP réalisé pour faire un formulaire de saisie simplifié. Suivant le contexte, ce script voudra récupérer les libellés des champs en espagnol ou en français. Pour ce faire, la solution est de se connecter avec des utilisateurs différents, l’un avec comme de travail l’espagnol, l’autre avec comme langue de travail le français.

Obtenir une réponse en XML

Par défaut, lorsqu’une commande ou tout autre instruction est réalisée, le serveur renvoie comme réponse la page HTML de l’interface en question, celle que l’on a l’habitude de voir quand on se connecte normalement.

Dans le cas d’un script, cette page ne présente pas d’intérêt : elle peut être volumineuse et recueillir l’information qui est intéressante dans le code HTML peut être laborieux.

Il est possible de changer le format de la réponse en utilisant le paramètre output=xml. La requête va alors renvoyer un fichier XML qui sera facile à traiter. C’est un fichier XML très simple qui renseigne sur la réussite ou non de la requête.

En cas de réussite, il se présente sous la forme suivante :

<report result="done">
  <done-message>...</done-message>
</report>

<done-message> comprend le message indiquant le succès dans la langue d’interface de l’utilisateur.

 

Quand la commande n’a eu aucun impact sur la base (par exemple, on a demandé la modification d’un libellé en indiquant une valeur identique à la valeur actuelle), le fichier est simplement :

<report result="none"/>

En cas d’échec, sa forme est identique à ceci près que l’attribut @result peut avoir les valeurs suivantes :

<report result="">
<error-message error-key="">...</error-message>
<error-message error-key="">...</error-message>
...
<class>...</class>
<trace>...</trace>
</report>

Comme il peut y avoir plusieurs erreurs, il peut y avoir plusieurs élements <error-message error-key="">. <class> et <trace> sont présents quand une exception a été lancée par Java (Cela ne devrait jamais arriver).