diff --git a/REST/README.md b/REST/README.md index 99b947e..9520fdb 100644 --- a/REST/README.md +++ b/REST/README.md @@ -1,3 +1,185 @@ REST ========== + +Scripts pour se connecter à l’API WoS (Web of Science) pour l’interroger et télécharger un corpus de notices, au format JSON ou au format XML, en utilisant +le protocole [REST](https://fr.wikipedia.org/wiki/Representational_state_transfer). Il n’y a pas de session à proprement parler, mais se passe en 2 étapes +avec un script `bash` dédié pour chacune de ces étapes : + + +| Étapes | Scripts | +| ------ | ------- | +| Interrogation de l’API | `WosQuery.sh` | +| Téléchargement des notices | `WosRetrieve.sh` | + + +Dans le cas particulier d’une recherche à partir d’une liste de DOIs, on utilise le script `rWosSearchByDoi.sh` qui fait à la fois l’interrogation de l’API et le téléchargement des notices, remplaçant ainsi les scripts `rWosQuery.sh` et `rWosRetrieve.sh`. + +Ces scripts ont besoin pour fonctionner de trois programmes qui sont généralement présents dans les distributions Unix/Linux : + + - `curl` + - `jq` + - `xmllint` + +Pour tous ces scripts, 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.json` ou `WosApiOut.xml` (suivant le format des notices), et `WosApiErr.txt`. + + +## rWosQuery.sh + +Ce script permet l’interrogation de l’API WoS à l’aide d'une clé chiffrée. Par souci de sécurité, il n’y a pas d’option pour la clé en ligne de commande. +Elle sera demandé par la suite de façon plus sûre. 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”, on peut choisir de ne garder que certains champs dans les notices grâce à l’option “-f” +et on peut modifier l’ordre de tri des notices avec l’option `-t`. + + +### Usage + +```bash + rWosQuery.sh -q 'requête' [ -r (résultats|-) ] [ -n nb_notices ] + [ -[cmp] début:fin ] [ -l [0-9]+[DWMY] ] [ -b [WOS:]base ]* + [ -f champs ]* [ -t CH:(A|D)[,CH:(A|D)]* ] + [ -j cookie_jar ] [ -ix ] + rWosQuery.sh -h +``` + +À noter que les options `-c`, `-l`, `-m` et `-p` be sont pas compatibles entre elles et on ne peut en utiliser +au plus qu'une seule. Les valeurs possibles pour les options `-b`, `-f` et `-t` sont données dans les [tables WoS](https://gitbucket.inist.fr/tdm/api-wos#tables-wos) +de la page rincipale. + + +### Options principales + +```txt + -c limite la recherche dans la base de données aux dates de création + des notices indiquées sous la forme aaaa-mm-jj:aaaa-mm-jj (comme par + exemple, “2000-01-01:2020-07-31”) + -h affiche cette aide + -l limite la recherche dans la base de données aux dates de chargement + des notices indiquées sous la forme d’un nombre de jours (D), de + semaines (W), de mois (M) ou d’années (Y). Les valeurs acceptées vont + de “0D” à “6D”, de “1W” à “52W”, de “1M” à “12M” et de “0Y” à “10Y” + -m limite la recherche dans la base de données aux dates de modification + des notices indiquées sous la forme aaaa-mm-jj:aaaa-mm-jj (comme par + exemple, “2000-01-01:2020-07-31”) + -p limite la recherche dans la base de données aux dates de publication + indiquées sous la forme aaaa-mm-jj:aaaa-mm-jj (comme par exemple, + “2000-01-01:2020-07-31”) + -r indique le nom du fichier où placer les notices téléchargées (mettre + un tiret pour indiquer la sortie standard) + -q fournit la requête à envoyer (entre simples ou doubles quotes si + elle contient des espaces ou des caractères spéciaux) + -x indique que les notices doivent être en XML au lieu de JSON, le format + par défaut +``` + + +### 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) + -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 0 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 pertinence (RS) + forcément décroissante +``` + + +## rWosRetrieve.sh + +Ce script permet de télécharger les notices trouvées lors de l’interrogation de l’API WoS en utilisant la clé d’identification +(demandée hors ligne de commande, par sécurité) 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”). +Si vous avez utilisé les options `-f` et/ou `-t` lors de l’interrogation de l’API, vous devez utiliser les mêmes options avec les mêmes valeurs pour +décharger le corpus de notices +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 + rWosRetrieve.sh -q queryId -n nb_notices -r (résultats|-) [ -o offset ] + [ -f champs ]* [ -t CH:(A|D)[,CH:(A|D)]* ] + [ -j cookie_jar ] [ -ix ] + rWosRetrieve.sh -h +``` + +### Options + +```txt + -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 + -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) + -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) + forcément décroissante + -x indique que les notices doivent être en XML au lieu de JSON, le format + par défaut +``` + + +## rWosSearchByDoi.sh (en cours de réécriture) + +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 la clé d’identification. +Contrairement au script `rWosQuery.sh`, on n’a pas d’options pour limiter la recherche par période ou par base. On n’a pas non plus d’option de tri parce que la +recherche se fait par paquet de 100 DOI maximum et le tri se ferait au sein de chaque paquet au lieu de se faire sur l’ensemble du corpus. +En fait, on récupère les notices dans l’ordre des DOI. + + +### Usage + +```bash + rWosSearchByDoi.sh -d (fichier|-) -r (résultats|-) [ -f champs ]* + [ -j cookie_jar ] [ -ix ] + rWosSearchByDoi.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 + -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 + -j indique le nom du fichier qui recevra les cookies (“cookies.txt” + -r indique le nom du fichier résultat (pour la sortie standard, utiliser + le tiret “-” comme argument de l’option) + -x indique que les notices doivent être en XML au lieu de JSON, le format + par défaut +``` + + + diff --git a/REST/rWosQuery.sh b/REST/rWosQuery.sh index 638ae91..caa299d 100755 --- a/REST/rWosQuery.sh +++ b/REST/rWosQuery.sh @@ -4,8 +4,8 @@ # Initialisation des variables pour les options programme=$(basename $0) substitut=$(echo $programme | sed 's/./ /g') -version='0.9.4' -modif='13/07/2022' +version='0.9.5' +modif='22/07/2022' function usage { @@ -26,7 +26,7 @@ $programme -q 'requête' [ -r (résultats|-) ] [ -n nb_notices ] $substitut [ -[cmp] début:fin ] [ -l [0-9]+[DWMY] ] [ -b [WOS:]base ]* $substitut [ -f champs ]* [ -t CH:(A|D)[,CH:(A|D)]* ] - $substitut [ -j cookie_jar ] [ -i ] + $substitut [ -j cookie_jar ] [ -ix ] $programme -h Options principales diff --git a/REST/rWosRetrieve.sh b/REST/rWosRetrieve.sh index 28d3466..2d08baa 100755 --- a/REST/rWosRetrieve.sh +++ b/REST/rWosRetrieve.sh @@ -4,13 +4,13 @@ # Initialisation des variables pour les options programme=$(basename $0) substitut=$(echo $programme | sed 's/./ /g') -version='0.4.1' -modif='15/07/2022' +version='0.5.2' +modif='22/07/2022' function usage { echo "Usage : $programme -q queryId -n nb_notices -r (résultats|-) [ -o offset ] " -echo " $substitut [ -n nb_notices ] [ -f champs ]* [ -t CH:(A|D)[,CH:(A|D)]* ] " +echo " $substitut [ -f champs ]* [ -t CH:(A|D)[,CH:(A|D)]* ] " echo " $substitut [ -j cookie_jar ] [ -ix ] " echo " $programme -h " } @@ -21,12 +21,20 @@ Usage ===== - $programme -q queryId -n nb_notices -r (résultats|-) [ -o offset ] [ -t taille ] + $programme -q queryId -n nb_notices -r (résultats|-) [ -o offset ] + $substitut [ -f champs ]* [ -t CH:(A|D)[,CH:(A|D)]* ] + $substitut [ -j cookie_jar ] [ -ix ] $programme -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 + -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) @@ -37,8 +45,11 @@ les résultats -r indique le nom du fichier résultat (pour la sortie standard, utiliser le tiret “-” comme argument de l’option) - -t indique le nombre de notices à télécharger à chaque itération - (100 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 pertinence (RS) + forcément décroissante + -x indique que les notices doivent être en XML au lieu de JSON, le format + par défaut N.B. : la variable d‘environnement WOS_DELAY permet de modifier le délai entre deux itérations (1 seconde par défaut). Sa valeur doit être @@ -56,7 +67,7 @@ format='json' # Options -while getopts f:hn:o:q:r:t:x i +while getopts f:hij:n:o:q:r:t:x i do case $i in f) champs+=$OPTARG;; @@ -99,8 +110,7 @@ then if [[ $offset -gt $nb ]] then - echo "Erreur : offset supérieur au nombre de notices" >&2 - exit 2 + echo "Attention : offset supérieur au nombre de notices" >&2 fi else echo "Erreur : l’offset (option “-o”) doit être un entier positif non nul" >&2 @@ -113,13 +123,13 @@ sortie='/dev/fd/1' fi -if [[ -z $cookie ]] +if [[ -z $cookiejar ]] then - cookie='cookies.txt' + cookiejar='cookies.txt' fi # Vérification de la présence des programmes -# “curl” et “jq” +# “curl”, “jq” et “xmllint” for i in curl jq xmllint do prog=$(which $i 2> /dev/null) @@ -239,7 +249,7 @@ if [[ $3 = 'json' ]] then - curl -X GET -b $cookie -c $cookie -v "$url/query/$qid?count=$2&firstRecord=$1&$options" \ + curl -X GET -b $cookiejar -c $cookiejar -v "$url/query/$qid?count=$2&firstRecord=$1&$options" \ -H "X-ApiKey: $key" 2> $err | jq . 2>> $err > $out cr=$? @@ -276,7 +286,7 @@ elif [[ $3 = 'xml' ]] then - curl -X GET -b $cookie -c $cookie -v "$url/query/$qid?count=$2&firstRecord=$1&$options" \ + curl -X GET -b $cookiejar -c $cookiejar -v "$url/query/$qid?count=$2&firstRecord=$1&$options" \ -H "X-ApiKey: $key" -H "Accept: application/xml" 2> $err | xmllint -format - 2>> $err > $out cr=$?