CasuHAL AtelierAPI : Différence entre versions

De HAL
Sauter à la navigation Sauter à la recherche
 
(40 révisions intermédiaires par 3 utilisateurs non affichées)
Ligne 1 : Ligne 1 :
−
== Notes libres pour l'atelier API des journées CasuHAL 2018 ==
+
== Atelier API des journées CasuHAL 2019 ==
  
−
== 13h30/13h45 : Introduction ==
+
=== Support de la présentation ===  
−
-> Explication de ce qu'est une API
+
[[:File:CasuhalAtelierAPI2019.pdf]]
−
-> Ce que ça permet
+
=== Mémos ===
−
-> 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 ==
+
Formats de réponse [[:File:afficheformatréponses.pdf]]
−
-> Requête -> traitement du fichier retourné
 
−
-> Affichage "simple" dans un tableur
 
−
-> Utilisation de logiciels de traitement de données (pour enrichissement ou traitement ou nettoyage)
 
−
-> Affichage dans un site web
 
−
-> 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
+
Paramètres groupes [[:File:affichegroupes.pdf]]
  
−
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 ?).
+
Métadonnées [[:File:affichemetadonnees.pdf]]
  
 +
Opérateurs de recherche [[:File:afficheopérateurs.pdf]]
  
 +
Récapitulatif des paramètres [[:File:afficheparamètres.pdf]]
  
−
=== Le cas d'une autre possibilité -> enrichir un fichier de données avec des données de l'API :===
+
Paramètres des facettes [[:File:afficheparamètresfacettes.pdf]]
  
−
Avec Open Refine = ouvrir un fichier / importer des données en moissonnant l'API
+
Types de champs [[:File:affichetypeschamps.pdf]]
  
−
== 14h / 14h15 : Démonstration d'interrogation de l'API ==
+
== Atelier API des journées CasuHAL 2018 ==
−
-> principes de construction d'une requêtes
 
−
Déconstruction de requêtes
 
  
−
URL d'entrée
+
'''A l'occasion des journées CasuHAL 2018 et de l'atelier sur l'utilisation des API de HAL, nous avons proposé de commencer par lister des actions à mener pour favoriser l'utilisation des API par le réseau CasuHAL.'''
 +
Ci-dessous la trame de l'atelier
  
−
+
+
=== Explication de ce qu'est une API===
 +
Les APIs (Application Programming Interface ou interface de programmation) sont des interfaces qui permettent une communication machine à machine. Cela permet à une source de donnée de s'exposer pour un ré-emploi par un autre système informatique.
  
−
critère : ?q=valeur OU ?q=champ:valeur / Séparateur &
+
-> Ce que ça permet
  
−
+
+
-> Comment ça le permet
  
−
filtre : fq=champ:valeur / séparateur &
+
-> Présentation des API Recherche et Référentiels de HAL
  
−
+
+
-> Précisions sur l'API d'import Sword et l'entrepôt OAI
  
−
retour : fl=champ / séparateur ,
+
=== Supports de formation sur l'API HAL ===
 +
https://fr.slideshare.net/OAccsd/les-api-de-hal
 +
https://fr.slideshare.net/OAccsd/usage-des-api-de-hal
 +
https://www.slideshare.net/OAccsd/les-api-de-recherche-de-hal
 +
https://fr.slideshare.net/OAccsd/les-api-de-hal-formation-ccsd-mars-2016
 +
https://fr.slideshare.net/OAccsd/tei-hal-import-sword
  
−
les filtres sont sur des listes fermées :
+
=== Utiliser l'API d'archives-ouvertes ? démonstrations ===
  
 +
-> Requête -> Que faire du fichier retourné ?
  
−
=== Les types de champs ===
+
-> Affichage "simple" dans un tableur : démonstration d'un export csv et affichage simple dans libreoffice
−
https://api.archives-ouvertes.fr/docs/search/schema/field-types/#field-types
 
  
−
=== Comprendre les données interrogées ===
+
-> 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.
−
Exemple d'une notice auteur riche => https://api.archives-ouvertes.fr/ref/author/?q=docid:58415&wt=xml&fl=* / champs du référentiel authors => https://api.archives-ouvertes.fr/docs/ref/resource/author/schema/fields/#fields + aurehal + cv
 
  
−
Exemple notice structure => https://api.archives-ouvertes.fr/ref/structure/?q=docid:300297&wt=xml&fl=* / champs du référentiel structure => https://api.archives-ouvertes.fr/docs/ref/resource/structure/schema/fields/#fields
+
-> Affichage dans un site web : démonstration d'un affichage site web avec une requête dans l'API
−
===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
 
−
*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.
 
−
{{Boîte déroulante/fin}}
 
  
−
== 14h15 / 14h30 : Analyses de 4 requêtes précises ==
+
-> Autre ? (question à la salle ?)
  
−
Question : pourquoi l'export CSV n'est pas disponible en requête facet ?
+
=== Réaliser des requêtes d'interrogation de l'API ===
  
−
'''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)'''
+
-> Diaporama de présentation de la syntaxe des requêtes : [[:File:2018-06-01_CASUHAL_Utilisation des API.pdf]]
  
