SOAP

Scripts pour se connecter à l’API WoS (Web of Science) pour l’interroger et télécharger un corpus de notices en utilisant le protocole SOAP. Chaque session se passe en 5 étapes avec un script bash dédié pour chacune de ces étapes :

Dans le cas particulier d’une recherche à partir d’une liste de DOIs, on utilise le script WosSearchByDoi.sh qui fait à la fois l’interrogation de l’API et le téléchargement des notices, remplaçant ainsi les scripts WosQuery.sh et WosRetrieve.sh.

Ces scripts ont besoin pour fonctionner de trois programmes qui sont généralement présents dans les distributions Unix/Linux :

• base64
• curl
• xmllint

En plus, le dernier script a besoin du programme C decode_wos dont le programme source, decode_wos.l, doit être compilé avec flex et gcc.

Pour les scripts communiquant avec l’API, c’est-à-dire les 4 premiers, toutes les informations renvoyées par le programme curl sur la sortie standard ou sur l’erreur standard sont conservées dans deux fichiers, respectivement WosApiOut.txt et WosApiErr.txt.

WosConnect.sh

Ce script permet la connexion à l’API WoS à l’aide d'un nom d’utilisateur et un mot de passe. En cas de succès, le script renvoie un identifiant de session (SID) à utiliser lors des étapes suivantes. Par souci de sécurité, il n’y a pas d’option pour le mot de passe en ligne de commande. Il sera demandé par la suite de façon plus sûre.

Usage

    WosConnect.sh -u utilisateur [ -j cookie_jar ]
    WosConnect.sh -h

Options

    -h  affiche cette aide
    -j  indique le nom du fichier qui recevra les cookies (“cookies.txt”
        par défaut)
    -u  indique le nom de l’utilisateur (login).

WosQuery.sh

Ce script permet l’interrogation de l’API WoS à l’aide d’une requête en utilisant l’identifiant SID. Par défaut, l’interrogation se fait sur l’ensemble des bases WoS et retourne un numéro de requête (queryId), le nombre de notices trouvées, le nombre total de notices dans les bases WoS interrogées ainsi que 5 notices complètes. Il est possible de limiter la recherche à certaines bases WoS avec l’option “-b” et on peut choisir de ne garder que certains champs dans les notices grâce à l’option “-f”. À noter que quelque soit le nombre de notices trouvées, on ne peut en télécharger que 100 000 au maximum. Au-delà, il faut faire plusieurs requêtes en indiquant, avec l’option “-p”, des périodes de temps successives. Les dates de début et de fin de période correspondent aux dates auxquelles les notices sont ajoutées à la base. Pour les personnes faisant une veille continue sur WoS, il est également possible de demander à ne considérer que les notices des 1, 2 ou 4 dernières semaines, toujours avec l’option “-p”.

Usage

    WosQuery.sh -s sid -q requête [ -p (début:fin|[124]week) ]
                [ -b [WOS:]base ]* [ -f champs ]*  [ -t CH:[AD] ]
                [ -n notices ] [ -j cookie_jar ] [ -i ]
    WosQuery.sh -h

Options principales

    -h  affiche cette aide 
    -p  limite la recherche dans la base de données à la période indiquée
        sous forme aaaa-mm-jj:aaaa-mm-jj (e.g., “2000-01-01:2020-07-31”)
        ou sous forme “1week”, “2week” ou “4week” 
    -q  fournit la requête à envoyer (entre simples ou doubles quotes si 
        elle contient des espaces ou des caractères spéciaux) 
    -s  indique le jeton d’authentification “SID” obtenu avec le programme
        d’authentification à l’API WoS

