# Utilisation des APIs de l'entrepôt Recherche Data Gouv

Camille Desiles, Virgile Jarrige, Damien Sans, Dimitri Szabo

► To cite this version:

Camille Desiles, Virgile Jarrige, Damien Sans, Dimitri Szabo. Utilisation des APIs de l'entrepôt Recherche Data Gouv. Printemps de la Donnée 2024, INRAE; Université Haute-Alsace; Université de Strasbourg; INSA; PNDB; AgroParisTech; Université de Lille; Sorbonne Université; Data Terra, 2024, Paris, France. **hal-04702536**

HAL Id: hal-04702536

https://hal.inrae.fr/hal-04702536v1

Submitted on 19 Sep 2024

HAL is a multi-disciplinary open access
archive for the deposit and dissemination of sci-
entific research documents, whether they are pub-
lished or not. The documents may come from
teaching and research institutions in France or
abroad, or from public or private research centers.

L'archive ouverte pluridisciplinaire HAL, est
destinée au dépôt et à la diffusion de documents
scientifiques de niveau recherche, publiés ou non,
émanant des établissements d'enseignement et de
recherche français ou étrangers, des laboratoires
publics ou privés.

<figure><img src="image_1.png" /></figure>

Distributed under a Creative Commons Attribution 4.0 International License
Bonjour et bienvenue !

Cette classe virtuelle démarrera
à xx h

Le support est téléchargeable ici :

<figure><img src="image_2.png" /></figure>

<figure><img src="image_3.png" /></figure>

<figure><img src="image_4.png" /></figure>

RÉPUBLIQUE
FRANÇAISE

Liberté
Egalité
Fraternité

recherche.data.gouv.fr

# Utilisation des APIs de l'entrepôt
Recherche Data Gouv

## Sessions 2024

<figure><img src="image_5.png" /></figure>

<figure><img src="image_6.png" /></figure>

LICENCE OUVERTE
OPEN LICENCE

<figure><img src="image_7.png" /></figure>

<figure><img src="image_8.png" /></figure>

@RechercheDataGv
<figure><img src="image_9.png" /></figure>

▲▲▲ Prérequis ▲▲▲

<figure><img src="image_10.png" /></figure>

* Avoir suivi la classe virtuelle
Découverte des APIs

* Avoir installé le Client API
INSOMNIA

<figure><img src="image_11.png" /></figure>

▲▲▲ Prérequis ▲▲▲

<figure><img src="image_12.png" /></figure>
## Liste des exercices corrigés

0. CONFIGURATION DU CLIENT

1. LES APPELS

2. RECHERCHER

3. COLLECTIONS

4. GESTION COLLECTIONS

5. JEU DE DONNÉES

6. GESTION JEU DE DONNÉES

7. DÉPÔT DE FICHIER(S)

8. TÉLÉCHARGEMENT DE FICHIER(S)

9. MÉTRIQUES
<figure><img src="image_13.png" /></figure>

# Déroulé de la séance

## I. INTRODUCTION

## II. LES CONCEPTS CLÉS DE L'APPLICATION DATAVERSE

## III. LES POSSIBILITÉS DES APIS DE RECHERCHE DATA GOUV

## IV. UTILISATION PRATIQUE
<figure><img src="image_14.png" /></figure>

## Ce que cette formation ne couvre pas

* Introduction aux APIs : voir formation « Découverte »

* Utilisation de l'entrepôt lui-même : voir formations « Déposer » et « Administrer »

* Les outils complémentaires (Widget, DV Uploader)

* Utilisation des APIs dans un langage de script (ex. R, Python)
# Dataverse, moteur de l'entrepôt et du catalogue

<figure><img src="image_15.png" /></figure>

116 Installations

<figure><img src="image_16.png" /></figure>

<figure><img src="image_17.png" /></figure>

<figure><img src="image_18.png" /></figure>
<figure><img src="image_19.png" /></figure>

<figure><img src="image_20.png" /></figure>

RÉPUBLIQUE
FRANÇAISE

Liberté
Égalité
Fraternité

recherche.data.gouv.fr

RAPPELS : LES CONCEPTS CLÉS DE L'ENTREPÔT

<figure><img src="image_21.png" /></figure>

<figure><img src="image_22.png" /></figure>

LICENCE OUVERTE
OPEN LICENCE

<figure><img src="image_23.png" /></figure>

<figure><img src="image_24.png" /></figure>

@RechercheDataGv
# Les éléments

