CasuHAL AtelierAPI : Différence entre versions
| Ligne 32 : | Ligne 32 : | ||
-> L'utilisation des facettes | -> L'utilisation des facettes | ||
| + | {{boîte déroulante/début|titre=Notes sur la doc Hélène}} | ||
| + | Contenu | ||
| + | {{boîte déroulante/fin}} | ||
== 14h15 / 14h30 : Echange avec la salle et/ou démonstrations de requêtes == | == 14h15 / 14h30 : Echange avec la salle et/ou démonstrations de requêtes == | ||
Version du 30 mai 2018 à 08:07
Sommaire
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 -> Que faire 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.
Contenu Modèle:Boîte déroulante/fin
14h15 / 14h30 : Echange avec la salle et/ou démonstrations de requêtes
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 »
- Compléter la documentation des requêtes déjà présentes sur le wiki
- Constituer un inventaire des requêtes fréquemment demandées
- Autre ?
Je n'ai pas d'idées : quelles requêtes peuvent être intéressantes pour moi ?
1 / La question d'une liste d'auteurs 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
Noter : Ces exports réalisés d'une machine pour une machine nécessitent un post-traitement pour les reprendre "humainement" Démo OpenRefine?
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
3 / retrouver des doublons potentiels de publication pour une collection donnée pour une année de production donnée
4 / Liste des structures rattachées à une structure de + haut niveau.
https://api.archives-ouvertes.fr/ref/structure/?wt=xml&q=parentDocid_i:300297&fl=* ou https://api.archives-ouvertes.fr/ref/structure/?wt=csv&q=parentDocid_i:300297&fl=*
On a 165 résultats (Attention la conf par défaut limite à 30)
