Cet article présente un exemple simple d'utilisation de l'API de Yahoo!Search BOSS dans une chaîne de traitements UIMA.

Yahoo!Search BOSS (Build your Own Search Service) est un service permettant de construire et d'exécuter des requêtes vers le moteur de recherche Yahoo!.  L'utilisation de ce service est gratuite et illimitée après l'obtention d'une clé d'identification.
L'API (Java) de Yahoo!Search BOSS permet, en réponse à une requête, d'obtenir un flux de réponses en XML (voir exemple). Le parsing de ce flux de texte format XML permet notamment de récupérer les champs d'informations suivants :

• nombre de résultats d'une requête
• URL des sites proposés
• Résumés des sites proposés
• etc.

Un certain nombre de paramètres supplémentaires (proposition de variations orthographiques, filtre sur une langue particulière, filtre sur des noms de domaines particuliers, etc) font de ce service un outil intéressant pour des tâches de traitement automatique des langues.

Nous décrivons ci-dessous un exemple de scénario très simple pour intégrer ce service dans un composant d'analyse UIMA.

Scénario exemple

Nous disposons d'un composant UIMA capable de reconnaître les entités nommées dans les documents textuels, et en particulier des noms de personnes.
Le Type Personne est associé à cette information. Dans les exemples ci-dessous "Jacques Chirac" et "Barack Obama" sont annotés et sont une information de type Personne.


Dans notre scénario, nous souhaitons estimer la "popularité" de ces personnes en comptabilisant le nombre de documents du web indexé qui parlent de ces personnes. L'attribut popularité est ajouté au type Personne denotre type system

Composant d'annotation utilisant Yahoo!Search : PopularityAnnotation

Le fonctionnement de ce composant se scinde en quatres étapes principales :

• 1- La récupération de l'index des annotations Personne contenues dans le document analysé
• 2- La création/envoie de la requête à Yahoo!Search BOSS
• 3- L'analyse des résultats XML retournés par le service
• 4- La modification de l'annotation Personne courante

1- Récupérer l'index des annotations Personne

ré-écriture de la méthode process de la classe PopularityAnnotation :

@Override

    public void process(JCas jcas) throws AnalysisEngineProcessException {

            //récupération des annotations de type Personne

            AnnotationIndex idxPersonne=(AnnotationIndex) jcas.getAnnotationIndex(Personne.type);

            while (idxPersonne.hasNext()){

                Personne p = (Personne) idxPersonne.next();

                ...

            }

        }

2- Création/Envoie de la requête à Yahoo!Search BOSS

Pour chaque annotation Personne, c'est le texte couvert par l'annotation qui nous intéresse et que l'on souhaite rechercher sur Yahoo!Search

 while (idxPersonne.hasNext()){

                Personne p = (Personne) idxPersonne.next();

                String nomPersonne=p.getCoveredText();



                //Certains caractères spéciaux nécessitent d'être encodés pour respecter le protocole HTTP

                nomPersonne=URLEncoder.encode(nomPersonne, "UTF-8");



                // la variable bossID (String) est votre clé d'identification

                String maRequete = "http://boss.yahooapis.com/ysearch/web/v1/"+nomPersonne+"?appid="+bossID+"&format=xml";



                // envoie de la requête

               HttpClient  client = new HttpClient();

               GetMethod method = new GetMethod(maRequete);

               

                int statusCode = client.executeMethod(method);

        

                if (statusCode != HttpStatus.SC_OK) {

                 System.err.println("Method failed: " + method.getStatusLine());

                }

                InputStream rstream = null;

        

                // Réception de la réponse

                rstream = method.getResponseBodyAsStream();

                Document response = DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(rstream);



               ...

  }

NB : Quelques imports sont nécessaire dans l'entête de la classe PopularityAnnotation pour envoyer des requêtes et parser le document XML réceptionné :
import java.io.InputStream;
import java.net.URLEncoder;
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.xpath.XPath;
import javax.xml.xpath.XPathConstants;
import javax.xml.xpath.XPathFactory;
import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.HttpStatus;
import org.apache.commons.httpclient.methods.GetMethod;
import org.w3c.dom.Document;
import org.w3c.dom.NodeList;


3- Analyse des résultats XML
 
Une fois le document XML réponse donné par Yahoo, il reste à le parser pour accéder aux champs d'informations qui nous intéressent. Ici, seul le nombre de résultats de la requête nous intéresse.

while (idxPersonne.hasNext()){

    ...

   // Réception de la réponse

   rstream = method.getResponseBodyAsStream();

   Document response = DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(rstream);



   //Accès au champ de valeur @totalhits avec XPath

   XPathFactory factory = XPathFactory.newInstance();

   XPath xPath=factory.newXPath();



   NodeList nodes = (NodeList)xPath.evaluate("/ysearchresponse/resultset_web", response, XPathConstants.NODESET);

   int nodeCount = nodes.getLength();

   

   String totalhits="";

   for (int i = 0; i < nodeCount; i++) {

          totalhits = (String)xPath.evaluate("@totalhits", nodes.item(i), XPathConstants.STRING);

    }

}

Le schéma du flux XML est détaillé ici.

4- Modification de l'annotation Personne courante

Le nombre de documents indexés par Yahoo! contenant le nom de la personne courante est stockée dans la variable totalhits, il ne reste plus qu'à modifier l'annotation ...

while (idxPersonne.hasNext()){

     ...

     //modification de l'annotation Personne

    p.setPopularity(totalhits);

}