Comment créer et tester son entrepôt OAI

De Doc.

Sommaire

Comment créer son entrepôt OAI

Un entrepôt OAI consiste en un ensemble de logiciels capables d’extraire des notices à partir d’une base de données (catalogue ou autres), de les mettre en forme (par exemple : MODS), de les attribuer à des lots distincts selon le cas, et de répondre aux requêtes d’un moissonneur.

La mise en œuvre d’un entrepôt peut se faire, en principe, de deux façons différentes :

  1. utilisation d’un module interne au logiciel (ou progiciel) gérant la base de données ; c’est le cas pour les bases gérées par le logiciel de gestion de bibliothèques Aloès, utilisé chez plusieurs partenaires du Portail ;
  2. réalisation d’un logiciel externe, qui obtient les notices de la base en question de l’une de deux façons :
    1. par l’entremise de requêtes qu’il enverra selon que de besoin à la base pour en extraire les notices, ce qui lui permettra de les traiter à la volée ; ceci suppose que le logiciel gérant la base propose un volant de requêtes (appelé API en anglais – application programming interface).
    2. à la suite d’exports des notices effectués manuellement (ou de façon programmée) à l’aide d’une commande proposée par le logiciel gérant la base ; une fois ces exports finis, les notices pourront être traitées. Le prétraitement peut être plus ou moins complexe, selon que la commande d’export fournit des notices traitées ou brutes (comprenant, par exemple, des liens vers d’autres tables qu’il faut aussi exporter et traiter). C’est la solution qui a été adoptée pour créer un entrepôt à partir des notices gérées par le logiciel de gestion de bibliothèques Loris, utilisé chez un autre partenaire.

La réalisation du logiciel externe lui-même n’est pas difficile : il suffit d’utiliser un logiciel libre à l’instar de phpOAI2 (solution adoptée pour plusieurs des entrepôts participant au Portail). Un prétraitement développé spécifiquement sert à récupérer les notices de la base (soit à l’aide d’un API soit à partir d’un export), d’en extraire les contenus adéquats qui seront mis dans une base de données (MySQL, par exemple). phpOAI2 est alors paramétré pour produire, à partir de ces contenus, des notices au format souhaité (MODS, en l’occurrence). Il répondra ensuite aux requêtes de moisson lancées par le Portail.

Structure des notices d’un entrepôt

En réponse à des requêtes de moisson détaillée (ListRecords), l’entrepôt renvoie un ou plusieurs « paquets » de notices structurées en XML ainsi :

En-tête du paquet
Première notice du paquet
En-tête de la notice
Corps de la notice (métadonnées)
Seconde notice du paquet
En-tête de la notice
Corps de la notice (métadonnées)
Dernière notice du paquet
En-tête de la notice
Corps de la notice (métadonnées)
Pied de page du paquet

En-tête du paquet

Cet en-tête reprend les paramètres de la requête (le verbe et le format souhaité des métadonnées) et indique l’heure de réponse à la requête.

En-tête de chaque notice

Cet en-tête est essentiel au bon fonctionnement de la moisson, puisqu’il comprend :

  1. l’identifiant unique de la notice ;
  2. la date précise (« datestamp ») de la création ou dernière modification de la notice dans l’entrepôt (et non pas nécessairement de la notice bibliographique – par exemple – dont elle est dérivée : il se peut en effet qu’une évolution du logiciel de l’entrepôt altère le format dans lequel les notices y sont présentées sans que cela ne provienne des notices source) ;
  3. la liste du, ou des, lots (sets) auxquels cette notice appartient.

Corps de chaque notice

Il s’agit ici des métadonnées de la ressource décrite par chaque notice. Leur format, pour le Portail, doit être en mods.

Pied de page du paquet

Dans le cas où la réponse de l’entrepôt à une requête se compose de plusieurs paquets successifs, ce pied de page comprend nécessairement un jeton de continuation (resumption token) qui sera utilisé par le moissonneur afin d’obtenir le paquet suivant, et le nombre total de notices fournies en réponse (dans l’ensemble des paquets constituant cette réponse), ce qui permet au moissonneur de vérifier, de son côté, que cette moisson s’est bien effectuée.

Comment tester son entrepôt OAI

Une fois qu'un entrepôt a été mis en place, il est nécessaire de le tester avant que de demander son inclusion dans les moissons du Portail. Ces tests visent notamment à vérifier :

  1. que les réponses produites en XML aux requêtes de moisson sont syntaxiquement correctes ;
  2. que l'entrepôt répond correctement aux requêtes individuelles ("verbes") de moisson au-delà de la pure mise en forme en XML - par exemple, la présence d'entêtes pour chaque enregistrement, et surtout qu'une moisson complète s'effectue correctement via le mécanisme des jetons de continuation (resumption token) ;
  3. que la description des ressources en MODS est correcte.

Valider le XML

