Les instructions et paramètres OAI
Ce document a pour objectif de décrire les différentes instructions OAI. Cette description est intéressante et ce même si par moment elle peut paraître technique. En effet, elle permet de voir la totalité des fonctionnalité du protocole et donc de mieux comprendre comment on peut l'utiliser pour atteindre nos objectifs d'interopérabilité.
De plus, il ne faut pas oublier que l'on peut tester le protocole OAI simplement en utilisant un navigateur Web pour moissonner. En connaissant les différentes instructions OAI et leurs paramètres, vous pourrez ainsi explorer et tester à votre guise.
Il existe également un service pratique sur le Web, le Open Archives Initiative - Repository Explorer 1 . Il vous permet, à l'aide d'une interface Web, de lancer des instructions OAI à différents entrepôts et de voir les réponses, et ce sans complexité technique. Vous devez toutefois comprendre le protocole pour utiliser efficacement cet outil.
1) Les instructions et leurs paramètres
Le protocole OAI est composé de six instructions (verb en anglais). Le tableau suivant décrit ces instructions, en mentionnant les paramètres qui peuvent être associés. Un paramètre suivi d'un astérisque indique qu'il est obligatoire, mais l'astérisque ne fait pas partie du nom du paramètre.
Instruction | Paramètres | Description |
|---|---|---|
Identify | Demande des informations à propose de l'entrepôt. Ces informations sont plutôt destinées à une consommation humaine, et non informatique. | |
ListMetadataFormats | identifier | Demande la liste des formats disponibles. Sans paramètre, tous les formats disponibles pour au moins un item sont retournés. Avec le paramètre identifier , les formats disponibles pour un item précis sont retournés. |
ListSets | resumptionToken | Demande la liste des ensembles disponibles dans cet entrepôt. La réponse peut être sur plusieurs pages. |
ListIdentifiers | from until metadataPrefix* set resumptionToken | Demande la liste des identifiants des items d'un entrepôt. On peut limiter cette demande par date et par ensemble. La réponse peut être sur plusieurs pages. |
ListRecords | from until metadataPrefix* set resumptionToken | Demande la liste des enregistrements dans un format spécifique. On peut limiter cette demande par date et par ensemble. La réponse peut être sur plusieurs pages. Il s'agit de l'instruction la plus utile pour moissonner le contenu d'un entrepôt OAI . |
GetRecord | identifier* metadataPrefix* | Demande un enregistrement spécifique, par son identifiant, en indiquant le format souhaité. |
Un conseil pour retenir le nom exact des instructions et des paramètres : les instructions débutent par une majuscule, mais les paramètres débutent par une minuscule. Dans les deux cas, la première lettre de chaque partie significative suivante du nom est en majuscule.
La syntaxe pour utiliser ces instructions et paramètres dans une requête OAI est de la forme suivante :
[adresse de l'entrepôt]?verb=[instruction]&[paramètre]=valeur&[paramètre]=valeur
Voici un exemple avec deux paramètres :
2) Les paramètres
Le tableau précédent a montré les paramètres qui peuvent être utilisés dans une requête OAI. On en retrouve six seulement, qui sont décrits dans le tableau suivant.
Paramètre | Instructions associées | Description |
|---|---|---|
metadataPrefix | ListIdentifiers ListRecords GetRecord | Indique le format de métadonnées à utiliser, par son préfixe. Le préfixe du format Dublin Core, obligatoire, est oai_dc . |
identifier | ListMetadataFormats GetRecord | Indique un item précis par son identifiant. |
from | ListIdentifiers ListRecords | Permet la moisson sélective en indiquant de retourner des enregistrements correspondant à des items modifiés depuis une certaine date. La date doit être en UTC exprimée selon la norme ISO8601, par exemple 2002-02-08T08:55:46Z ou encore 2002-02-08 , selon la granularité acceptée par l'entrepôt. |
until | ListIdentifiers ListRecords | Permet la moisson sélective en indiquant de retourner des enregistrements correspondant à des items modifiés avant une certaine date. La date doit être en UTC exprimée selon la norme ISO8601, par exemple 2002-02-08T08:55:46Z ou encore 2002-02-08 , selon la granularité acceptée par l'entrepôt. |
set | ListIdentifiers ListRecords | Permet la moisson sélective en indiquant de retourner des enregistrements qui font partie d'un ensemble précis. |
resumptionToken | ListSets ListIdentifiers ListRecords | Un entrepôt peut retourner les réponses à ces trois instructions en plusieurs pages pour limiter les ressources utilisées et les risques d'erreurs. Dans ce cas, avec chaque page, il doit retourner un code qui permet de demander la suite. Ce code doit être indiqué par ce paramètre lorsque le moissonneur demande cette suite. |
3) La moisson sélective
Les paramètres from , until et set permettent une moisson sélective, par date de modification pour les deux premiers et par ensemble pour le dernier.
3.1) Par date de modification
Les items exposés par un entrepôt OAI peuvent être modifiés. C'est le cas lorsqu'une fiche descriptive est corrigée. Mais une modification peut aussi être un ajout d'item, ou même la suppression d'un item (ce dernier cas sera traité plus loin).
Il serait inefficace qu'un moissonneur demande systématiquement les enregistrements correspondant à tous les items lorsqu'il moissonne un entrepôt. Un scénario plus logique consisterait, par exemple, à faire une moisson périodique (une fois par jour par exemple) et à demander seulement les enregistrement correspondant à des items modifiés depuis la dernière moisson (la veille par exemple).
Les paramètres from et until permettent de préciser les dates de modification lorsqu'on demande une liste d'identifiants ou une liste d'enregistrements. Le cas le plus fréquent sera l'utilisation du paramètre from avec comme valeur la date de la dernière moisson. Dans ce cas, l'entrepôt doit être en mesure de retourner uniquement les enregistrements qui ont été modifiés (ou ajoutés, ou détruits) depuis cette date. La nature de la réponse ne change pas, seul son contenu sera différent (ce ne seront pas nécessairement les mêmes enregistrements).
3.2) Par ensemble
Un entrepôt peut définir des ensembles (il s'agit d'une fonctionnalité optionnelle pour un entrepôt OAI), et dans ce cas un item peut appartenir à un ou plusieurs ensembles. La sémantique des ensembles n'est bien sûr pas définie par le protocole. Il peut s'agir d'une liste de sujets (un sujet est un ensemble), d'une liste de types de documents (un type de documents est un ensemble), etc.
On peut connaître les ensembles disponibles dans un entrepôt OAI avec le verbe ListSets . Mais surtout, on peut moissonner des enregistrements qui sont dans un ensemble (et non tous les enregistrements) en utilisant le paramètre set avec les instructions ListIdentifiers et ListRecords . La moisson sélective par ensemble peut être combinée avec la moisson sélective par date.
La nature de la réponse n'est pas modifiée par l'utilisation du paramètre set , seul son contenu sera différent (ce ne seront pas nécessairement les mêmes enregistrements).
3.3) Les enregistrements supprimés
Un entrepôt OAI peut (ce n'est pas obligatoire) gérer la notion d'enregistrements supprimés. Cette fonctionnalité est très utile lorsque l'on utilise le protocole OAI pour constituer et mettre à jour un ensemble de données depuis différentes sources. Si le moissonneur n'a pas connaissance des enregistrements supprimés, il ne saura pas quels sont les données à supprimer de son côté, et son contenu ne reflétera pas fidèlement le contenu des sources moissonnées.
Lorsqu'on fait une moisson sélective par date, ou lorsqu'on demande un enregistrement précis, un entrepôt qui supporte les enregistrements supprimés doit les indiquer, en ne retournant pas le contenu de l'enregistrement mais uniquement son en-tête, incluant son identifiant et sa date de suppression.
A noter que ce sont des enregistrements qui sont détruits, et non des items. La plupart des outils OAI ne permettent pas de gérer finement cette distinction toutefois.
4) Quelques exemples
Les URL ci-dessous permettent d'utiliser un navigateur Web pour explorer les différentes facettes du protocole OAI. Pour une exploration plus approfondie, nous vous conseillons d'utiliser Open Archives Initiative - Repository Explorer 2 .
4.1) Instruction Identify
L'instruction Identify permet de mieux connaître l'entrepôt. Nous allons travailler avec deux entrepôts, que nous présentons ici à l'aide de leur réponse Identify :
- Universidad Lyon 2 – Thèses électroniques
http://demeter.univ-lyon2.fr:8080/sdx/sdx/oai/theses/documents?verb=Identify- @rchiveSIC : Sciences de l'Information et de la Communication
http://archivesic.ccsd.cnrs.fr/perl/oai20?verb=Identify
La réponse nous indique que tous deux supportent les documents supprimés.
4.2) Instruction ListMetadataFormats
Les requêtes suivantes permettent de connaître les formats de métadonnées disponibles. Pour @rchiveSIC, nous avons les formats oai_dc et ccsd_tel :
http://archivesic.ccsd.cnrs.fr/perl/oai20?verb=ListMetadataFormats
Pour l'université de Lyon 2, nous avons les formats formats oai_dc et oai_etdms :
http://demeter.univ-lyon2.fr:8080/sdx/sdx/oai/theses/documents?verb=ListMetadataFormats
On peut également connaître les formats pour un enregistrement spécifique, par exemple :
4.3) Instruction ListSets
L'instruction ListSets permet de connaître les ensembles disponibles pour un entrepôt. Voici le résultat pour @rchiveSIC :
http://archivesic.ccsd.cnrs.fr/perl/oai20?verb=ListSets
On constate qu'il s'agit d'une liste de sujets. Pour l'Université de Lyon 2, les ensembles ne sont pas supportés :
http://demeter.univ-lyon2.fr:8080/sdx/sdx/oai/theses/documents?verb=ListSets
4.4) Instruction ListIdentifiers
L'instruction ListIdentifiers permet de connaître les identifiants, si ce sont les seules informations nécessaires. Sans critères de sélection, les deux entrepôts de test nous retournent ces informations :
http://archivesic.ccsd.cnrs.fr/perl/oai20?verb=ListIdentifiers&metadataPrefix=oai_dc
On peut modifier ces requêtes pour obtenir uniquement les enregistrements modifiés pendant l'année 2004 dans l'entrepôt @rchiveSIC :
Idem pour les enregistrements modifiés en janvier 2006 pour l'Université de Lyon 2 :
On constate que les deux entrepôts ne supportent pas la même granularité des dates, ce qui est prévu par le protocole OAI.
Pour une moisson périodique, on pourrait par exemple demander uniquement les enregistrements modifiés depuis décembre dernier :
On peut également s'intéresser uniquement à des enregistrements en géopolitique avec cette requête sur l'entrepôt @rchiveSIC :
http://archivesic.ccsd.cnrs.fr/perl/oai20?verb=ListIdentifiers&metadataPrefix=oai_dc&set=sic_geop
4.5) Instruction ListRecords
L'instruction ListRecords fonctionne de la même façon que ListIdentifiers , mais retourne les enregistrements complets. Nous reprenons ici les mêmes paramètres :
http://archivesic.ccsd.cnrs.fr/perl/oai20?verb=ListRecords&metadataPrefix=oai_dc
http://archivesic.ccsd.cnrs.fr/perl/oai20?verb=ListRecords&metadataPrefix=oai_dc&set=sic_geop
4.6) Instruction GetRecord
L'instruction GetRecord retourne un enregistrement uniquement. Voici deux URL pour retourner un item en deux formats différents dans l'entrepôt @rchiveSIC :
Voici des URL équivalents pour l'entrepôt de l'Université de Lyon 2 :