CasuHAL AtelierAPI : Différence entre versions

De HAL
Sauter à la navigation Sauter à la recherche
Ligne 17 : Ligne 17 :
 
-> Requête -> traitement du fichier retourné  
 
-> Requête -> traitement du fichier retourné  
  
-> Affichage "simple" dans un tableur  
+
-> Affichage "simple" dans un tableur : démonstration d'un export csv et affichage simple dans libreoffice
  
-> Utilisation de logiciels de traitement de données (pour enrichissement ou traitement ou nettoyage)
+
-> Utilisation de logiciels de traitement de données (pour enrichissement et/ou traitement et/ou nettoyage) : Démonstration avec OpenRefine d'un import de données récupérées, découpage du contenu d'une colonne etc.
  
-> Affichage dans un site web
+
-> Affichage dans un site web : démonstration d'un affichage site web avec une requête dans l'API
  
 
-> Autre ? (question à la salle ?)
 
-> Autre ? (question à la salle ?)
  
https://hal.archives-ouvertes.fr/search/index : cocher toutes les options (pour comparer on cherche dans tout, voir que le site web ne cherche pas dans tout par défaut) : entrer les 2 mots api hal = 940 résultats. le site par défaut fait api AND hal
+
== 14h / 14h15 : Réaliser des requêtes d'interrogation de l'API ==
 
 
https://api.archives-ouvertes.fr/search/?q=api AND hal = 946 résultats (pourquoi 6 de + ? je ne sais pas : pas exactement la même requête en fait ou bien fraîcheur de la base ?).
 
 
 
 
 
 
 
=== Le cas d'une autre possibilité -> enrichir un fichier de données avec des données de l'API :===
 
 
 
Avec Open Refine = ouvrir un fichier / importer des données en moissonnant l'API
 
 
 
== 14h / 14h15 : Démonstration d'interrogation de l'API ==
 
 
-> Les principes de construction d'une requêtes
 
-> Les principes de construction d'une requêtes
Déconstruction de requêtes
+
-> Quelles informations on trouve dans la documentation
 
+
-> L'utilisation des facettes
URL d'entrée
 
 
 
+
 
 
 
critère : ?q=valeur OU ?q=champ:valeur / Séparateur &
 
 
 
+
 
  
filtre : fq=champ:valeur / séparateur &
 
 
+
 
 
retour : fl=champ / séparateur ,
 
 
les filtres sont sur des listes fermées :
 
 
 
=== Les types de champs ===
 
https://api.archives-ouvertes.fr/docs/search/schema/field-types/#field-types
 
 
 
===LN===
 
{{boîte déroulante/début|titre=Informations contenues dans la documentation →|align=left}}
 
 
*Il faut au moins un paramètre dans l'URL pour faire une requête, ce paramètre est q
 
*Il faut au moins un paramètre dans l'URL pour faire une requête, ce paramètre est q
 
*Ce paramètre contient la requête à effectuer.
 
*Ce paramètre contient la requête à effectuer.
Ligne 107 : Ligne 75 :
 
//
 
//
 
*Vous pouvez obtenir vos résultats de requêtes groupés selon un critère de votre choix, à condition que le critère soit représenté par un champ non multivalué et de type string.
 
*Vous pouvez obtenir vos résultats de requêtes groupés selon un critère de votre choix, à condition que le critère soit représenté par un champ non multivalué et de type string.
{{Boîte déroulante/fin}}
 
  
== 14h15 / 14h30 : Analyses de 4 requêtes précises ==
+
 
 +
== 14h15 / 14h30 : Echange avec la salle ou démonstrations/analyses de requêtes ==
  
 
Question : pourquoi l'export CSV n'est pas disponible en requête facet ?
 
Question : pourquoi l'export CSV n'est pas disponible en requête facet ?
Ligne 157 : Ligne 125 :
 
Attention la conf par défaut limite à 30 = il faut ajouter rows.
 
Attention la conf par défaut limite à 30 = il faut ajouter rows.
  
==> Dire aux participants de poster leurs demandes de requêtes au support / revoir les pages requêtes sur le wiki ensemble ?
+
=== Développer un réseau d’entraide autour des API de HAL : on objectif pour CasuHal ? ===
 +
Pistes / propositions :
 +
*Utiliser la liste hal.tech pour les questions concernant l’interrogation de l’API
 +
*Reporter sur le wiki les « réponses »
 +