Autres options

    -b  limite la recherche à une ou plusieurs bases (e.g. “WOS:SCI”).
        Cette option est répétitive et “WOS:” est facultatif (par défaut,
        la recherche se fait sur l’ensemble du WoS)
    -f  limite les champs présents dans les notices téléchargées. Cette
        option est répétitive (par défaut, tous les champs sont présents)
    -i  ajoute dans la réponse de l’API la liste des identifiants WoS des
        notices retournées (5 par défaut ou valeur de l’option “-n”)
    -j  indique le nom du fichier qui recevra les cookies (“cookies.txt”
        par défaut)
    -n  indique le nombre de notices, entre 1 et 100, à retourner (5 par
        défaut)
    -t  trie les résultats sur un champ (nom abrégé à 2 majuscules) de
        façon croissante (A) ou décroissante (D) ou par pertinene (RS)
        forcément décroissante

WosRetrieve.sh

Ce script permet de télécharger les notices trouvées lors de l’interrogation de l’API WoS en utilisant l’identifiant SID et le numéro de requête (queryId) obtenu à l’étape précédente. En cas d’interruption du transfert, il est possible de reprendre le téléchargement là où il s'est arrêté en indiquant un nouveau numéro de départ (option “-o”). Au cas où un paquet de notices a une taille trop élevée et se retrouve tronqué, vous pouvez relancer le téléchargement avec un nombre de notices plus petit (l’option “-t”). De même, si vous recevez un message signalant une limitation de la bande passante (bandwidth throttling), vous pouvez modifier le délai entre deux itérations (1 seconde par défaut) avec la variable d’environnement WOS_DELAY. Par exemple, pour passer à un délai de 3 secondes :

    export WOS_DELAY=3

Usage

    WosRetrieve.sh -s sid -q queryId -n nb_notices -r résultat
                   [ -f champs ]* [ -t CH:(A|D) ] [ -i ]
                   [ -o offset ] [ -T taille ] [ -j cookie_jar ]
    WosRetrieve.sh -h

Options

    -f  limite les champs présents dans les notices téléchargées. Cette
        option est répétitive (par défaut, tous les champs sont présents)
    -h  affiche cette aide
    -i  ajoute dans la réponse de l’API la liste des identifiants WoS des
        notices retournées (5 par défaut ou valeur de l’option “-n”)
    -j  indique le nom du fichier qui recevra les cookies (“cookies.txt”
        par défaut)
    -n  indique le nombre total de notices WoS à télécharger (la valeur
        maximale est donnée par le programme envoyant la requête à l’API
        WoS)
    -o  indique à partir de quel numéro (offset), on veut télécharger les
        notices, en particulier pour reprendre un téléchargement après un
        problème de connexion (1 par défaut)
    -q  indique le numéro de la requête “queryId” dont on veut télécharger
        les résultats
    -r  indique le nom du fichier résultat (pour la sortie standard, utiliser
        le tiret “-” comme argument de l’option)
    -s  indique le jeton d’authentification “SID” obtenu avec le programme
        d’authentification à l'API WoS
    -t  trie les résultats sur un champ (nom abrégé à 2 majuscules) de
        façon croissante (A) ou décroissante (D) ou par pertinence (RS)
    -T  indique le nombre de notices à télécharger à chaque itération
        (100 par défaut)

WosSearchByDoi.sh

Ce script permet à la fois l’interrogation de l’API WoS à partir d’une liste de DOIs et le téléchargement des notices trouvées en utilisant l’identifiant SID. Fondamentalement, les options sont les mêmes que pour le script WosQuery.sh. La seule différence, c’est qu’on a un fichier avec les DOIs en entrée et un fichier de résultats en sortie.

Usage

    WosSearchByDoi.sh -s sid -d (fichier|-) -r (résultats|-) [ -f champs ]*
                      [ -T taille ] [ -j cookie_jar ] [ -i ]
    WosSearchByDoi.sh -h

Options principales

    -d  indique le nom du fichier avec la liste des DOIs à chercher. Si on
        a un tiret “-” en argument, la liste de DOIs est lue sur l’entrée
        standard
    -h  affiche cette aide
    -r  indique le nom du fichier résultat (pour la sortie standard, utiliser
        le tiret “-” comme argument de l’option)
    -s  indique le jeton d’authentification “SID” obtenu avec le programme
        d‘authentification à l‘API WoS
    -T  indique le nombre de notices à télécharger à chaque itération
        (100 par défaut)

