Skip to content

API SRU

Jump to bottom
PMoirez edited this page Nov 18, 2016 · 29 revisions

Service de Recherche SRU

Contexte

Cette API est une interface de recherche avec le moteur de recherche de Gallica. Il s'agit d'un web service rendant du XML, représentant les documents liés à une requête.

Nous avons implémenté le protocole de recherche SRU dans sa version 1.2 et dont la norme est disponible ici : Norme SRU

Nous avons décidé d'implémenter la partie recherche, ce qui se traduit par l'appel à un web service dont la syntaxe minimale est la suivante.

http://gallica.bnf.fr/SRU?version=1.2&operation=searchRetrieve&query=

  • version : la version de la norme SRU implémentée (ici, 1.2)
  • operation : l'opération à effectuer (ici, searchRetrieve)
  • query : la requête à effectuer pour obtenir les résultats souhaités. La valeur du paramètre query est écrit en langage CQL ("Contextual Query Language") dont la norme est décrite ici : Norme CQL

En plus de ces 3 paramètres obligatoires, il existe d'autres paramètres optionnels :

  • startRecord : il s'agit d'un chiffre compris entre 1 et le nombre maximal de résultats renvoyés par la requête (vous pouvez récupérer cette information dans le flux xml rendu dans l'élément srw:numberOfRecords)
  • maximumRecords : il s'agit du nombre de résultats retournés par le service SRU. Ce chiffre est compris entre 0 et 50 (au delà de 50, la valeur du paramètre est surchargée côté back-office par 50). Par défaut si ce paramètre est absent, la valeur est de 15.

Ces deux derniers paramètres permettent de paginer une liste de documents liés à une requête.

J'ai ma requête initiale :
http://gallica.bnf.fr/SRU?operation=searchRetrieve&version=1.2&query=%28gallica%20all%20%22toto%22%29&suggest=0

je peux la paginer comme suit http://gallica.bnf.fr/SRU?operation=searchRetrieve&version=1.2&query=%28gallica%20all%20%22toto%22%29&suggest=0&startRecord=15

puis http://gallica.bnf.fr/SRU?operation=searchRetrieve&version=1.2&query=%28gallica%20all%20%22toto%22%29&suggest=0&startRecord=30

etc...

Format du flux xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<srw:searchRetrieveResponse xmlns="http://gallica.bnf.fr/namespaces/gallica/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:oai_dc="http://www.openarchives.org/OAI/2.0/oai_dc/" xmlns:onix="http://www.editeur.org/onix/2.1/reference/" xmlns:srw="http://www.loc.gov/zing/srw/" xmlns:onix_dc="http://bibnum.bnf.fr/NS/onix_dc/">
    <srw:version>1.2</srw:version>
    <srw:echoedSearchRetrieveRequest>
        <srw:query>(dc.creator all "molière" or dc.contributor all "molière" )  and (dc.type all "monographie") and (provenance adj "bnf.fr")</srw:query>
        <srw:version>1.2</srw:version>
    </srw:echoedSearchRetrieveRequest>
    <srw:numberOfRecords>257</srw:numberOfRecords>
    <srw:records>
        <srw:record>
            <srw:recordSchema>http://www.openarchives.org/OAI/2.0/OAIdc.xsd</srw:recordSchema>
            <srw:recordPacking>xml</srw:recordPacking>
            <srw:recordData>
                <oai_dc:dc>
                    <dc:contributor>Lemaistre, Félix. Éditeur scientifique</dc:contributor>
                    <dc:creator>Molière (1622-1673)</dc:creator>
                    <dc:date>1867</dc:date> etc...

  • srw:searchRetrieveResponse est la racine du document xml conenant les espace de nom spécifique au srw (Search/Retrieve Web service) qui est le format xml de réponse à une requête sru

  • description de l'entête de la réponse qui rappelle des éléments généraux de la réponse à la requête

    • srw:version est la version du protocole SRU de la requête initiale
    • srw:echoedSearchRetrieveRequest est le rappel de la requête qui a donné cette réponse
    • srw:query : la requête en CQL
    • srw:numberOfRecords est le nombre total de résultat pour cette requête

  • les résultats de la requête

    • srw:records est l'enveloppe srw des résultats du flux xml
    • srw:record est l'enveloppe d'un résultat
    • srw:recordSchema décrit le format utilisé pour les données du résultat
    • srw:recordPacking décrit le type du format du résultat
    • srw:recordData contient le résultat dans le format et le type décrit dans recordSchema et recordPacking

Ensuite on trouve le résultat au format dublin core

En ce qui concerne le paramètre query en CQL, voici les spécificités de notre implémentation.

Les mots clés implémentés en CQL

###Liste des index de recherche

  • dc.title : il s'agit d'un champ texte libre permettant la recherche par mots dans l'index Titre

  • dc.creator : il s'agit d'un champ texte libre permettant la recherche par mots dans l'index des auteurs

  • dc.publisher : il s'agit d'un champ texte libre permettant la recherche par mots dans l'index éditeur

  • text : il s'agit d'un champ texte libre permettant la recherche par mots dans le texte des documents OCRisés

  • toc : il s'agit d'un champ texte libre permettant la recherche par mots dans le contenu d'une table des matières indexée

  • légendes : il s'agit d'un champ texte libre permettant la recherche par mots dans le contenu des légendes associées au document de type image, carte, ou objet

  • metadata : permet la recherche dans toutes les métadonnées de la notice du document numérique (titre,auteurs,éditeur etc...)

  • ISBN : il s'agit d'un champ texte libre permettant la recherche dans l'index ISBN

  • gallica : il s'agit d'un champ texte libre permettant la recherche par mots dans tout (métadonnés, texte, tdm etc ....)

  • dc.date : il s'agit d'un champ texte libre permettant la recherche dans l'index des dates d'édition (correspond à l’indexation de la balise dc:date, qui peut comporter différents types de formats d’années)

  • dc.type : il s'agit d'un champ texte libre permettant la recherche dans l'index des type de documents de la bibliothèque numérique. Les valeurs possibles sont monographie, carte, image, fascicule(pour les publication en série), manuscrit, partition, sonore (pour les documents avec du son) et objet. Cela correspond au type de document proposé dans la recherche avancée. exemple : http://gallica.bnf.fr/SRU?version=1.2&operation=searchRetrieve&query=dc.type any fascicule.

  • ocrquality : il s'agit d'un champ texte libre permettant la recherche dans l'index de qualité de la numérisation. La valeur est comprise entre 0 et 100. Exemple ocrquality any "099.99". Les guillemets sont importants et le format xxx.xx aussi. Ceci permet de récupérer une valeur de qualité de numérisation, 100.00 étant un ocr sans faute. Une fois traduit en nombre, cela nous permet cette règle métier,

    •   		si ocr >= 60 mode texte disponible, 

    •   		si ocr < 60 pas de mode texte

Cet index n'est pas interrogeable sur un range.

  • dewey : il s'agit d'un champ texte libre permettant la recherche dans l'index de classification dewey. La requête se fait sur l'indice dewey dont la spécification à la BnF est disponible ici

exemple: dewey any 1 =>les documents dont le "thème" Philosophie et psychologie

Voici la liste des indices et leur signification

			0 = Généralités
			1 = Philosophie et psychologie
			2 = Religion
			3 = Économie et société
			4 = Langues
			5 = Sciences
			6 = Techniques
			7 = Arts et loisirs
			8 = Littérature
			9 = Histoire et géographie

Cela correspond à la partie "par thème" de la recherche avancée. Exemple : http://gallica.bnf.fr/SRU?version=1.2&operation=searchRetrieve&query=dewey%20all%201

  • provenance : il s'agit d'un champ texte libre permettant la recherche dans l'index des provenances. Les valeurs possibles sont repérées dans les balises id_provenance des notices des documents.

Ainsi la provenance "bnf.fr" est le code pour les documents numérisés par la BnF et appartenant à la BnF.

  • access : il s'agit d'un champ texte libre permettant la recherche dans l'index des droits. Les valeurs possibles sont :

    • fayes : document libre de droits
    • fano : document sous conditions de ré-utilisation

  • indexationdate : il s'agit d'un champ texte permettant la recherche dans l'index des dates de première indexation du document numérique. Le format de date possible est YYYYMMJJ

exemple sur une date : tout les documents indexés le 20/10/2014 http://gallica.bnf.fr/SRU?version=1.2&operation=searchRetrieve&query=indexationdate%20any%2020141020

ou un intervalle de dates entre le 20/10/2014 et le 20/10/2015 http://gallica.bnf.fr/SRU?version=1.2&operation=searchRetrieve&query=indexationdate%20%3E%2020141020%20and%20indexationdate%20%3C%2020151020

  • dc.relation : il s'agit d'un champ texte libre permettant la recherche par mots dans l'index relation et qui correspond à l'indexation de la balise dc:relation des notices

Ce champ d'index est tokenizé ce qui signifie que chaque mot contenu dans la balise peut répondre.

Exemple : les relations des documents numériques avec une notice du catalogue général http://gallica.bnf.fr/SRU?operation=searchRetrieve&version=1.2&maximumRecods=10&startRecord=1&query=dc.relation%20any%20%22catalogue.bnf.fr%22

  • dc.rights : il s'agit d'un champ texte libre permettant la recherche par mots dans l'index des droits. Il s'agit du contenu des balises dc:rights des notices

  • dc.source : il s'agit d'un champ texte libre permettant la recherche par mots dans l'index des sources. Il s'agit du contenu des balises dc:source des notices

  • dc.subject : il s'agit d'un champ texte libre permettant la recherche par mots dans l'index des sujets. Il s'agit du contenu des balises dc:subject des notices

  • dc.format : il s'agit d'un champ texte libre permettant la recherche par mots dans l'index des format. Il s'agit du contenu des balises dc:format des notices

  • dc.language : il s'agit d'un champ texte libre permettant la recherche par mots dans l'index des langues dans laquelle le document original a été édité. Cela correspond à l'indexation de la balise dc:language des notices. La normalisation BnF est la suivante avec un code langue sur 3 caractères :

      	ale = Aléoute
  	alg = langues algonquiennes
  	ang = anglo-saxon
  	ara = Arabe
  	arm = Arménien
  	aze = Azéri
  	ber = Berbère
  	bre = breton
  	bul = Bulgare
  	cat = Catalan
  	cau = Caucasiennes, autres langues
  	che = Tchétchène
  	chi = Chinois
  	cop = copte
  	cos = Corse
  	cpf = Créoles et pidgins français, autres
  	cze = Tchèque
  	dan = danois
  	dut = Néerlandais
  	eng = Anglais
  	enm = anglais moyen
  	epo = Espéranto
  	est = Estonien
  	eth = Ethiopien
  	fin = Finnois
  	frd = Français, Dialectes
  	fre = Français
  	frm = Français moyen
  	fro = Français ancien
  	gaa = Ga
  	ged = Gade
  	gem = Langues germaniques
  	geo = Géorgien
  	ger = Allemand
  	gez = guèze
  	gle = Irlandais
  	glg = Galicien
  	gmh = moyen haut allemand
  	goh = vieux haut allemand
  	got = gothique
  	grc = Grec
  	gre = grec moderne (1453-)
  	haw = hawaïen
  	heb = Hébreu
  	hun = Hongrois
  	ita = Italien
  	itd = italien ancien
  	jpn = Japonais
  	kab = Kabyle
  	lan = Languedocien
  	lat = Latin
  	lav = Letton
  	lit = Lituanien
  	mlg = Malgache
  	mul = Multilingue
  	nor = Norvégien
  	oci = occitan (après 1500)
  	oss = Ossète
  	ota = Turc ottoman (1500-1928)
  	per = Persan
  	pol = Polonais
  	por = Portugais
  	pro = Provençal ancien
  	pus = Pachto
  	roa = Langue Romane
  	rom = Roumain
  	rum = Roumain
  	rus = Russe
  	scc = Serbe
  	scr = Croate
  	slo = Slovaque
  	spa = Espagnol
  	swe = Suédois
  	tat = Tatar
  	ukr = Ukrainien
  	und = indéterminée
  	uzb = Ouszbek
  	vie = vietnamien
  	wel = Gallois
  	yid = Yiddish
  	yor = Yoruba

Exemple : http://gallica.bnf.fr/SRU?operation=searchRetrieve&version=1.2&maximumRecods=10&startRecord=1&query=dc.language%20any%20yor

Ceci est vrai pour les documents de provenance bnf.fr, mais chez nos partenaires, l'attribut langue n'est pas toujours conforme à cette normalisation

  • dc.identifier : il s'agit d'un champ texte libre permettant la recherche dans l'index des identifiants liés à un documents numérique. Cela correspond à l'indexation de la balise dc:identifier

  • dc.description : il s'agit d'un champ texte libre permettant la recherche par mots dans l'index des descriptions associées à un document numérique. Il s'agit d'un contenu de la balise dc:description

###Liste des opérateurs possibles pour interroger un champ d'index

  • all : correspond à tous les mots. Il faut mettre des guillemets autour du/des terme(s) recherché(s) si plus d’un.
  • any : L’un des mots au moins. Il faut mettre des guillemets autour du/des terme(s) recherché(s) si plus d’un.
  • adj : Il s'agit de l'expression exacte/ égal.Il faut mettre des guillemets autour autour du/des terme(s) recherché(s). Attention l'utilisation de ce critère entraîne automatiquement la recherche sans expansion (contrairement aux autres opérateurs qui laissent le moteur effectuer certains élargissements pour les mots de la requête). S'il est présent une fois dans une des requêtes unitaire, les expansions sont désactivées pour tous les champs de la requête.

Sur les index dates (dc.date, indexationdate), on peut aussi utiliser les éléments classiques suivant : < , <= , > , >=

Les mots clés de recherche sur les champs d'index et les opérateurs ci-dessus permettent de générer des éléments de requête unitaire. Par exemple : dc.language any "yor"

On peut ensuite utiliser l'algèbre de Boole avec les éléments suivants pour combiner le tout.

  • and signifie ET
  • or signifie OU
  • not signifie SAUF

À noter que le parenthésage est également pris en compte pour isoler des sous-requêtes dans la requête principale.

###Les critères de tri

À la fin du paramètre query, une fois que la requête est construite, on peut ajouter, toujours en CQL, un critère de tri.

Voici les possibilités :

  • dc.creator/sort.ascending : tri par ordre croissant des auteurs
  • dc.title/sort.ascending : tri par ordre croissant des titres
  • dc.date/sort.ascending : tri par ordre croissant des dates d'édition
  • dc.date/sort.descending : tri par ordre décroissant des dates d'édition
  • ocr.quality/sort.descending : tri par ordre décroissant de la qualité de l'ocr
  • indexationdate/sort.descending : tri par ordre décroissant des dates de mise en ligne

##Exemples

##TIPS Si vous souhaitez écrire des requêtes SRU non programmatiquement, nous vous conseillons de passer par Gallica, vous effectuez une recherche exemple : http://gallica.bnf.fr/services/engine/search/sru?operation=searchRetrieve&exactSearch=false&collapsing=true&version=1.2&query=(dc.creator all "molière" or dc.contributor all "molière" ) and (dc.type all "monographie") and (provenance adj "bnf.fr")&suggest=10 dans ce cas on récupère le contenu du paramètre query, ici : (dc.creator all "molière" or dc.contributor all "molière" ) and (dc.type all "monographie") and (provenance adj "bnf.fr") et on l'utilise pour le paramètre query du service SRU comme suis : http://gallica.bnf.fr/SRU?version=1.2&operation=searchRetrieve&query=(dc.creator all "molière" or dc.contributor all "molière" ) and (dc.type all "monographie") and (provenance adj "bnf.fr")

Difficulté

Parsing classique d'un flux xml. La difficulté tiens à l'écriture de la requête en CQL et à la connaissance du format dublin core pour savoir quel index interroger en fonction de ce que l'on souhaite rechercher.

Clone this wiki locally