<figure><img src="image_25.png" /></figure>

* **collection (dataverse) : de jeux de données et/ou de sous-collections ;**

* **jeu de données (dataset) : rassemble les fichiers et les métadonnées ;**

* **fichier (file) : Un fichier de données ou de documentation (ex. README).**
<figure><img src="image_26.png" /></figure>

RÉPUBLIQUE
FRANÇAISE

Liberté
Égalité
Fraternité

recherche.data.gouv.fr

<figure><img src="image_27.png" /></figure>

## Rappel : les métadonnées

**Identifiant pérenne** doi:10.57745/PM55G5

**Date de publication** 2023-01-26

**Titre** One-step synthesis of spin crossover nanoparticles using flow chemistry and supercritical CO2

**Point de contact** Utiliser le bouton de courriel ci-dessus pour joindre la personne-contact.
TOULIN, Stéphane (CNRS)

**Auteur** Daro, Nathalie (Univ. Bordeaux, CNRS, Bordeaux INP, ICMCB, UMR 5026, F-33600 Pessac, France) - ORCID: 0000-0002-3707-9686
Chastanet, Guillaume (Univ. Bordeaux, CNRS, Bordeaux INP, ICMCB, UMR 5026, F-33600 Pessac, France) - ORCID: 0000-0001-6829-4066
Marre, Samuel (Univ. Bordeaux, CNRS, Bordeaux INP, ICMCB, UMR 5026, F-33600 Pessac, France) - ORCID: 0000-0001-8889-187X
Aymonier, Cyril (Univ. Bordeaux, CNRS, Bordeaux INP, ICMCB, UMR 5026, F-33600 Pessac, France) - ORCID: 0000-0003-1775-0716
Vaudel, Tony (Univ. Bordeaux, CNRS, Bordeaux INP, ICMCB, UMR 5026, F-33600 Pessac, France)
Afindouli, Luc (Univ. Bordeaux, CNRS, Bordeaux INP, ICMCB, UMR 5026, F-33600 Pessac, France)

**Contributeur** Data Collector : TOULIN, Stéphane (Univ. Bordeaux, CNRS, Bordeaux INP, ICMCB, UMR 5026, F-33600 Pessac, France) - ORCID: 0000-0002-2087-7403

**Producteur** Centre National de la Recherche Scientifique (CNRS) https://www.cnrs.fr/cnrs

Université de Bordeaux (UBX) https://www.u-bordeaux.fr/université
d'**BORDEAUX**

Bordeaux INP https://www.bordeaux-inp.fr/BORDEAUX
INP

**Localisation de la production** Pessac

**Distributeur** Entrepôt-Catalogue Recherche Data Gouv

**Description** Data set and images from

- Publication : Daro N., Vaudel T., Afindouli L., Marre S., Aymonier C. and Chastanet G. One-step synthesis of spin crossover nanoparticles using flow chemistry and supercritical CO2. Chemistry - European Journal 2020 vol.26, n°69, p.16286-16290.
DOI: 10.1002/chem.202002322 / HAL : https://hal.science/hal-02945200

* Données décrivant les données

* Facilite la découverte

* Pour comprendre les données et les conditions de production

<figure><img src="image_28.png" /></figure>

<figure><img src="image_29.png" /></figure>
<figure><img src="image_30.png" /></figure>

RÉPUBLIQUE
FRANÇAISE

Liberté
Égalité
Fraternité

recherche.data.gouv.fr

# Blocs de métadonnées

* Métadonnées générales :

* 6 sont obligatoires : Titre, Auteur Nom, Point de contact Courriel, Description Texte, Sujet, Type de données

* liens avec d'autres objets (Lien vers les données, Autre identifiant, Publication associée, Jeu de données associé)

* etc.

* Métadonnées spécifiques :

* Métadonnées géospatiales

* Métadonnées de sciences humaines et sociales

* Métadonnées de science de la vie

* Métadonnées de revue

* Métadonnées de ressources sémantiques

* Métadonnées d'astronomie et astrophysique

* Métadonnées de workflow de calcul

Conformes aux standards
DDI, Dublin Core,
DataCite, ISA-TAB

<figure><img src="image_31.png" /></figure>

<figure><img src="image_32.png" /></figure>

@RechercheDataGv
<figure><img src="image_33.png" /></figure>

RÉPUBLIQUE
FRANÇAISE

Liberté
Égalité
Fraternité

recherche.data.gouv.fr

Comment tester ?

• Pour les tests et d'autant plus en écriture :

