CasuHAL AtelierAPI

De HAL
Sauter à la navigation Sauter à la recherche

Support libre pour l'atelier API des journées CasuHAL 2018

Hélène Jouguet

Eléments de langage

  • C’est un accès aux données.
  • C’est une source de donnée qui est exposée de manière à être re-exploitée par des tiers.
  • C’est prendre la main sur les données afin de les organiser et les agencer autrement que sur l’interface standard.
  • C’est enrichir son site avec des données
  • API ou Webservices qui permettent d'extraire ou d'afficher une information du catalogue à partir d'une URL contenant des critères de recherche. (exemple Le Sudoc met diverses API à la disposition des systèmes locaux pour intégrer à la volée aux fonctions locales des données du système central.)
  • Les portails HAL sont une façon d'accéder au réservoir de données qu’est HAL
  • l'API donne accès à la base de données : c'est donc logiquement l'accès le plus complet possible (contrairement au site web qui ne permet à l'usager de ne faire que ce qui a été prévu)
  • Pour utiliser une API il faut connaître la structure des données, c’est pour ça qu’elles sont toujours accompagnées d’une documentation
  • Les formats de données = Json (Utile d'installer Json view dans son navigateur)
  • Sparql Endpoint : https://api.archives-ouvertes.fr/sparql
  • Des API partout : Isidore, Istex, Sudoc Abes.

Utiliser l'API ?

  • Cadrage : De mon point de vue mon point de vue c'est si les autres moyens d'accès ne "suffisent" pas au besoin exprimé (pour les stats = ne pas oublier le module stats dans l'admin
  • Donc : notion de "besoin à exprimer"

Déconstruction de requêtes

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 :

Un peu de compulsion de la doc

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

//

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

Les types de champs

https://api.archives-ouvertes.fr/docs/search/schema/field-types/#field-types

recherche de publis

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