Autres options

    -f  limite les champs présents dans les notices téléchargées. Cette
        option est répétitive (par défaut, tous les champs sont présents)
    -i  ajoute dans la réponse de l’API la liste des identifiants WoS des
        notices retournées à chaque itération
    -j  indique le nom du fichier qui recevra les cookies (“cookies.txt”
        par défaut)

WosClose.sh

Ce script permet de terminer une session d’interrogation de l’API WoS, après une ou plusieurs itérations de reqêtes et de téléchargements. À noter que l’identifiant de session (SID) a une durée de vie limitée, donc, la session s’arrêtera de toute façon.

Usage

    WosClose.sh -s sid [ -j cookie_jar ]
    WosClose.sh -h

Options

    -h  affiche cette aide
    -j  indique le nom du fichier qui recevra les cookies (“cookies.txt”
        par défaut)
    -s  indique le jeton d’authentification “SID” obtenu avec le programme
        d’authentification à l'API WoS

WosDecode.sh

Que se soit en utilisant le script WosRetrieve.sh ou le script WosSearchByDoi.sh, le fichier de résultats est souvent la concaténation de plusieurs fichiers. Dans chacun de ses fichiers, les notices sont encodées au sein de l’élément records. Le script WosDecode.sh permet de remettre les notices au format XML et d’en faire un fichier « bien formé ». Il utilise le programme C decode_wos qu’il faut compiler à partir du fichier source decode_wos.l .

Ce script peut traiter plusieurs fichiers en même temps soit en les listant avec l’option “-f”, soit en les envoyant par l’entrée standard, soit par un mixte des deux. Par exemple, si on a 3 fichiers (fic1.xml, fic2.xml et fic3.xml) que l’on veut réunir en un seul fichier final, on peut utiliser les commandes suivantes qui donnent toutes le même résultat.

    WosDecode.sh -f fic1.xml -f fic2.xml -f fic3.xml
    WosDecode.sh -f fic1.xml,fic2.xml,fic3.xml
    WosDecode.sh -f "fic1.xml fic2.xml fic3.xml"
    cat fic1.xml fic2.xml fic3.xml | WosDecode.sh -f -
    cat fic2.xml | WosDecode.sh -f fic1.xml,-,fic3.xml

Usage

    WosDecode.sh -f (fichier[,fichier]*|-) [ -p programme ] [ -s sortie ]
    WosDecode.sh -h

Options

    -f  indique le nom du ou des fichiers à traiter. Cette option est
        répétitive. Vous pouvez également utiliser une liste de fichiers
        séparés par des virgules (mais sans espace) ou mettre un tiret
        si les données sont envoyées sur l’entrée standard
    -h  affiche cette aide
    -p  indique où trouver le programme “decode_wos” s’il n’est pas dans
        un des répertoires donnés par la variable $PATH
    -s  indique le nom du fichier de sortie. Sinon, les données sont
        envoyées sur la sortie standard

decode_wos

Programme C qui permet d’ajouter des sauts de ligne dans les fichiers reçus de l’API WoS tout en décodant les entités caractères de façon à avoir des notices individualisées au format XML. Comme chaque notice est sur une ligne, il devient alors possible de les filtrer et de les réunir en un seul fichier.

Compilation

Le programme source, decode_wos.l, est un fichier Lex qui se compile avec flex et gcc. Les différentes étapes sont :

    flex -t decode_wos.l > decode_wos.c
    gcc -c -o decode_wos.o decode_wos.c
    gcc decode_wos.o -lfl -o decode_wos

Sous MacOs, la dernière commande est :

    gcc decode_wos.o -ll -o decode_wos

Vous pouvez déplacer le programme decode_wos dans un des répertoires donnés par la variable globale $PATH ou indiquer sa position au script WosDecode.sh avec l’option “-p”.