Utiliser le bac à sable !

• Pour tester la publication, utiliser si possible
toujours le même jeu de données

• Si possible, supprimer les tests au fur et à mesure

Attention !

Ne mets pas tes mains
dans la prod, tu risques
de te faire pincer très fort.

<figure><img src="image_34.png" /></figure>

<figure><img src="image_35.png" /></figure>
<figure><img src="image_36.png" /></figure>

<figure><img src="image_37.png" /></figure>

RÉPUBLIQUE
FRANÇAISE

Liberté
Egalité
Fraternité

recherche.data.gouv.fr

RAPPELS SUR LES APIS

<figure><img src="image_38.png" /></figure>

<figure><img src="image_39.png" /></figure>

LICENCE OUVERTE
OPEN LICENCE

<figure><img src="image_40.png" /></figure>

<figure><img src="image_41.png" /></figure>

@RechercheDataGv
<figure><img src="image_42.png" /></figure>

Un peu de vocabulaire

https://entrepot.recherche.data.gouv.fr/api/v1/search?q=*&fq=publicationStatus:Published

1. protocole

2. serveur

3. version

4. endpoint

5. paramètres

5. paramètres

5. paramètres

4. endpoint

1. Protocole : par quoi on échange

2. Serveur : avec qui/quoi on échange

3. Version : permet d'utiliser l'ancienne version d'une API si elle change

4. Endpoint : point d'entrée, quelle commande on effectue

5. Paramètres : avec quelles spécificités
Les méthodes

* Verbes HTTP correspondant à 4 opérations (CRUD)

<table><thead><tr><td>Opération</td><td>Traduction</td><td>Verbe</td></tr></thead><tbody><tr><td>Create</td><td>Créer</td><td>POST</td></tr><tr><td>Read</td><td>Afficher</td><td>GET</td></tr><tr><td>Update</td><td>Mettre à jour</td><td>PUT</td></tr><tr><td>Delete</td><td>Supprimer</td><td>DELETE</td></tr></tbody></table>
CORS et APIs

Seules certaines commandes ont CORS activé,
ces commandes sont toutes des lectures (GET),
Il est alors possible de les lancer dans un navigateur ou
script web.

Dans le cas d'une appli web, pour les autres commandes,
il faut passer par un appel côté serveur.
# La documentation des APIs

## Guide Dataverse :

https://guides.dataverse.org/en/5.14/api/

<figure><img src="image_43.png" /></figure>

bien préciser la version de Dataverse utilisée

<figure><img src="image_44.png" /></figure>

Les différentes APIs y sont documentées séparément
<figure><img src="image_45.png" /></figure>

# Les bibliothèques

Des bibliothèques dans différents langages de programmation pour construire des programmes.