*Faire un travail de documentation des requêtes déjà présentes sur le wiki
 +
*Constituer un inventaire des requêtes fréquemment demandées
 +
*Autre ?

Version du 30 mai 2018 à 07:38

Notes libres pour l'atelier API des journées CasuHAL 2018

13h30/13h45 : Introduction

-> Explication de ce qu'est une API

-> Ce que ça permet

-> Comment ça le permet

-> Présentation des API Recherche et Référentiels de HAL

-> Précisions sur l'API d'import Sword et l'entrepôt OAI

13h45 / 14h : Utiliser l'API d'archives-ouvertes ? démonstrations

-> Requête -> traitement du fichier retourné

-> Affichage "simple" dans un tableur : démonstration d'un export csv et affichage simple dans libreoffice

-> Utilisation de logiciels de traitement de données (pour enrichissement et/ou traitement et/ou nettoyage) : Démonstration avec OpenRefine d'un import de données récupérées, découpage du contenu d'une colonne etc.

-> Affichage dans un site web : démonstration d'un affichage site web avec une requête dans l'API

-> Autre ? (question à la salle ?)

14h / 14h15 : Réaliser des requêtes d'interrogation de l'API

-> Les principes de construction d'une requêtes -> Quelles informations on trouve dans la documentation -> L'utilisation des facettes

  • Il faut au moins un paramètre dans l'URL pour faire une requête, ce paramètre est q
  • Ce paramètre contient la requête à effectuer.
  • Le paramètre doit être suivi du nom du champ dans lequel rechercher puis de la valeur à chercher.
  • Si le nom du champ dans lequel chercher est omis, par défaut la recherche porte sur l'index text qui contient les valeurs de plusieurs champs.
  • Pour chercher dans un champ particulier la syntaxe est champ:terme
  • Pour chercher plusieurs champs, utiliser (terme1 terme2). L'opérateur booléen par défaut est AND
  • Pour OR : Utiliser (terme1 OR terme2)
  • Pour une phrase : Utiliser les guillemets doubles "phrase"
  • Troncature ? * ~ proximité

//

  • Le format de réponse par défaut est JSON
  • Le format de réponse est spécifié par le paramètre wt : wt=json
  • liste des formats dans la doc. Ajouter indent=true pour indenter le format de réponse.

//

  • Par défaut seuls les champs docid et label_s sont retournés dans une réponse. Cependant tous les champs stockés peuvent être retournés dans le format de réponse
  • Le paramètre pour choisir les champs à retourner est fl. Les champs demandés doivent être séparés par le signe ,
  • Formats de sortie avec fl = JSON, XML et CSV uniquement
  • On peut utiliser le caractère * comme troncature de nom de champ, eg fl=cha*

*fl=* signifie tous les champs possibles //

  • Par défaut, les résultats sont triés par pertinence.
  • Le tri des résultats peut se faire sur n'importe quel champ en évitant les champs de type text (suffixe "_t") et les champs multi-valués qui donneront des résultats imprévisibles.
  • Le paramètre pour choisir les champs à retourner est sort + le sens de tri asc ou desc

//

  • Le paramètre pour ajouter des filtres est fq suivi de la requête servant au filtre : fq=submitType_s:file
  • Il est possible de faire des requêtes sur des intervalles avec cette syntaxe champ:[valeurDébut TO valeurFin]
  • valeur maximale = * + doc pour les spécificités des calculs de dates

//

  • Le nombre de réponses à retourner est définit par le paramètre rows .
  • Le nombre total de dépôt/notices ne change pas avec ce paramètres, seul le nombre de résultats effectivement retournés varie.
  • Par défaut les requêtes ne retournent que les 30 premiers résultats, le maximum autorisé est 10000. Si vous souhaitez plus de résultats vous devez utiliser la pagination.
  • Le paramètre &rows=0 peut permettre de ne retourner que le nombre de résultats et d'enlever les documents du corps de la réponse. Vous pouvez par exemple utiliser ce paramètre à des fins de statistiques ou si vous voulez retourner uniquement des facettes.

//

  • pagination : afficher 50 après les 50 1ers : start=50&rows=50
  • Curseurs : si vous devez parcourir plusieurs milliers de résultats, pour des raisons de performance il est fortement recommandé d'utiliser les curseurs