Il existe une pléthore de validateurs en ligne, par exemple celui du W3C (en anglais). Il faut leur fournir l'URL complète de la requête que l'on veut tester, par exemple ':
http://www2.univ-paris8.fr/DMCE/phpoai2/oai2.php?verb=Identify

Installer et utiliser un moissonneur de base

La première famille de tests ne peut réellement s'effectuer qu'en lançant un moissonneur - au moins en ce qui concerne une moisson complète destinée à tester aussi les jetons de continuation ; en ce qui concerne les requêtes (verbes) qui ne renvoient qu'une réponse simple (Identify, GetRecord), il suffit de les lancer à la main (le logiciel phpoai2 mentionné ci-dessus permet de le faire à partir de la page d'accueil de l'entrepôt qu'il génère).

Pour les requêtes plus complexes, il est possible d'installer un moissonneur minimal qui ne ferait que ces tâches-là, sans passer à l'indexation (ni a fortiori à un référencement). Une solution libre existe en Perl (un langage de script) et nécessite :

  1. l'installation de Perl - on recommande la distribution ActivePerl (testée sous Windows mais devrait fonctionner sur d'autres plateformes) ;
  2. l'installation du module Perl Net::OAI::Harvester (elle se fait via la commande Perl ppm).

Une fois ce moissonneur installé, il fournit, en sus des fonctions inhérentes, quelques commandes de base, que l'on peut lancer en mode ligne de commande :

oai-listsets

Ce script de commande demande à l'entrepôt la liste des lots (sets) qu'il annonce détenir ; la syntaxe de cette commande est la suivante :

oai-listsets --baseURL=URL-de-base-de-l'entrepôt

L'exemple suivant fournira la liste des lots de l'entrepôt OAI du catalogue de la BnF :

oai-listsets --baseURL=http://catoai.bnf.fr/oai2/OAIHandler

oai-listrecords

Ce script de commande effectue une moisson complète du Portail, au cours de laquelle il affiche à l'écran les identifiants des notices moissonnées et quelques informations qui s'y trouvent (titre, notamment), ainsi que le jeton de continuation présent à la fin de chaque paquet de notices ; sa syntaxe est la suivante :

oai-listrecords --baseURL=URL-de-base-de-l'entrepôt --metadataPrefix=format

Ne pas oublier de spécifier mods comme format...

Si l'on redirige la sortie vers un fichier, les informations concernant les enregistrements s'y retrouveront, tandis qu'à l'écran ne s'afficheront que les jetons de continuation :

oai-listrecords --baseURL=URL-de-base de-l'entrepôt --metadataPrefix=format > nom-du-fichier

On peut modifier ce script afin qu'il affiche en sus du jeton, le numéro de série du paquet et l'heure précise à laquelle le paquet a été renvoyé, ce qui facilite l'interprétation de problèmes, par exemple : laps de temps trop long entre requêtes et réponses, plantages à un paquet particulier (ou de façon aléatoire - ce qu'on peut constater en lançant plusieurs fois ce script). L'affichage se présente alors ainsi :

1 16:02:44  using resuption token: 1383145359645
2 16:02:48  using resuption token: 1383145364273
3 16:02:51  using resuption token: 1383145367897
4 16:02:55  using resuption token: 1383145371457
5 16:02:59  using resuption token: 1383145375129
6 16:03:02  using resuption token: 1383145378943
7 16:03:06  using resuption token: 1383145382661
8 16:03:10  using resuption token: 1383145386346
9 16:03:14  using resuption token: 1383145390548
10 16:03:17  using resuption token: 1383145394128
11 16:03:20  using resuption token: 1383145397248
12 16:03:23  using resuption token: 1383145400317
...

Pour ce faire :

  1. Rajouter après la ligne Pod::Usage; les deux lignes suivantes :
    use POSIX qw(strftime);
    my ( $paquet );
  2. Rajouter après la ligne <code>$opts{ resumptionToken } = $records->resumptionToken(); la ligne suivante :
    print STDERR ++$paquet, " ",strftime("%H:%M:%S ", localtime(time())) ." ";

oai-dump

Ce script de commande moissonne tout l'entrepôt et enregistre les paquets dans leur totalité dans un répertoire spécifié dans la commande, ce qui est utile pour voir la totalité des paquets (si la moisson se termine bien) et en examiner les contenus, ce qui est utile pour l'étape suivante.

Sa syntaxe est la suivante :

oai-dump URL-de-base-de-l'entrepôt

Attention :

  1. La syntaxe ici est différente, on ne doit pas mentionner <code>--baseURL=.
  2. Ce script ne permet pas de choisir le format des notices, il ne moissonne que du Dublin Core. Il faut donc le modifier, et y remplacer la seule occurrence de oai_dc par mods.

Valider le MODS

À ce stade, la vérification ne peut que s'effectuer manuellement, en consultant des notices en MODS prises sélectivement dans le résultat de la moisson.

Outils personnels