* R : [atom4R](https://atom4r.fr), ⚠ **dataverse**

* Python : [pyDataverse](https://pydataverse.com)

* Java

* Javascript

* Ruby

Si le client n'existe/ne convient pas, utiliser des bibliothèques comme « curl » !

<figure><img src="image_46.png" /></figure>

Le Plus : intégration

✓ Correspond le plus souvent à l'usage final
Les clients API

<figure><img src="image_47.png" /></figure>

Permet des requêtes plus modulaires qu'avec
la console

* Par exemple :
  https://insomnia/rest/download
  https://www.postman.com/

<figure><img src="image_48.png" /></figure>

Le Plus : User Friendly

✔ Distinction et configuration des variables, environnements, sauvegarde...

<figure><img src="image_49.png" /></figure>

Le Moins : automatisation

- Outil séparé d'une potentielle chaîne de traitement
## Convention de nommage

**Une accolade** = Variable que vous devez modifier

* Exemple : `{alias_de_la_collection}` = l'identifiant de la collection sur laquelle vous souhaitez interagir

**Deux accolades** = Variable supportée par Insomnia

* Exemple : `{{ _ . base_url }}` = variable qui sera stockée dans Insomnia.

Il est possible de copier/coller ces variables
## Préparer son projet dans Insomnia

<figure><img src="image_50.png" /></figure>

<figure><img src="image_51.png" /></figure>

Sub Environments :

* Créer un environnement () :
  « BAC A SABLE »

* Créer un environnement
  « ENTREPOT »

## Initialiser la variable `{{_.base_url}}` pour chaque environnement

* https://demo.recherche.data.gouv.fr/api/

* https://entrepot.recherche.data.gouv.fr/api/
<figure><img src="image_52.png" /></figure>

## Exercice 1 : Votre premier appel API vers l'entrepôt

1.a : écrire un appel simple

serveur : bac-à-sable de l'entrepôt

https://demo.recherche.data.gouv.fr

verbe : GET

endpoint : metadatablocks

Que voyez-vous ?

<figure><img src="image_53.png" /></figure>
<figure><img src="image_54.png" /></figure>

## Exercice 1 : Votre premier appel API vers l'entrepôt

1.a Solution :

https://demo.recherche.data.gouv.fr/api/metadatablocks

ou

{{_.base_url }}metadatablocks

Les blocs de métadonnées s'affichent : leur identifiant, leur nom affiché et leur nom véritable.

Format d'affichage : {json}
<figure><img src="image_55.png" /></figure>

Exercice 1 : Quelques commandes supplémentaires

1.b Obtenir le schéma du bloc de métadonnées Générales en adaptant la commande :

https://demo.recherche.data.gouv.fr/api/metadatablocks/{nom du bloc}

1.c Réaliser l'appel avec un autre bloc (par exemple « Life Sciences »)

Rappel : la liste des blocs disponibles s'affiche avec l'appel à « metadatablocks »
Testez sur les deux plateformes « BAC A SABLE » et « ENTREPOT » !
<figure><img src="image_56.png" /></figure>

## Exercice 1 : Quelques commandes supplémentaires

1.b Solution :
{{ _ . base_url }} metadatablocks/citation

1.c Solution :
{{ _ . base_url }} metadatablocks/{bloc}

Exemple, pour « Life Sciences » :

{{ _ . base_url }} metadatablocks/biomedical

**NB** : ces appels peuvent se faire directement dans un navigateur web

<figure><img src="image_57.png" /></figure>
Les différentes APIs

* Search : Recherche

* Native : Fonctionnalités principales

* Direct Upload/Replace : Téléversement des fichiers

* Data Access : Téléchargement de fichiers

* Metrics : Statistiques d'utilisation

* SWORD : Dépôt de fichiers et jeux de données

* MyData ⚠ non documentée
## Rechercher des jeux de données

API = Search ou MyData

Cas d'usage :

* Recherche (**avancée**), avec ou sans **authentification** (Search)

* Récupérer les données d'un utilisateur (MyData)

NB :

* Pour rechercher sur des métadonnées spécifiques

* Pas toutes les métadonnées renvoyées (utiliser l'API Native)

* ⚠ **Pagination ⚠** : résultats limités par page
<figure><img src="image_58.png" /></figure>

## Exercice 2 : Rechercher des données

2.a Tester une nouvelle recherche :

```json
{{_.base_url }}search
```
.utiliser le paramètre : q)

2.b Filtrer sur un champ de métadonnées :

```json
{{_.base_url }}search?q={valeur}&fq={champ}: {valeur}
```
<figure><img src="image_59.png" /></figure>

RÉPUBLIQUE
FRANÇAISE

Liberté
Égalité
Fraternité

recherche.data.gouv.fr

## Exercice 2 : Rechercher des données

2.c Limiter le nombre de résultats par page :

```javascript
{{ _ . base_url }}
search?per_page={##}&q={valeur}&fq={champ} : {valeur}
```

2.d Récupérer un champ additionnel de métadonnées :

```javascript
{{ _ . base_url }}
search?per_page=1&q=tree&fq=tree:&metadata_fields={bloc} : {champ}
```

<figure><img src="image_60.png" /></figure>

<figure><img src="image_61.png" /></figure>

@RechercheDataGv
<figure><img src="image_62.png" /></figure>

RÉPUBLIQUE
FRANÇAISE

Liberté
Égalité
Fraternité

recherche.data.gouv.fr

# Bonne pratique avec Insomnia

Transformer les paramètres pour les éditer/(dés)activer facilement :
Onglet « Query » —> Import from URL

<figure><img src="image_63.png" /></figure>
## Exercice 2 : Correction

2.a Tester une nouvelle recherche :

{{ _ . base_url }} search?q=classe

2.b Filtrer sur un champ de métadonnées :

{{ _ . base_url }} search?q=classe
&fq=title:classe
## Exercice 2 : Correction

2.c Limiter le nombre de résultats par page :

`{{ _ . base_url }} search?per_page=1`

`&q=classe`

`&fq=title:classe`

2.d Récupérer un champ additionnel de métadonnées :

`{{ _ . base_url }} search?per_page=1`

`&q=*`

`&type=dataset`

`&metadata_fields=citation:depositor`
<figure><img src="image_64.png" /></figure>

<figure><img src="image_65.png" /></figure>

RÉPUBLIQUE
FRANÇAISE

Liberté
Égalité
Fraternité

recherche.data.gouv.fr

# L'AUTHENTIFICATION

<figure><img src="image_66.png" /></figure>

<figure><img src="image_67.png" /></figure>

LICENCE OUVERTE
OPEN LICENCE

<figure><img src="image_68.png" /></figure>

<figure><img src="image_69.png" /></figure>

@RechercheDataGv
## S'authentifier : le jeton API (1/3 l'obtenir)

* Sur Recherche Data Gouv, 1 se connecter puis :

<figure><img src="image_70.png" /></figure>
<figure><img src="image_71.png" /></figure>

## S'authentifier : le jeton API (2/3 l'utiliser)

<figure><img src="image_72.png" /></figure>

Une fois créé, il faut le copier (bouton « Copier dans le presse-papier »).

Le mode de renseignement du jeton dépend ensuite de l'outil utilisé.

* Exemple dans cURL :
  en-têteheader* « X-Dataverse-key » :

curl -H X-Dataverse-key :{jeton}
-X GET {ma commande}

<footnote>*éléments permettant d'envoyer au serveur des informations supplémentaires.</footnote>
<figure><img src="image_73.png" /></figure>

# S'authentifier : Bonne pratique Insomnia

Ajouter les variables d'environnement `{{_.api_token}}` et `{{_.api_key}}` pour s'authentifier :

```
"api_token": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX",
"api_key": "X-Dataverse-key"
```

<figure><img src="image_74.png" /></figure>
## Exercice 2bis : Rechercher des données en étant authentifié

2bis.a : Créer un appel avec l'endpoint « search?q=*&per_page=1 » sur le bac à sable
L'exécuter et noter la valeur de « total_count »

2bis.b : Créer un jeu de données sur le bac à sable depuis l'interface web, dans la
collection « Travaux pratiques » – Ne pas le publier !

2bis.c : Ajouter l'authentification pour l'appel que vous avez créé (onglet API Key) et
noter la différence pour la valeur de « total_count »
Correction 2bis : Rechercher des données en étant authentifié

2bis.a :

<< _ . base_url }} searchsearch?per_page=1&q= *

