Utilisation de DVUploader

L’interface de dépôt de Data INRAE 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 Data INRAE) 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 dataset 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) : https://java.com/fr/download/.

Télécharger l’outil

Vous pouvez trouver la dernière version sur la page https://github.com/GlobalDataverseCommunityConsortium/dataverse-uploader/releases/ et 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 : https://github.com/GlobalDataverseCommunityConsortium/dataverse-uploader/releases/download/v1.1.0/DVUploader-v1.1.0.jar.

Vous pouvez ensuite placer ce fichier où vous souhaitez conserver l’outil.

N.B : Veillez à avoir accès à ce dossier ensuite pour pouvoir l’exécuter ! Si vous utilisez par exemple « C:\Program Files », vous devrez lancer la console en tant qu’administrateur pour pouvoir lancer DVUploader.

Utilisation :

Remarques préalables :

Pour cet exemple nous utilisons la préproduction de Data INRAE (https://data-preproduction.inrae.fr/).
Nous vous recommandons de faire de même pour votre premier essai.
N.B : comme pour l’interface en ligne, pour interagir avec la préproduction vous devez être connecté au réseau INRAE ou avoir activé votre VPN.
Si vous n’avez pas cette possibilité, vous pouvez utiliser l’adresse https://demo.dataverse.org pour les tests.

A – Sous Windows

1. Ouvrir le terminal

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

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

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

Pour une exécution plus simple par la suite, placez vous dans le répertoire où vous avez enregistré DVUploader avec la commande suivante en remplaçant {Dossier de DVUploader} par le chemin vers lequel vous avez enregistré le fichier .jar (voir Installation).

cd {Dossier de DVUploader}

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

N.B : 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

Instanciez les variables suivantes comme indiqué en remplaçant les {valeurs} par les valeurs qui correspondent à votre cas, sans accolades.

Jeton API

La clé ou jeton API associée à votre compte est trouvable sur le portail en vous connectant, dans « Jeton API » / « API Token » en cliquant sur votre nom :

Jeton API

(https://data-preproduction.inrae.fr/dataverseuser.xhtml?selectTab=apiTokenTab pour la préproduction.)

Remarque : ce jeton dispose d’une durée de vie d’un an, vous pouvez 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 la préproduction :

set SERVER="https://data-preproduction.inrae.fr"

Utiliser l’adresse https://data.inrae.fr pour la production.

DOI du dataset

Vous devez avant d’y déposer des données avoir créé un dataset, copiez ensuite le DOI (ex. 10.70112/RDGTI6).
N.B : Dans la commande, indiquer le {DOI} sous la forme 10.xxx/xxxx

set DOI=doi:{DOI}

Remarque : vous pouvez utiliser d’autres noms de variables selon votre préférence mais veillez à 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 car différentes dans les cas 3 et 3bis :

set PATH_TO_DATA={chemin vers les données}

avec un {chemin vers les données} indiquant les fichier à déposer. Par exemple :

set PATH_TO_DATA=Documents\monFichier.csv

Ce chemin peut être absolu ou relatif.

N.B : 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%

On retrouve les %VARIABLES% crées précédemment.
N.B : Notez que le fichier .jar est ici « DVUploader-v1.1.0.jar », si vous utilisez une autre version, il faudra bien-sûr utiliser le bon nom de fichier.

Remarque : vous pouvez également 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.

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.

N.B : Attention, si vous utilisez des guillements à 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 si vous voulez également inclure les sous dossier, il faut ajouter le paramètre « recurse« .

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

5. Exemple :

set API_KEY="1212-1212-1212-1212-1212-1212-1212"
set SERVER="https://data-preproduction.inrae.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%

6. Paramètres additionnels

D’autres paramètres facultatifs peuvent être utilisés comme « recurse » dans la section 3bis.
La liste complète est disponible dans la documentation de l’outil, nous ne présentons ici que les paramètres jugés les plus susceptibles d’être utiles.

-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 si vous automatisez l’envoi d’un grand nombre de fichiers afin de les envoyer progressivement.
Exemple d’utilisation :

java -jar DVUploader-v1.1.0.jar -key=%API_KEY% -did=%DOI% -server=%SERVER% %PATH_TO_DATA% -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.
Vous pouvez ainsi exclure les fichiers avec une certaine extension ou nom.
Par exemple pour exclure les fichiers .txt :

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

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

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

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

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

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

B – Sous Linux

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

N.B. le numéro de version de DVUploader est indiqué dans les commandes, il est nécessaire de le modifier si vous utilisez une autre version que la 1.1.0

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

Les différents paramètres de la commande sont bien sûr passable directement dans cette dernière mais utiliser des variables permet une lecture plus simple et plus de flexibilité si plusieurs éxecutions sont nécessaires

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

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 -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://data-preproduction.inrae.fr"
export DOI=doi:10.70112/RDGTI6
export PATH_TO_DATA="../data/"
java -jar DVUploader-v1.1.0.jar -key=$API_KEY -did=$DOI -server=$SERVER $PATH_TO_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,