//

  • Les facettes sont des listes de termes extraits en fonction d'une requête.
  • On peut les utiliser pour avoir une liste de valeurs distinctes sur un champ donné.
  • Pour générer des facettes, il faut ajouter le paramètre facet=true à une requête.
  • Il faut ensuite ajouter les champs avec lesquel construire les facettes avec le paramètre facet.field=NomDuChamp à une requête.
  • facet.sort=index, count, prefix, contains (facet.contains.ignoreCase=true)
  • Pivots
  • plage de résultats

//

  • Vous pouvez obtenir vos résultats de requêtes groupés selon un critère de votre choix, à condition que le critère soit représenté par un champ non multivalué et de type string.


14h15 / 14h30 : Echange avec la salle ou démonstrations/analyses de requêtes

Question : pourquoi l'export CSV n'est pas disponible en requête facet ?

1 / La question d'une liste d'auteur affiliés à un établissement (CF question précise posée sur la liste dans le cadre de la prépa de l'atelier)

Ils ont réalisé 2 essais. Explication ? = les auteurs ne sont pas affiliés (dans auréhal) comme on pourrait le penser = Donc on cherche en fait dans l'api de recherche de documents et on extrait les affiliations par ce biais là. Ils souhaitent avoir les identifiants (orcid, idref and cie) = impossible en réalité puisque ça c'est stocké dans auréhal author donc il faudrait re requêter 1 à 1...

Essai 1 -> https://api.archives-ouvertes.fr/ref/author/?q=structureId_i:81173&fl=docid,label_s,idHal_i,idHal_s,*_id&rows=10000&wt=xml Référentiel auteur

Essai 2 -> https://api.archives-ouvertes.fr/search/uvsq/?q=*:*&facet=true&facet.field=structHasAuthIdHal_fs&facet.mincount=0&facet.prefix=81173_&rows=0&wt=xml&facet.limit=10000

Noter : Ces exports réalisés d'une machine pour une machine nécessitent un post-traitement pour les reprendre "humainement" Démo OpenRefine?

Ensuite on propose 3 requêtes dont on pense que ce sont celles qui intéressent généralement les admin

2 / les affiliations : afficher ttes les structures affiliées à un auteur (https://api.archives-ouvertes.fr/docs/ref/resource/authorstructure)

https://api.archives-ouvertes.fr/search/authorstructure/?firstName_t=prenom&lastName_t=nom&i&wt=xml

5 / Je n'ai pas d'idées : quelles requêtes font les usagers ?? requête API pour retrouver des doublons potentiels de publication pour une collection donnée pour une année de production donnée http://api.archives-ouvertes.fr/search/?q=collCode_s:%22INRIA%22%20AND%20producedDateY_i:2015&rows=0&wt=xml&indent=true&facet=true&facet.pivot=title_s,docType_s,halId_s&facet.limit=10&facet.mincount=2

1 / ?

https://api.archives-ouvertes.fr/search/?fq=labStructId_i:186732&fq=submittedDate_tdate:[* TO NOW]&fq=docType_s:ART&fl=halId_s&fl=docid&fl=contributorFullName_s&fl=title_s&fl=language_s&fl=docType_s&fl=submittedDate_s&fl=producedDateY_i&fl=journalTitle_s&fl=issue_s&fl=volume_s&fl=page_s&fl=doiId_s&fl=audience_s&fl=comment_s&fl=authLastNameFirstName_s&fl=rteamStructAcronym_s&fl=authId_i&fl=abstract_s&rows=200&wt=xml

requête de recherche : ?fq puis &fl puis rows et enfin wt

labstructid = polen (univ orleans)

date : * to now

NumFound = <result name="response" numFound="146" start="0">

2 / Liste des structures rattachées à une structure de + haut niveau.

https://api.archives-ouvertes.fr/ref/structure/?wt=xml&q=parentDocid_i:300297&fl=*

On a 165 résultats

on veut exporter en csv = https://api.archives-ouvertes.fr/ref/structure/?wt=csv&q=parentDocid_i:300297&fl=*

Attention la conf par défaut limite à 30 = il faut ajouter rows.

Développer un réseau d’entraide autour des API de HAL : on objectif pour CasuHal ?

Pistes / propositions :

  • Utiliser la liste hal.tech pour les questions concernant l’interrogation de l’API
  • Reporter sur le wiki les « réponses »
  • Faire un travail de documentation des requêtes déjà présentes sur le wiki
  • Constituer un inventaire des requêtes fréquemment demandées
  • Autre ?