DV Uploader

L’interface de dépôt de l'entrepôt Recherche Data Gouv peut parfois être limitante, comme dans le cas de dépôt de nombreux fichiers. Si les APIs permettent de répondre à ces problématiques, il existe également un outil moins technique permettant de déposer directement le contenu de dossiers locaux : DVUploader. Cet article vous guidera à travers l’utilisation de cet outil.

DVUploader est un outil de dépôt local vers Dataverse (donc vers l'entrepôt Recherche Data Gouv) développé par la communauté Dataverse. Comme il est exécuté sur le poste du déposant il permet d’envoyer facilement l’intégralité du contenu d’un dossier avec ses sous répertoires, de contourner la limite de dépôt de 1000 fichiers par téléversement, et de mettre à jour un jeu de données en déposant seulement les nouveaux fichiers dans un répertoire.

Cet outil requiert une installation ainsi que l’usage de la console de commande, mais son utilisation reste très simple.

Les commandes à saisir dans la console seront indiquées avec la mise en forme suivante :

Exemple de commande

Installation

Prérequis

Cet outil nécessite l’installation de Java (8 ou plus).

Télécharger l’outil

La dernière version est disponible sur la page https://github.com/GlobalDataverseCommunityConsortium/dataverse-uploader/releases/. Télécharger le fichier .jar dans la section « Assets » de celle-ci.

Lien de téléchargement direct pour la version 1.1.0.

Placer ce fichier dans un répertoire approprié.

Remarque : Veiller à avoir accès à ce dossier ensuite pour pouvoir l’exécuter ! Si il est dans « C:\Program Files », lancer la console en tant qu’administrateur pour pouvoir lancer DVUploader.

Utilisation sous Windows

L'exemple ci-dessous est réalisé dans le bac à sable de l'entrepôt Recherche Data Gouv. Il est recommandé de l'utiliser pour tester cet outil.

1. Ouvrir le terminal

Ouvrir l’application « Invite de commandes » (C:\WINDOWS\system32\cmd.exe).

Remarque : Ceci peut être fait via le raccourci : « Win + R » puis taper « cmd » et « Entrée »

2. Se placer dans le répertoire du .jar

Pour une exécution plus simple par la suite, se placer dans le répertoire où DVUploader est enregistré avec la commande suivante en remplaçant {Dossier de DVUploader} sans les accolades par le chemin du fichier .jar (voir Installation).

cd {Dossier de DVUploader}

Il est possible de copier directement le chemin avec un clic droit puis « Propriétés » dans le dossier concerné, il est indiqué après « Emplacement : ».

Remarque : Si des noms de dossiers comportent des espaces, le chemin d’accès doit être entre guillemets.

3. Définir les paramètres en variables

Instancier les variables suivantes comme indiqué en remplaçant les {valeurs} par les valeurs (sans accolade) suivantes :

• Jeton API

La clé ou jeton API associée au compte d'un utilisateur est trouvable sur le portail après connexion dans « Jeton API » en cliquant sur le nom de l'utilisateur :

Remarque : ce jeton dispose d’une durée de vie d’un an, il est possible d'en regénérer un depuis cette même page.

set API_KEY={clé API}

Exemple :

set API_KEY="1212-1212-1212-1212-1212-1212-1212"

• Adresse du portail

Pour le bac à sable:
set SERVER="https://demo.recherche.data.gouv.fr"
Utiliser l’adresse https://entrepot.recherche.data.gouv.fr pour la production.

• DOI du dataset

Avant de déposer des données, créer un dataset, copier ensuite le DOI (ex. 10.70112/RDGTI6). Dans la commande, indiquer le {DOI} sous la forme 10.xxx/xxxx
set DOI=doi:{DOI}
Remarque : il est possible d'utiliser d’autres noms de variables mais veiller à ce que ces noms soient aussi ceux utilisés dans la commande de dépôt.

4. Déposer un fichier

• Chemin vers le fichier

Il reste une dernière variable à configurer. Elle est différente selon les cas 4 et 4bis :
set PATH_TO_DATA={chemin vers les données}
avec un {chemin vers les données} indiquant les fichiers à déposer. Ce chemin peut être absolu ou relatif.

Exemple (chemin relatif) :
set PATH_TO_DATA=Documents\monFichier.csv

Remarque : Si vos noms de dossiers comportent des espaces, ils doivent être entre guillemets :
set PATH_TO_DATA="Documents\Depot Fichier\monFichier.csv"

• Dépôt

java -jar DVUploader-v1.1.0.jar -key=%API_KEY% -did=%DOI% -server=%SERVER% %PATH_TO_DATA -directupload
On retrouve les %VARIABLES% créées précédemment.
Remarques :

• Il est également possible d'utiliser directement les valeurs indiquées pour les variables dans la commande. Ceci est déconseillé dans le cas de la clé d’API pour laquelle il est recommandé de toujours passer par une variable.
• Dans cet exemple, la version DVUploader-v1.1.0.est utilisée, le nom de fichier .jar devra être modifié en cas d'utilisation d'une autre version.

4 Bis. Déposer des fichiers en arborescence

• Chemin vers le dossier

Il est également possible de téléverser le contenu d’un dossier ou d’une arborescence.
Dans ce cas :
set PATH_TO_DATA={chemin vers les données}
Pointera vers un dossier. Les mêmes remarques que pour le fichier s’appliquent.
Remarque : si des guillements sont utilisés, ne pas finir la chaîne de caractère avec : \"

• Dépôt

La commande à exécuter est la même que pour le fichier, mais pour inclure les sous dossiers, ajouter le paramètre « recurse ».
java -jar DVUploader-v1.1.0.jar -key=%API_KEY% -did=%DOI% -server=%SERVER% %PATH_TO_DATA% -directupload -recurse

5. Exemple 

set API_KEY="1212-1212-1212-1212-1212-1212-1212"
set SERVER="https://demo.recherche.data.gouv.fr"
set DOI=doi:10.70112/RDGTI6
set PATH_TO_DATA="C:\Users\Nom\Documents\Data"
java -jar DVUploader-v1.1.0.jar -key=%API_KEY% -did=%DOI% -server=%SERVER% %PATH_TO_DATA% -directupload 

6. Paramètres additionnels

D’autres paramètres facultatifs peuvent être utilisés comme « recurse » dans la section 4bis.
La liste complète est disponible dans la documentation de l’outil. Seuls les paramètres susceptibles d’être les plus utiles sont présentés.

• limit

Permet de limiter le nombre de fichiers par envoi.
Ceci peut-être utile pour faire un test sans envoyer l’intégralité d’un dossier, ou lors de l’envoi automatique d’un grand nombre de fichiers afin de les envoyer progressivement.
Exemple :

java -jar DVUploader-v1.1.0.jar -key=%API_KEY% -did=%DOI% -server=%SERVER% %PATH_TO_DATA% -directupload -limit=1

• ex

Permet d’exclure de l’envoi des fichiers.

Ce paramètre exclut les fichiers correspondant à une expression régulière donnée.
Par exemple pour exclure les fichiers .txt :

java -jar DVUploader-v1.1.0.jar -key=%API_KEY% -did=%DOI% -server=%SERVER% %PATH_TO_DATA% -directupload -ex=*.txt$

Remarque : Il est possible d’utiliser plusieurs fois ce paramètre pour utiliser plusieurs filtres.
Exemples de correspondance de caractères  :

* : n’importe quelle chaîne de caractères (Exemple : *.txt reconnaît « fichier.txt ») .

? : un seul caractère (Exemple : fast? reconnait « fasta » et « fastq »).

^: début de la chaîne de caractères (Exemple : ^bck* reconnait « bck20200617 »).

$ : fin de la chaîne de caractères (Exemple : *txt$ reconnaît « fichier.txt » et pas « datafromtxt.csv »).

Utilisation sous Linux

La procédure est la même que sous Windows, cette section présente seulement directement les commandes en bash.

Remarque : le numéro de version de DVUploader est indiqué dans les commandes, il est nécessaire de le modifier si une autre version que la 1.1.0 est utilisée.

1.  Définir les paramètres en variables (Recommandé)

Les différents paramètres de la commande peuvent directement passés dans cette dernière mais l'utilisation de variables permet une lecture plus simple et facilite des exécutions itératives si nécessaires.

• export API_KEY={clé API}
  trouvable sur https://demo.recherche.data.gouv.fr/dataverseuser.xhtml?selectTab=apiTokenTab pour la préproduction)
• export SERVER="https://demo.recherche.data.gouv.fr" (ou https://entrepot.recherche.data.gouv.fr en production)
• export DOI={DOI du dataset où déposer les fichiers} (dans la forme {doi:10.70112/XXX})
• export PATH_TO_DATA={chemin vers les données}

2. Déposer un fichier

Si le chemin indiqué pointe vers un fichier.

java -jar DVUploader-v1.1.0.jar -key=$API_KEY -did=$DOI -server=$SERVER $PATH_TO_DATA -directupload

2 bis. Déposer des fichiers en arborescence

Si le chemin indiqué pointe vers un dossier, les fichiers présents dans ce dossier seront téléversés, mais il est également possible de téléverser le contenu d’une arborescence avec l’option -recurse.

java -jar DVUploader-v1.1.0.jar -key=$API_KEY -did=$DOI -server=$SERVER $PATH_TO_DATA -directupload -recurse

3. Exemple 

mkdir ~/DVUploader
cd ~/DVUploader
wget https://github.com/GlobalDataverseCommunityConsortium/dataverse-uploader/releases/download/v1.1.0/DVUploader-v1.1.0.jar
export API_KEY="1212-1212-1212-1212-1212-1212-1212"
export SERVER="https://demo.recherche.data.gouv.fr"
export DOI=doi:10.70112/RDGTI6
export PATH_TO_DATA="../data/"

4. Paramètres additionnels

Voir la section « 6. Paramètres additionnels » de la partie Windows, ou la liste complète dans la documentation de l’outil,