diff --git a/README.md b/README.md index 01dc8af..c14d25a 100644 --- a/README.md +++ b/README.md @@ -1,98 +1,47 @@ api-wos =============== -Scripts pour se connecter à l’API WoS (Web of Science) pour l’interroger et télécharger un corpus de notices. Chaque session se passe en 5 étapes avec un script `bash` dédié à chacune de ces étapes : +Scripts pour interroger l’API WoS (Web of Science) et télécharger un corpus de notices en utilisant soit le protocole REST, soit le protocole SOAP. +## REST + +L’interrogation et le téléchargement d’un corpus se fait sans avoir à ouvrir une session et l’authentification se fait uniquement à l’aide d’une clé. +Les différentes étapes se font avec un script `bash` dédié : + +| Étapes | Scripts | +| ------ | ------- | +| Interrogation de l’API | `rWosQuery.sh` | +| Téléchargement des notices | `rWosRetrieve.sh` | + +Les notices obtenue peuvent être au format JSON ou au format XML au choix. + + +## SOAP + +Avec le protocole SOAP, il est nécessaire de se connecter et d’ouvrir une session pour pouvoir interagir avec l’API WoS. +L’authentification se fait avec un nom d’utilisateur et un mot de passe et il y a 5 étapes différentes, chacune réalisée avec un script `bash` dédie : + | Étapes | Scripts | | ------ | ------- | | Connexion à l’API | `WosConnect.sh` | | Interrogation de l’API | `WosQuery.sh` | | Téléchargement des notices | `WosRetrieve.sh` | | Déconnexion | `WosClose.sh` | -| Extraction des notices | `WosDecode.sh` | - +| Extraction des notices | `WosDecode.sh` | 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`. +Les notices obtenues sont uniquement au format JSON. -## WosConnect.sh +## Tables WoS -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. +Certains paramètres de l’interrogation de l’API et du téléchargement de notices sont limités à une liste finie ou sont sous forme de codes. +La première table n’est utile que pour l’interrogation alors que les deux suivantes sont utiles si on veut modifier l’ordre des notices du corpus +ou la liste des champs affichés. Comme on peut déjà décharger des notices lors de l’interrogation, il est important dans ce cas d’utiliser +les mêmes options de tri et/ou de visualisation lors du téléchargement. -### Usage - -```bash - WosConnect.sh -u utilisateur [ -c cookies.txt ] - WosConnect.sh -h -``` - -### Options - -```txt - -c indique le nom du fichier qui recevra les cookies (“cookies.txt” - par défaut) - -h affiche cette aide - -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 - -```bash - WosQuery.sh -s sid -q requête [ -p (début:fin|[124]week) ] - [ -b [WOS:]base ]* [ -f champs ]* [ -t CH:[AD] ] - [ -n notices ] [ -c cookies.txt ] [ -i ] - WosQuery.sh -h -``` - -### Options principales - -```txt - -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 - -```txt - -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) - -c indique le nom du fichier qui recevra les cookies (“cookies.txt” - par défaut) - -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”) - -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 -``` ### Bases WoS @@ -150,7 +99,8 @@ | contributor | keywords_plus | titles | | doctypes | language | UID | -### Critère de tri + +### Critères de tri Enfin, il est possible avec l’option “-t” de trier les résultats en fonction d'un champ, désigné par une abréviation à 2 lettres majuscules, dans le sens croissant (A) ou décroissant (D). Le tableau suivant donne la liste de ces champs et leur abréviation. @@ -172,172 +122,3 @@ À noter que les champs `RS` et `TC` ne peuvent être triés que dans le sens décroissant (D). - -## 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 : -```bash - export WOS_DELAY=3 -``` - - -### Usage - -```bash - WosRetrieve.sh -s sid -q queryId -n nb_notices -r résultat - [ -o offset ] [ -t taille ] [ -c cookies.txt ] - WosRetrieve.sh -h -``` - -### Options - -```txt - -c indique le nom du fichier qui recevra les cookies (“cookies.txt” - par défaut) - -h affiche cette aide - -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 indique le nombre de notices (entre 1 et 100) à 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 - -```bash - WosSearchByDoi.sh -s sid -d (fichier|-) -r (résultats|-) - [ -p (début:fin|[124]week) ] [ -b [WOS:]base ]* - [ -f champs ]* [ -c cookies ] [ -i ] - WosSearchByDoi.sh -h -``` - -### Options principales - -```txt - -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 - -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” - -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 -``` - -#### Autres options - -```txt - -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) - -c indique le nom du fichier qui recevra les cookies (“cookies.txt” - par défaut) - -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 -``` - - -## WosClose - -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 - -```bash - WosClose.sh -s sid [ -c cookies.txt ] - WosClose.sh -h -``` - -### Options - -```txt - -c indique le nom du fichier qui recevra les cookies (“cookies.txt” - par défaut) - -h affiche cette aide - -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. - -```bash - 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 - -```bash - WosDecode.sh -f (fichier[,fichier]*|-) [ -p programme ] [ -s sortie ] - WosDecode.sh -h -``` - -### Options - -```txt - -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](https://fr.wikipedia.org/wiki/Lex_(logiciel) qui se compile avec `flex` et `gcc`. Les différentes étapes sont : - -```bash - 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 : - -```bash - 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”. - - -