Exemple d'utilisation d'un WebService : Google

Ce document a pour but de présenter d'une manière que j'espère simple l'utilisation d'un WebService. Il ne s'agit pas d'un cours de haute voltige, mais d'une implémentation pratique.

Bien entendu, toute remarque constructive est la bienvenue.

Le code a été écrit et testé avec Borland C++ Builder 6.0 Enterprise anglais.

Le projet est téléchargeable ici.

Pour pouvoir l'utiliser, enregistrer la clé reçue de Google dans le fichier RegKey.txt.

En faisant l'analogie avec un programme développé par soi-même, le WebService est une fonction, ou une librairie de fonctions mise à disposition non dans une librairie ou un code source, mais par un serveur Web.

Les prototypes de ces fonctions sont définis dans un fichier WSDL, qui peut être comparé à un fichier d'en-tête.

D'un point de vue pratique, il s'agit d'un échange de fichiers XML, transporté par le protocole HTTP. L'application cliente encode dans un fichier XML, la fonction qu'elle désire appeler, ainsi que les paramètres. Ce fichier est envoyé au serveur. Le serveur le décode , exécute le traitement demandé, encode le résultat dans un fichier XML qui est renvoyé au client.

J'imagine bien que cette description va faire hurler les puristes, mais il me semble qu'elle donne une idée rapide et simple de ce qu'est un WebService.

Google fournit une API sous forme de WebSerice. Cette API est une version bêta, mais est fonctionnelle et gratuite, disponible pour une utilisation non commerciale.

Elle est téléchargeable à l'adresse suivante : http://www.google.fr/apis/

Après enregistrement, une clé est envoyée sur l'e-mail. Cette clé est nécessaire pour chaque appel au service.

La première étape est de créer un nouveau projet et d'y importer le fichier WSDL afin de pouvoir accéder aux fonctions exportées par le serveur.

Dans le menu File/New/Other …, sélectionner l'onglet WebServices, WSDL Importer

Dans l'assistant qui apparaît, cliquer sur le bouton Next.

Doit alors apparaître une fenêtre semblable a celle qui suit, avec à gauche la liste des types et fonctions générées et à droite, un aperçu du code.

Cliquer sur le bouton Finish et enregistrer le nouveau projet dans un répertoire.

Dans le fichier qui va utiliser le WebService, ajouter la ligne suivante dans les includes :

#include "GoogleSearch.h"

Il faut ensuite déclarer une interface permettant d'accéder au service désiré :

_di_GoogleSearchPort GoogleSearchPort;

Et la variable qui contiendra la valeur de retour.

GoogleSearchResult *SearchResult = new GoogleSearchResult();

L'étape suivante est d'acquérir l'interface vers le service désiré.

GoogleSearchPort = GetGoogleSearchPort();

L'appel au WebService se fait dès lors comme une fonction tout à fait classique :

SearchResult = GoogleSearchPort->doGoogleSearch(RegKey->Text,
                                                EKeyWords->Text,
                                                iStart,
                                                EMaxRes->Text.ToInt(),
                                                CBFilter->Checked,
                                                ERestrict->Text,
                                                CBSafeSearch->Checked,
                                                Elr->Text,
                                                "dummy", 
                                                "dummy");

Les paramètres sont dans l'ordre :

• la clé reçue lors de l'enregistrement auprès de Google ;
• les mots clés ;
• l'index du premier élément de réponse désiré ;
• le nombre de résultats désirés ;
• un booléen indiquant si l'on veut tous les résultats, ou si les résultats similaires sont filtrés ;
• une clause de restriction (langue, sujet…) ;
• une option de filtrage des sites Adultes ;
• une option de filtre sur la langue des pages résultant de la recherche ;
• deux options qui doivent être présentes, mais qui ne sont plus utilisées et qui sont appelées à disparaître à l'avenir.

Pour une description plus complète des paramètres et les valeurs permises, je vous renvoie à la documentation fournie dans l'API.

Le code suivant permet de lister les résultats de la recherche dans une ListBox :

ResultElement *resElem;
                
for (int i = SearchResult->startIndex - iStart;i <= SearchResult->endIndex - iStart;i++) {
    resElem = SearchResult->resultElements[i-1];
    LBResult->Items->Add( "<" +IntToStr(iStart + i)+ "> "+ resElem->title);
    LBResult->Items->Add(" -> " + resElem->URL);
}

À l'exception de l'étape d'importation du descriptif du WebService, l'utilisation est quasi identique à une fonction classique du programme.