2bis.c :

La valeur de total_count est plus élevée lorsque l'on est identifié.
Pourquoi ? Une fois authentifié, les jeux de données en version provisoire auquel notre
compte à accès sont ajoutés.
## S'authentifier : le jeton API (3/3 le renouveler)

⚠️ Le jeton a une **durée de validité d'un an,**

Au delà le jeton est révoqué et il faut en créer un autre.

* Interface web : Bouton « Créer de nouveau le jeton » / « Recreate token »

* API : S'authentifier avec {{ _ . api_key }} et {{ _ . api_token }} en Header

Renouvellement :

Verbe : POST

{{ _ . base_url }} users/token/recreate

Information sur je jeton :

Verbe : GET

{{ _ . base_url }} users/token
## Gérer une collection

API = Native

Cas d'usage :

* Créer, modifier et publier une collection

* Gérer les informations, droits et autres possibilités du portail

* Supprimer la collection

* Récupérer les données des Registres des visiteurs

Point d'attention à l'usage :

* Authentification généralement nécessaire

* CORS
<figure><img src="image_75.png" /></figure>

## Exercice 3 : Créer une sous-collection

3.a Trouver la section « Create a Dataverse Collection » dans « Native API » de la documentation et télécharger le fichier **json** nécessaire à la création d'une collection via l'API https://guides.dataverse.org/en/5.14/api/native-api.html

3.b Créer un appel avec l'endpoint « dataverses/{alias-de-la-collection-travaux-pratiques} » et sélectionner le verbe « POST »

3.c Copier/coller le contenu du fichier json dans l'onglet **Body** > **JSON** d'Insomnia puis modifiez le pour qu'il corresponde à votre *collection de rêve*

3.d Créer votre collection dans la collection « Travaux Pratiques » du bac à sable
<figure><img src="image_76.png" /></figure>

RÉPUBLIQUE
FRANÇAISE

Liberté
Égalité
Fraternité

recherche.data.gouv.fr

Correction 3 : Créer une sous-collection

3.a https://guides.dataverse.org//en/latest/api/native-api.html#create-dataverse-api

<figure><img src="image_77.png" /></figure>

