Recommended
Recommended
More Related Content
What's hot
What's hot (20)
Similar to Usage des API de HAL
Similar to Usage des API de HAL (20)
More from OAccsd
More from OAccsd (20)
Usage des API de HAL
- 1. JDEV 2017 – Atelier T5.A02 Usage des API de HAL Yannick Barborini - CCSD
- 2. Créé en 2000 Mission fournir à la communauté de l’ESR des outils pour l’archivage, la diffusion et la valorisation des publications et des données scientifiques. Basé à Villeurbanne 16 personnes Partenaire de projets européens : MedOANet, DARIAH-EU, PEER Equipex DILOH, ANR Campus AAR https://www.ccsd.cnrs.fr/ https://hal.archives-ouvertes.fr L'archive ouverte pluridisciplinaire HAL, est destinée au dépôt et à la diffusion d'articles scientifiques de niveau recherche, publiés ou non, et de thèses. https://www.sciencesconf.org Plateforme Web ouverte aux organisateurs de colloques, workshops ou réunions scientifiques https://episciences.org Plateforme de revues électroniques en libre accès, alimentées par les articles déposés dans les archives ouvertes
- 3. Plan • Introduction • Accès aux référentiels • Les référentiels pour le dépôt SWORD • Les référentiels AURéHAL • L’API de recherche d’affiliations • Accès aux documents de l’archive HAL • Les points d’entrées • Les paramètres • Les facettes • Mise en pratique • Dépôt SWORD
- 4. Introduction
- 5. Les types d’API disponibles Référentiels Accès aux référentiels AuréHAL Documents Accès aux ressources de HAL Import Dépôt via protocole SWORD Moissonnage Accès aux ressources de HAL via protocole OAI-PMH Triplestore (09/17) Accès aux données RDF https://api.archives-ouvertes.fr
- 6. Les types d’API disponibles Référentiels Accès aux référentiels AuréHAL Documents Accès aux ressources de HAL Import Dépôt via protocole SWORD Moissonnage Accès aux ressources de HAL via protocole OAI-PMH Triplestore (09/17) Accès aux données RDF https://api.archives-ouvertes.fr
- 7. Les types d’API disponibles Référentiels Accès aux référentiels AuréHAL Documents Accès aux ressources de HAL Import Dépôt via protocole SWORD Moissonnage Accès aux ressources de HAL via protocole OAI-PMH Triplestore (09/17) Accès aux données RDF https://api.archives-ouvertes.fr
- 8. Pré-requis technique • Pas d’authentification • Client HTTP • Navigateur web • cURL • Bibliothèque logicielle • …
- 9. Syntaxe d’une Requête API web URL dans le navigateur Point d’accès https://api.archives-ouvertes.fr/search/hal Séparateur paramètres ? paramètre = valeur q=* paramètres séparés par & Exemples : https://api.archives-ouvertes.fr/search/hal?q=* https://api.archives-ouvertes.fr/search/hal?q=*&rows=5 https://api.archives-ouvertes.fr/search/hal?q=*&rows=5&wt=xml https://api.archives-ouvertes.fr/search/hal?q=*&start=20&rows=5&wt=xml
- 12. Recherche • Tous les modèles de données sont accessibles via l’API • https://api.archives-ouvertes.fr/ref/referentiel • Format de réponse SOLR (type) • <reponse> • <result …> • Les formats de sortie json ou xml
- 13. Liste des référentiels Référentiel Description URL anrproject Projets ANR /ref/anrproject author Auteurs /ref/author authorstructure Affiliation des auteurs /ref/authorstructure doctype * Types de documents /ref/doctype domain Disciplines scientifiques /ref/domain europeanproject Projets européens /ref/europeanproject instance * Portail HAL /ref/instance journal Revues /ref/journal metadata * Métadonnées /ref/metadata metadatalist * Métadonnées – listes fermées /ref/metadatalist structure Structures de recherche /ref/structure * Référentiels utilisés principalement pour le dépôt
- 14. Les référentiels pour le dépôt SWORD
- 15. Le dépôt SWORD • API REST https://api.archives-ouvertes.fr/docs/sword • Dépôt d’un fichier au format XML-TEI • Dans un portail HAL : portail HAL générique ou portail institutionnel HAL INRIA, HAL Univ Lorraine, … • Un type de dépôt : Article, Communication, Image, Vidéo, … • Une liste de métadonnées requises • Des valeurs prédéfinies pour certaines métadonnées
- 17. Les types de documents • Liste des types de documents acceptés sur HAL • Dépend du portail hal • Documentation https://api.archives-ouvertes.fr/docs/ref/resource/doctype • Exemple • Types de document acceptés sur TEL ( instance_s=tel ) : https://api.archives-ouvertes.fr/ref/doctype?instance_s=tel
- 18. Liste des métadonnées • Permet d’obtenir la liste des métadonnées requises pour un type de document et dans un portail • Exemples : • Liste des métadonnées pour le dépôt d’un article dans le portail de l’université de Lorraine : https://api.archives-ouvertes.fr/ref/metadata/?instance_s=univ- lorraine&docType_s=ART&wt=xml • Liste des métadonnées pour le dépôt d’un mémoire dans le portail de Inria : https://api.archives- ouvertes.fr/ref/metadata/?instance_s=inria&docType_s=MEM&wt=json
- 19. Listes fermées • Permet d’avoir les valeurs possibles pour les listes fermées • Exemple : • Niveau du cours : https://api.archives-ouvertes.fr/ref/metadatalist?q=metaName_s:lectureType
- 21. Les référentiels AURéHAL • Accès aux référentiels utilisés dans l’archive ouverte HAL : https://aurehal.archives-ouvertes.fr • Gestion des référentiels Auteurs, Structures, Domaines scientifiques, revues, projets ANR et projets européens
- 22. Auteurs • Accès aux formes auteurs associées aux publications présentes dans HAL • Une forme auteur est définie par • Nom, Prénom, autre prénom, adresse mail • Aligné avec des référentiels externes (IDHAL, ORCID, IdRef, …) • Documentation : https://api.archives-ouvertes.fr/docs/ref/resource/author • Liste des champs : https://api.archives- ouvertes.fr/docs/ref/resource/author/schema/fields/#fields
- 23. Auteurs - exemple • https://api.archives-ouvertes.fr/ref/author?q=docid:49567&fl=*
- 26. Structure - Exemple • Structure ADAC ADAC LIRMM CNRS UMONTPELLIER
- 27. Structures - Exemple • Exemple avec la structure ADAC https://aurehal.archives-ouvertes.fr/structure/read/id/487991
- 29. Structures – liste des champs • https://api.archives-ouvertes.fr/docs/ref/resource/structure/schema/fields/#fields
- 30. Disciplines scientifiques • Origine disciplines arXiv + département SHS du CNRS • Documentation https://api.archives-ouvertes.fr/docs/ref/resource/domain • Exemple https://api.archives-ouvertes.fr/ref/domain?q=code_s:phys&fl=*
- 32. Projets ANR • Récupération à partir de l’ANR • Documentation api.archives-ouvertes.fr/docs/ref/resource/anrproject • Exemple api.archives-ouvertes.fr/ref/anrproject?q=*&fl=*
- 33. Projets européens • Moissonnage d’OpenAIRE • Documentation https://api.archives-ouvertes.fr/docs/ref/resource/europeanproject • Exemple https://api.archives-ouvertes.fr/ref/europeanproject?q=*&fl=*
- 34. L’API de recherche d’affiliations
- 35. Recherche d’affiliations d’un auteur • Algorithme permettant de retrouver une affiliation d’un auteur • Prend en compte le nom, prénom, adresse mail et la date de publication • Basé sur les affiliations existantes dans HAL • Documentation https://api.archives-ouvertes.fr/docs/ref/resource/authorstructure • Exemple https://api.archives- ouvertes.fr/search/authorstructure/?firstName_t=laurent&las tName_t=capelli&wt=xml • Evolution de l’algorithme en prenant en compte le laboratoire (string)
- 37. Contenu API des documents • Tous les dépôts de HAL en ligne • +/- toutes les métadonnées d’un dépôt sous différentes formes • + version des métadonnées aux formats : • Bibtex • XML-TEI • COinS (ContextObjects in Spans) • Endnote • Texte intégral indexé mais pas stocké
- 39. Entrée par un portail • Point d’entrée pour un portail : https://api.archives-ouvertes.fr/search/<instance> • Exemple : https://api.archives-ouvertes.fr/search/univ-lorraine/ • NB : Dans le cas d’un portail/instance, si un dépôt a plusieurs versions, on ne trouve que la dernière.
- 40. Entrée par une collection • Point d’entrée pour une collection: https://api.archives-ouvertes.fr/search/<COLLECTION> • Exemple : https://api.archives-ouvertes.fr/search/LORIA • NB : Dans le cas d’une collection, si un dépôt a plusieurs versions, on ne trouve que la version tamponnée.
- 41. Paramètres utiles Nom paramètre/usage Description exemple Valeur par défaut q Requête de recherche q=exemple * :* Chercher dans un champ NomDuChamp:valeur q=title_t:test q=title_t:(printemps OR spring) text wt Format de réponse wt=xml Json Equation de recherche Termes + opérateurs booléens avec des parenthèses Journal AND (Histoire OR History) Intervalles Recherche d'intervalles submittedDateY_i:[2000 TO *] Opérateur booléens AND OR NOT + - && || AND fq Filtres fq=submitType_s:file rows Nombre de résultats rows=5 30 start Décalage des résultats start=10 0 fl Champs à retourner fl=auth*,docid,label_s docid,label_s sort Tri : nom du champ + asc ou desc sort=submittedDateY_i desc score facet Construire des facettes facet=true false facet.field Un champ pour faire des facettes facet.field=docType_s facet.mincount Nombre minimum de valeurs pour retourner une facette facet.mincount=1 0 facet.sort Tri des facettes [count ou index] facet.sort=index count Valeurs et paramètres sensibles à la casse
- 42. Types de métadonnées accessibles Type Usage prévu Exemple Indexées Recherche title_t Stockées Affichage label_s Facettes Liste de valeurs submitType_s Tri Tri de valeurs multivaluées author_sort • Liste des champs https://api.archives-ouvertes.fr/docs/search/schema/fields/#fields
- 43. Paramètre : Format de réponse • wt=format • Valeurs : xml ou json • Exemple : https://api.archives-ouvertes.fr/search/?wt=xml
- 44. Paramètre : Critère de recherche • q=valeur • Exemple : https://api.archives-ouvertes.fr/search/?q=dimuons
- 45. Paramètre : Recherche dans un champ • q=champ:valeur • Exemple : https://api.archives-ouvertes.fr/search/?q=title_t:dimuons
- 46. Paramètre : Recherche sur plusieurs champs • q=champ1:valeur1 OPERATEUR champ2:valeur2 • Exemple : https://api.archives- ouvertes.fr/search/?q=title_t:dimuons AND authLastName_t:capelli
- 47. Paramètre : Filtrer avec un champ • fq=champ:valeur • Exemple : https://api.archives- ouvertes.fr/search/?q=title_t:dimuons&fq=submitType_s:file
- 48. Paramètre : Champs retournés • fl=champ1,champ2,… • Par défault : docid, uri_s, label_s • Exemple : https://api.archives- ouvertes.fr/search/?q=title_t:dimuons&fq=submitType_s:file&fl=halId_s,ti tle_s
- 49. Paramètre : Groupe • group=true&group.field=[champ]&group.limit=[limi t] • Permet de grouper les résultats en fonction d’un champ. Permet également de ne retourner qu’un certain nombre de résultats par groupe • Exemple : https://api.archives- ouvertes.fr/search/?q=title_t:dimuons&fq=submitType_s:file&group=true &group.field=docType_s&group.limit=1
- 50. Paramètre : Tri • sort=champ1 (ASC|DESC),champ2 (ASC|DESC),… • Exemple : https://api.archives- ouvertes.fr/search/?q=title_t:dimuons&fq=submitType_s:file&sort=submi ttedDate_tdate desc
- 51. Parametre : Pagination • start=[num 1er resultat]&rows=[nb résultats] • Convient pour paginer un résultat de recherche • cursorMark=Id • Permet de récupérer l’intégralité d’une collection / de HAL… • https://api.archives- ouvertes.fr/search/?q=*:*&wt=xml&rows=100&sor t=docid%20asc&cursorMark=*&start=0
- 52. Le système de facettes
- 54. Les facettes • Créer des regroupements facet=true&facet.field=champ1 • Exemple : https://api.archives- ouvertes.fr/search/?q=*:*&rows=0&facet=true&f acet.field=docType_s
- 55. Les pivots • Créer des regroupements à plusieurs dimensions • facet=true&facet.pivot=champ1, champ2 • Exemple : https://api.archives- ouvertes.fr/search/?q=*&rows=0&facet=true&fa cet.pivot=docType_s,submitType_s
- 56. Les ranges • Créer des regroupements (principalement utilisé pour les dates) • facet=true&facet.range=champ • Exemple : https://api.archives- ouvertes.fr/search/?q=*:*&rows=0&indent=true &facet=true&facet.range=submittedDateY_i&fac et.range.start=1990&facet.range.end=2010&fac et.range.gap=2
- 57. Ateliers
- 58. Requêtes
- 64. Référentiel Structures • Lister les laboratoires rattachés à Inria qui ont un identifiant RNSR. Retourner le nom du laboratoire ainsi que l’identifiant RNSR • https://api.archives- ouvertes.fr/ref/structure/?q=*&fq=parentDocid_i:3 00009&fq=type_s:laboratory&fq=rnsr_s:["" TO *]&fl=acronym_s,name_s,rnsr_s
- 68. Référentiel des revues • Lister les revues avec le statut « green » dans Sherpa/Romeo où l’éditeur est Elsevier et la revue est validée dans le référentiel
- 69. Référentiel des revues • Lister les revues avec le statut « green » dans Sherpa/Romeo où l’éditeur est Elsevier et la revue est validée dans le référentiel • https://api.archives- ouvertes.fr/ref/journal/?wt=json&q=publisher_t:(El sevier)&fq=valid_s:VALID&fq=sherpaColor_s:green &fl=*&sort=title_s asc
- 70. Documents HAL • Lister les articles de la collection LKB déposés en 2006 et qui ont un texte associé
- 72. Documents HAL • Obtenir la liste d'auteurs affiliés à la structure AgroParisTech avec le nombre de dépôts par auteur
- 73. Documents HAL • Obtenir la liste d'auteurs affiliés à la structure AgroParisTech avec le nombre de dépôts par auteur • https://api.archives- ouvertes.fr/search/?q=*%3A*&rows=0&&facet=tru e&facet.field=structHasAuthId_fs&facet.prefix=148 117_FacetSep_&facet.limit=3000 • Champ structHasAuthId_fs contient : Identifiant de structure + _FacetSep_ + Nom structure + _JoinSep_ + Identifiant Auteur + _FacetSep_ + Nom auteur
- 74. Documents HAL
- 82. Création d’une interface de recherche basée sur les API
- 83. Atelier • Construire une petite application Web d’interrogation de l’archive HAL basée sur les API • Récupération du projet • https://github.com/ybarborini/jdev-t5A02 • Récupérer la branche « master » • Lancer bower install pour récupérer les librairies Js utilisées dans le projet
- 84. Atelier • Construire une petite application Web d’interrogation de l’archive HAL basée sur les API • Récupération du projet • https://github.com/ybarborini/jdev-t5A02 • Récupérer la branche « master » • Lancer bower install pour récupérer les librairies Js utilisées dans le projet • Si pb avec bower : récupérer le répertoire libraries à l’adresse : https://hal.archives-ouvertes.fr/public/jdev/libraries.zip
- 85. Etape 1 • Récupération des métadonnées d’un document • Mise en page de ce document • Ex http://localhost/jdev-t5A02/?halid=hal- 00000001 récupèrera les métadonnées de l’article dans HAL et le mettra en page
- 86. Etape 2 • Créer une page avec un champ de recherche • Effectuer une recherche avec l’API et retourner les résultats de recherche / facette (type de dépôt, discipline primaire, auteur) • Effectuer la mise en page
- 87. Etape 3 • Créer une page d’accueil regroupant : • Liste des derniers dépôts • Nuage de mot-clés (utilisation wordcloud2.js) • Graphes représentant les facettes types de documents, répartition par pays et type de soumission (utilisation Google Charts)
- 89. Simple Web-service Offering Repository Deposit • Basé sur Atom Publishing Protocol (APP) • Utilisé par d’autres AO & logiciels • arXiv, Dspace, Eprints, … • API REST HTTP • Verbes HTTP : • GET : statut d’une ressource • POST : nouveau dépôt • PUT : modification des métadonnées / nouvelle version • DELETE : suppression d’une ressource http://swordapp.org/
- 90. Entêtes HTTP (1) • Content-Type : • text/xml pour le dépôt d’un fichier XML • application/zip pour le dépôt d’une archive ZIP contenant un fichier XML + les fichiers associés • Content-Disposition : • attachment; filename=tei.xml à utiliser pour indiquer le nom du fichier XML dans le ZIP • Packaging : • http://purl.org/net/sword-types/AOfr : format AOfr - TEI HAL • http://jats.nlm.nih.gov/publishing/tag-library/ : format JATS • Content-MD5 : • Signature MD5 : vérifie l’intégrité du contenu envoyé
- 91. Entêtes HTTP (2) • On-Behalf-Of : Dépôt pour le compte d’un utilisateur HAL • UID ou LOGIN du compte HAL • IDHAL ou ORCID (prochainement) • Export-To-Arxiv • true / false : indique si le dépôt doit être transféré sur ArXiv • Export-To-PMC • true / false : indique si le dépôt doit être transféré sur Pubmed Central • Hide-For-RePEc • true / false : permet de cacher le dépôt du réservoir accessible à RePEc dans l'archive HAL • Hide-In-OAI • true / false : permet de cacher le dépôt du réservoir OAI-PMH et du Sitemap • X-Allow-Completion : • idext : récupération des métadonnées à partir d'un identifiant externe DOI, arXivID, … • grobid : récupération des métadonnées à partir du PDF soumis via l'outil GROBID • affiliation : recherche des affiliations des auteurs en se basant sur le référentiel AURéHAL
- 92. Statut d’une ressource • GET api.archives-ouvertes.fr/sword/[identifiant] • Réponse • HTTP/1.1 200 OK • statut : accept | verify | update | delete curl –X GET -u login:pwd https://api.archives-ouvertes.fr/sword/hal- 00000001v2 <?xml version="1.0" encoding="utf-8"?> <document id="hal-00000001" version="2"> <status>accept</status> <comment></comment> </document>
- 93. Suppression d’une ressource • DELETE api.archives-ouvertes.fr/sword/[identifiant] • Réponse • Suppression OK : HTTP/1.1 204 No Content • Suppression NOK : Code Erreur curl –X DELETE -u login:pwd https://api.archives-ouvertes.fr/sword/hal- 01039627
- 94. Dépôt d’une ressource (1) • POST api.archives-ouvertes.fr/sword/[portail] • Liste des portails accessible via l’API : https://api.archives- ouvertes.fr/ref/instance • Format pivot basé sur la TEI • https://hal.archives-ouvertes.fr/documents/aofr.xsd • Dépôt d’un fichier XML (Content-Type:text/xml) àNotice ou Texte intégral non intégré au dépôt • Dépôt d’une archive ZIP (Content-Type:application/zip) à Texte intégral : fichier(s) intégré(s) au dépôt
- 95. Dépôt d’une ressource (2) • Réponse • Dépôt accepté (passage diret en ligne) : HTTP/1.1 202 Accepted • Dépôt créé (en modération dans HAL) : HTTP/1.1 201 Created • Problème lors du dépôt : Code Erreur curl -X POST -u login:pwd https://api.archives-ouvertes.fr/sword/hal -H "X- Packaging:http://purl.org/net/sword-types/AOfr" -H "Content-Type:text/xml" - -data-binary @tei.xml
- 96. Dépôt d’une ressource (3) <?xml version="1.0" encoding="utf-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:sword="http://purl.org/net/sword/terms/" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:hal="http://hal.archives-ouvertes.fr/"> <title>Accepted media deposit to HAL</title> <id>hal-01040864</id> <hal:password>9322one</hal:password> <hal:version>1</hal:version> <updated>2017-03-28T08:56:23+02:00</updated> <summary>A media deposit was stored in the HAL workspace</summary> <sword:treatment>stored in HAL workspace</sword:treatment> <sword:userAgent>HAL SWORD API Server</sword:userAgent> <source> <generator uri="https://api.archives-ouvertes.fr/sword" version="1.0">hal@ccsd.cnrs.fr</generator> </source> <link rel="alternate" href="https://hal.archives-ouvertes.fr/hal-01040864"/> </entry>
- 97. Modification des métadonnées • PUT api.archives-ouvertes.fr/sword/[identifiant] • Réponse • Modification OK : HTTP/1.1 200 OK • Modification NOK : Code Erreur curl -X PUT -u login:pwd https://api.archives-ouvertes.fr/sword/hal- 01040864 -H "X-Packaging:http://purl.org/net/sword-types/AOfr" -H "Content-Type:text/xml" --data-binary @new_tei.xml
- 98. Dépôt d’une nouvelle version • Idem modification des métadonnées + ajout du texte intégral • PUT api.archives-ouvertes.fr/sword/[identifiant] • Réponse • Dépôt OK : HTTP/1.1 201 Created • Dépôt NOK : Code Erreur curl -X PUT -u login:pwd https://api.archives-ouvertes.fr/sword/hal- 01040864 -H "X-Packaging:http://purl.org/net/sword-types/AOfr" -H "Content-Type:text/xml" --data-binary @new_tei.xml
- 99. Gestion des erreurs (1) • HTTP/1.1 4XX • 406 Not Acceptable • Packaging non reconnu • Content-type non reconnu • Erreur dans chargement du fichier XML • 412 Precondition Failed • Problème dans la vérification du MD5 • 403 Forbidden • Problème d’authentification • 405 Method Not Allowed • Utilisation d’un verbe HTTP non accepté • 413 Request Entity Too Large • Taille du fichier supérieur à la limite (200Mo) • 400 Bad Request • Erreur d’enregistrement
- 100. Gestion des erreurs (2) • Xpath : /sword:error/sword:verboseDescription <?xml version="1.0" encoding="utf-8"?> <sword:error xmlns:sword="http://purl.org/net/sword/error/" xmlns="http://www.w3.org/2005/Atom" href="http://purl.org/net/sword/error/ErrorBadRequest"> <title>ERROR</title> <updated>2017-03-28T10:13:50+02:00</updated> <author> <name>HAL SWORD API Server</name> </author> <source> <generator uri="https://api.archives-ouvertes.fr/sword" version="1.0">hal@ccsd.cnrs.fr</generator> </source> <summary>Some parameters sent with the request were not understood</summary> <sword:treatment>processing failed</sword:treatment> <sword:verboseDescription>{"meta":{"abstract":{"isEmpty":"Vous devez remplir ce champ"}}}</sword:verboseDescription> <link rel="alternate" href="https://api.archives-ouvertes.fr" type="text/html"/> </sword:error>
- 101. Liens utiles Exemples en ligne de requêtes sur l’API de recherche HAL : Base de connaissance de HAL : https://wiki.ccsd.cnrs.fr/wikis/hal/ Documentation API Recherche HAL : https://api.archives- ouvertes.fr/docs/search Extension Chromium/Chrome pour visualiser JSON : - JSONViewer-for-Chrome : https://github.com/teocci/JSONViewer-for-Chrome Extension Firefox pour visualiser JSON : - JSON-formatter https://addons.mozilla.org/fr/firefox/addon/json- formatter