−
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...
+
-> Scan du contenu de la documentation [[Notes Hélène]]
  
−
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
+
=== Echange avec la salle et/ou démonstrations de requêtes ===
−
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
+
=== 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 ?
  
−
Noter : Ces exports réalisés d'une machine pour une machine nécessitent un post-traitement pour les reprendre "humainement"
+
=== Je n'ai pas d'idées : quelles requêtes peuvent être intéressantes pour moi ? ===
−
Démo OpenRefine?
 
  
−
=== Ensuite on propose 3 requêtes dont on pense que ce sont celles qui intéressent généralement les admin ===
+
'''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)'''
  
−
'''2 / les affiliations : afficher ttes les structures affiliées à un auteur (https://api.archives-ouvertes.fr/docs/ref/resource/authorstructure)'''
+
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
  
−
https://api.archives-ouvertes.fr/search/authorstructure/?firstName_t=prenom&lastName_t=nom&i&wt=xml
+
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
  
−
'''5 / Je n'ai pas d'idées : quelles requêtes font les usagers ??'''
+
Les auteurs ne sont pas affiliés (dans auréhal) comme on pourrait le penser, ce sont dans les notices documents que les affiliations sont appliquées  = Donc on cherche dans l'api de recherche de documents et on extrait les affiliations par ce biais là.  
−
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 / ?'''
+
Comment obtenir en plus dans cette liste les identifiants accrochés aux auteurs (orcid, idref and cie) = Re requêter 1 à 1 les auteur ?...
  
−
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
+
'''2 / les affiliations : afficher ttes les structures affiliées à un auteur (https://api.archives-ouvertes.fr/docs/ref/resource/authorstructure)'''
  
−
labstructid = polen (univ orleans)
+
https://api.archives-ouvertes.fr/search/authorstructure/?firstName_t=prenom&lastName_t=nom&i&wt=xml
  
−
date : * to now
 
  
−
NumFound = <result name="response" numFound="146" start="0">
+
'''3 / retrouver des doublons potentiels de publication pour une collection donnée pour une année de production donnée'''
  
−
'''2 / Liste des structures rattachées à une structure de + haut niveau.'''
+
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
−
 
 
−
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=*
+
'''4 / Liste des structures rattachées à une structure de + haut niveau.'''
  
−
Attention la conf par défaut limite à 30 = il faut ajouter rows.
+
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=*
  
−
==> Dire aux participants de poster leurs demandes de requêtes au support / revoir les pages requêtes sur le wiki ensemble ?
+
On a 165 résultats (Attention la conf par défaut limite à 30)

Version actuelle datée du 25 juin 2019 à 16:25

Atelier API des journées CasuHAL 2019

Support de la présentation

File:CasuhalAtelierAPI2019.pdf

Mémos

Formats de réponse File:afficheformatréponses.pdf

Paramètres groupes File:affichegroupes.pdf

Métadonnées File:affichemetadonnees.pdf

Opérateurs de recherche File:afficheopérateurs.pdf

Récapitulatif des paramètres File:afficheparamètres.pdf

Paramètres des facettes File:afficheparamètresfacettes.pdf

Types de champs File:affichetypeschamps.pdf

Atelier API des journées CasuHAL 2018

A l'occasion des journées CasuHAL 2018 et de l'atelier sur l'utilisation des API de HAL, nous avons proposé de commencer par lister des actions à mener pour favoriser l'utilisation des API par le réseau CasuHAL. Ci-dessous la trame de l'atelier

Explication de ce qu'est une API

Les APIs (Application Programming Interface ou interface de programmation) sont des interfaces qui permettent une communication machine à machine. Cela permet à une source de donnée de s'exposer pour un ré-emploi par un autre système informatique.

-> 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

Supports de formation sur l'API HAL

https://fr.slideshare.net/OAccsd/les-api-de-hal
https://fr.slideshare.net/OAccsd/usage-des-api-de-hal
https://www.slideshare.net/OAccsd/les-api-de-recherche-de-hal
https://fr.slideshare.net/OAccsd/les-api-de-hal-formation-ccsd-mars-2016
https://fr.slideshare.net/OAccsd/tei-hal-import-sword

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 ?)

Réaliser des requêtes d'interrogation de l'API

-> Diaporama de présentation de la syntaxe des requêtes : File:2018-06-01_CASUHAL_Utilisation des API.pdf

-> Scan du contenu de la documentation Notes Hélène

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)

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

Les auteurs ne sont pas affiliés (dans auréhal) comme on pourrait le penser, ce sont dans les notices documents que les affiliations sont appliquées = Donc on cherche dans l'api de recherche de documents et on extrait les affiliations par ce biais là.

Comment obtenir en plus dans cette liste les identifiants accrochés aux auteurs (orcid, idref and cie) = Re requêter 1 à 1 les auteur ?...


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

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


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)

Récupérée de « https://wiki.ccsd.cnrs.fr/wikis/hal/index.php?title=CasuHAL_AtelierAPI&oldid=970 »