3.b

3.c

3.d

Ne pas oublier
l'onglet
API Key
pour faire une
requête
authentifiée !
<figure><img src="image_78.png" /></figure>

## Exercice 4 : Gérer une sous-collection

4.a Désactivez le bloc de métadonnées « journal » sur votre collection précédemment créée

https://guides.dataverse.org/en/5.14/api/native-api.html#define-metadata-blocks-for-a-dataverse-collection

4.b Assigner le rôle de curateur sur la collection précédemment crée à vous-même

https://guides.dataverse.org/en/5.14/api/native-api.html#assign-a-new-role-on-a-dataverse-collection

4.c Publier la collection

https://guides.dataverse.org/en/5.14/api/native-api.html#publish-a-dataverse-collection

<figure><img src="image_79.png" /></figure>
<figure><img src="image_80.png" /></figure>

Correction 4 : Gérer une sous-collection

4.a

<figure><img src="image_81.png" /></figure>

Pour vérifier :

{{ _ . base_url }} dataverses/ { alias_de_la_collection } / metadatablocks
Verbe GET
<figure><img src="image_82.png" /></figure>

Correction 4 : Gérer une sous-collection

4.b

<figure><img src="image_83.png" /></figure>

Pour vérifier :

{{ _ . base_url }} dataverses/ {{ alias_de_la_collection }} /assignments
Verbe GET (sans JSON)

4.c

<figure><img src="image_84.png" /></figure>

Pour récupérer un votre UserId

<figure><img src="image_85.png" /></figure>

<figure><img src="image_86.png" /></figure>

{{ _ . base_url }} users/:me

{{ _ . base_url }} dataverses/ {{ alias_de_la_collection }} /actions/:publish
# Gérer un jeu de données

## API = Native ou SWORD

## Cas d'usage

* Créer, modifier et publier un jeu de données

* Gérer les métadonnées, droits et autres possibilités du portail

* Supprimer le jeu de données

## Point d'attention à l'usage :

* Authentification généralement nécessaire

* CORS
<figure><img src="image_87.png" /></figure>

RÉPUBLIQUE
FRANÇAISE

Liberté
Égalité
Fraternité

recherche.data.gouv.fr

## Point d'attention : Les métadonnées spécifiques

Appliquer le schéma pour déposer ou importer des jeux de données

* Exemple complet (toutes métadonnées remplies) :

https://nextcloud.inrae.fr/s/BDf4sAPLe4edN3Z

* Exemple limité :

https://nextcloud.inrae.fr/s/a9pcG6kGKBGWexT

⚠ Attention aux évolutions ⚠

(ajout de nouvelles métadonnées) ⚠
<figure><img src="image_88.png" /></figure>

## Exercice 5 : Créer un jeu de données

5.a. Créer un appel avec l'endpoint dataverses/{alias dataverse}/datasets {alias dataverse} étant l'identifiant de votre *collection de rêve*

5.b : Télécharger le fichier json [nouveau jdd.json](https://nextcloud.inrae.fr/s/5XLRib2EwXFGPZS)

5.c : Copier/coller le contenu du fichier json de métadonnées dans :
Block > JSON »,
**modifier l'email du contact, a minima, et exécuter l'appel.**

<figure><img src="image_89.png" /></figure>

Ne pas oublier l'authentification
<figure><img src="image_90.png" /></figure>

RÉPUBLIQUE
FRANÇAISE

Liberté
Égalité
Fraternité

recherche.data.gouv.fr

Correction 5 : Créer un jeu de données

<figure><img src="image_91.png" /></figure>

Application possible :
dupliquer les métadonnées
d'un jeu de données de
l'entrepôt vers le bac à sable

<figure><img src="image_92.png" /></figure>

<figure><img src="image_93.png" /></figure>
<figure><img src="image_94.png" /></figure>

## NOTE : Dupliquer un jeu de données

* Pour dupliquer les métadonnées d'un jeu de données de l'entrepôt vers le bac à sable, il faut avoir les droits suffisants dessus pour récupérer les métadonnées cachées (ex. adresse mail contact, etc.)

Pour récupérer les métadonnées il faut les lister :

`{{_.base_url}}datasets/:persistentId?persistentId=doi:{DOI_du_JDD}`

Et les injecter (copier/coller) dans un nouveau jeu de données dans la collection souhaitée, de la même manière que dans l'exercice 5.

<figure><img src="image_95.png" /></figure>

Attention, les fichiers ne seront pas transférés.
<figure><img src="image_96.png" /></figure>

Exercice 6 : Gérer un jeu de données

6.a Publier le jeu de données (version majeur)

https://guides.dataverse.org/en/5.14/api/native-api.html#publish-a-dataset

6.b Modifier des métadonnées du jeu de données créé précédemment

https://guides.dataverse.org/en/5.14/api/native-api.html#edit-dataset-metadata
avec le fichier d'exemple :

https://guides.dataverse.org/en/5.14/downloads/cb0fae993277527ea354dc15bc5db864/dataset-edit-metadata-sample.json

6.c Publier à nouveau le jeu de données (version majeur)

6.d Lister les versions du jeu de données

`{{ base_url }}datasets/:persistentId/versions?persistentId=doi:{DOI_du_JDD}`
<figure><img src="image_97.png" /></figure>

RÉPUBLIQUE
FRANÇAISE

Liberté
Égalité
Fraternité

recherche.data.gouv.fr

Correction 6 : Gérer un jeu de données

6.a,c :

{{ _ . base_url }} datasets/:persistentId/actions/:publish?
persistentId=doi: { DOI_du_JDD }

&type=major

Verbe : POST

6.b :

{{ _ . base_url }} datasets/:persistentId/editMetadata?
persistentId=doi: { DOI_du_JDD }

&replace=true

Verbe : PUT

Il faut ajouter replace=true si
on souhaite modifier une
valeur

PUT

_ . base_url

datasets/:persistentId/editMetadata

JSON

API Key

Query

3

Headers

1

1 v {

2 v

"fields": [

3 v

{

"typeName": " subtitle ",

4

<figure><img src="image_98.png" /></figure>

<figure><img src="image_99.png" /></figure>

@RechercheDataGv
<figure><img src="image_100.png" /></figure>

# Gestion des fichiers

## API = Native ou Data Access

### Cas d'usage

* Créer, remplacer, modifier et supprimer des fichiers

* Administrer (et demander) l'accès

* Télécharger des fichiers ou certaines de leurs variables

### Point d'attention à l'usage :

* Authentification généralement nécessaire

* CORS (voir *diapo 46*)
<figure><img src="image_101.png" /></figure>

## Exercice 7 : Déposer des fichiers

7.a Déposer un fichier texte depuis votre machine dans votre jeu de données

Verbe : POST

Endpoint : datasets/:persistentId/add?persistentId=doi:\{DOI_du_JDD\}

Dans Body > Multipart Form, ajouter deux paramètres (bouton « Add ») :

* name : file

value : choisir **file** que l'on trouve sous la petite flêche (à droite)

* name : laisser vide

value : laisser vide

<figure><img src="image_102.png" /></figure>
<figure><img src="image_103.png" /></figure>

## Exercice 7bis : Déposer des fichiers

7.b Rendre le fichier accessible en publiant le jeu de données

7.c Lister les fichiers du jeu de données

{{_.base_url }}datasets:/persistentId/versions/{n°_de_version}/files?
persistentId={DOI_du_JDD}
<figure><img src="image_104.png" /></figure>

Correction 7 : Déposer des fichiers

7.a

{{ _ . base_url }} datasets/:persistentId/add?

persistentId=doi: {DOI_du_JDD}

Verbe : POST

7.b :

{{ _ . base_url }} datasets/:persistentId/actions/:publish?

persistentId=doi: {DOI_du_JDD}

&type= major

Verbe : POST

7.C.

{{ _ . base_url }} datasets/:persistentId/versions/{n°_de_version}/files?

persistentId={DOI_du_JDD}

Verbe : GET

<figure><img src="image_105.png" /></figure>
<figure><img src="image_106.png" /></figure>

Exercice 8 : Récupérer des fichiers

8.a Trouver la documentation sur la DATA Access API

https://guides.dataverse.org/en/5.14/

8.b Télécharger tous les fichiers du jeu de données 10.57745/EELX9B sur l'entrepôt

8.c Lister les fichiers de ce jeu de données

{{_.base_url }}datasets/:persistentId/?persistentId={DOI_du_JDD}

8.d Puis télécharger un seul fichier de ce jeu de données

{{_.base_url }}access/datafile/:persistentId?persistentId={DOI_du_fichier}
# Correction 8 : Récupérer des fichiers

## 8.b Télécharger tout

{{_.base_url }}access/dataset/:persistentId/?

persistentId=doi:10.57745/EELX9B

Verbe : GET

## 8.c Lister

{{_.base_url }}datasets/:persistentId/?

persistentId=doi:10.57745/EELX9B

Verbe : GET

## 8.d Télécharger un

{{_.base_url }}access/datafile/:persistentId/?

persistentId=doi:10.57745/UQIFOB

Verbe : GET

<figure><img src="image_107.png" /></figure>
# Métrique

## API = Metrics

## Cas d'usage

* Récupérer des métriques sur le portail (créations, téléchargements...)

* Récupérer des métriques pour une collection

* Récupérer des métriques d'utilisation pour un jeu de données

## Point d'attention à l'usage :

* Données de bac à sable pas forcément renseignées
Exercice 9 : Récupération de données métriques

https://guides.dataverse.org/en/5.14/api/metrics.html

9.a Métriques de téléchargements de l'entrepôt

9.b Métriques de téléchargements d'une collection par mois ( monthly )

9.c Métriques de téléchargements dans une collection par thématique ( bySubject )

9.d Métriques de téléchargements uniques des fichiers, par mois, dans une collection
## Correction 9

9.a Tous téléchargements
{{_.base_url }}info/metrics/downloads
Verbe : GET

9.b Téléchargements mensuels dans une collection
{{_.base_url }}info/metrics/downloads/monthly?
parentAlias={alias_du_dataverse}
Verbe : GET
## Correction 9.bis

9.c Téléchargements dans une collection par thématique

`{{_.base_url }}info/metrics/dataverses/bySubject?
parentAlias={alias_du_dataverse}`

Verbe : GET

9.d Téléchargements uniques, par mois, dans une collection

`{{_.base_url }}info/metrics/uniquedownloads/monthly?
parentAlias={id_de_collection}`

Verbe : GET
Merci
pour votre écoute
<figure><img src="image_108.png" /></figure>

# Classe Virtuelle : Utilisation des APIs

<figure><img src="image_109.png" /></figure>

Centre de ressources
entrepôt-catalogue

<figure><img src="image_110.png" /></figure>

Recherche Data Gouv

support-recherchedatagouv@inrae.fr

<figure><img src="image_111.png" /></figure>

<figure><img src="image_112.png" /></figure>

LICENCE OUVERTE
OPEN LICENCE

Support réalisé par : Camille Desiles (CNRS-INIST) ; Virgile Jarrige (Unistra) ; Damien Sans (INRAE) ; Dimitri Szabo (INRAE)
<figure><img src="image_113.png" /></figure>

RÉPUBLIQUE
FRANÇAISE

Liberté
Égalité
Fraternité

recherche.data.gouv.fr

Une gouvernance collective

• Partenaires du projet

INRAE
la science pour la vie, l'humain, la terre

UGA
Université

Grenoble Alpes

<figure><img src="image_114.png" /></figure>

UNIVERSITÉ
DE LORRAINE

<figure><img src="image_115.png" /></figure>

<figure><img src="image_116.png" /></figure>

Université
de Lille

Université

de Strasbourg

<figure><img src="image_117.png" /></figure>

Université
Paris Cité

<figure><img src="image_118.png" /></figure>

Université
Paris Nanterre

• Représentants de la communauté ESR

cea

<figure><img src="image_119.png" /></figure>

UNIVERSITÉ TOULOUSE
Jean Jaurès

université
PARIS-SACLAY

université
de BORDEAUX

<figure><img src="image_120.png" /></figure>

<figure><img src="image_121.png" /></figure>

<figure><img src="image_122.png" /></figure>

@RechercheDataGv
<figure><img src="image_123.png" /></figure>

# ANNEXE A : API MyData : Documentation

* Endpoint : {serveur}/api/mydata/retrieve

* Paramètres :

* ⚠ Key = Jeton de l'utilisateur; pour cette API il ne doit pas être passé dans le header (jusqu'à la version 5.14)

* role_ids = Rôles de l'utilisateur, plusieurs valeurs possibles parmi :

* 1 = Admin

* 2 = File Downloader

* 3 = Dataverse + Dataset Creator

* 4 = Dataverse Creator

* 5 = Dataset Creator

* 6 = Contributor

* 7 = Curator

* 8 = Member

* dvobject_types = Type d'objet, plusieurs valeurs possibles parmi :

* DataFile

* Dataset

* Dataverse

* published_states = Etat de l'objet, plusieurs valeurs possibles parmi :

* Published

* Unpublished

* Draft

* Deaccessioned

* In+Review

* per_page = Nombre de résultats renvoyés par page