dxda
0.6.2
Outil CLI pour gérer le téléchargement de grandes quantités de fichiers depuis DNAnexus
REMARQUE : Il s'agit d'une première version de cet outil et est en cours de test dans divers contextes. Veuillez contacter DNAnexus si vous souhaitez savoir si cet outil est approprié pour votre application.
Pour démarrer avec dx-download-agent , téléchargez le dernier binaire précompilé à partir de la page de version. L'agent de téléchargement accepte deux fichiers :
manifest_file : fichier manifeste JSON compressé en BZ2 qui décrit, au minimum, les informations suivantes pour un téléchargement, par exemple :
{ "projet-AAAA": [
{ "id": "file-XXXX", "name": "foo", "folder": "/path/to", "parts": { "1": { "size": 10, "md5": "49302323" }, "2": { "taille": 5, "md5": "39239329" }
}
}, "..."
], "projet-BBBB": [ "..." ]
}Pour démarrer un processus de téléchargement, générez d’abord un jeton API DNAnexus valable pour la période pendant laquelle vous prévoyez de télécharger les fichiers. Stockez-le dans la variable d'environnement suivante :
export DX_API_TOKEN=
Si aucun jeton API n'est fourni, l'agent de téléchargement consultera le fichier ~/.dnanexus_config/environment.json également utilisé par dx-toolkit.
Pour démarrer le téléchargement :
dx-download-agent download exome_bams_manifest.json.bz2 Obtained token using environment Creating manifest database manifest.json.bz2.stats.db Required disk space = 1.2TB, available = 3.6TB Logging detailed output to: manifest.json.bz2.download.log Preparing files for download Downloading files using 8 threads Downloaded 11904/1098469 MB 124/11465 Parts (104.0 MB written to disk in the last 60s)
Un rapport continu sur la progression du téléchargement est écrit à l'écran. Avant de démarrer le transfert de données, on vérifie qu'il y a suffisamment d'espace disque pour la liste complète des fichiers. Sinon, une erreur est signalée et rien n'est téléchargé. La vitesse de téléchargement reflète non seulement la bande passante du réseau, mais également la capacité d'E/S de votre machine.
Un journal de téléchargement contient des informations plus détaillées sur le téléchargement en cas d'erreur. Si une erreur se produit et que vous ne comprenez pas comment la résoudre, veuillez contacter [email protected] avec le fichier journal ci-joint et nous vous aiderons.
Veuillez noter que la réexécution de la commande dx-download-agent download ne retéléchargera PAS les fichiers précédemment téléchargés qui ont ensuite été déplacés, supprimés ou modifiés. Veuillez exécuter dx-download-agent inspect (décrit ci-dessous) pour détecter toute modification apportée aux fichiers précédemment téléchargés et les marquer pour un nouveau téléchargement. Voir Déplacer les fichiers téléchargés pour plus de détails.
Vous pouvez interroger la progression d'un téléchargement existant dans un terminal séparé
dx-download-agent progress exome_bams_manifest.json.bz2
et vous obtiendrez un bref résumé de l'état des téléchargements :
21.6 MB/sec 1184/27078 MB 18/327 Parts Downloaded and written to disk
Pour vérifier l'intégrité des fichiers téléchargés, vous pouvez exécuter
dx-download-agent inspect exome_bams_manifest.json.bz2
Cette commande effectuera une inspection des fichiers et garantira que leurs sommes MD5 correspondent au manifeste. Si un fichier est manquant ou si une somme MD5 ne correspond pas, l'agent de téléchargement signalera les fichiers concernés et vous pourrez ensuite exécuter à nouveau dx-download-agent download pour retélécharger les fichiers concernés.
-num_threads (entier) : nombre maximum de threads simultanés à utiliser lors du téléchargement ou de l'inspection de fichiers
Par exemple, la commande
dx-download-agent download -num_threads=20 exome_bams_manifest.json.bz2
créera un pool de travailleurs de 20 threads qui téléchargeront des parties de fichiers en parallèle. Un maximum de 20 travailleurs effectueront des téléchargements à tout moment. La limitation du débit des téléchargements peut être contrôlée dans une certaine mesure en faisant varier ce nombre.
Les informations sur les parties téléchargées sont conservées dans un fichier de base de données sqlite3 qui contient des informations similaires sur le contenu du format de fichier JSON plus un champ bytes_fetched supplémentaire.
Nom de la table : manifest_stats
Champs (tous les champs sont des chaînes, sauf indication contraire)
file_id : ID de fichier pour la partie du fichier
project : ID du projet pour la partie du fichier
name : nom du fichier
folder : dossier contenant le fichier sur DNAnexus
part_id (entier) : ID de pièce pour le fichier
md5 : somme md5 pour l'ID de la pièce
size (entier) : taille de la pièce
block_size (entier) : taille du bloc principal du fichier (supposée égale à size sauf pour la dernière partie)
bytes_fetched (integer <= size ) : nombre total d'octets téléchargés
C'est à l'implémentation de décider si oui ou non bytes_fetched est mis à jour de manière plus grossière ou plus fine. Par exemple, bytes_fetched ne peut être mis à jour que lorsque le téléchargement de la partie est terminé. Dans ce cas, ses valeurs ne seront que 0 ou la valeur de size .
Le manifeste comprend quatre champs pour chaque fichier : file_id , project , name et parts . Si les quatre sont spécifiés, le fichier est supposé être actif et fermé, ce qui le rend disponible au téléchargement. Si le champ parts est omis, le fichier sera décrit sur la plateforme. Les descriptions en masse sont utilisées pour le faire efficacement pour de nombreux fichiers par lots. Les fichiers archivés ou non fermés ne peuvent pas être téléchargés et déclencheront une erreur.
Il est possible de télécharger des liens symboliques DNAx, qui ne comportent aucune pièce. Les champs obligatoires pour les liens symboliques sont file_id , project et name . Notez qu'un lien symbolique possède une somme de contrôle MD5 globale, qui est vérifiée à la fin du téléchargement.
Outre le binaire Go autonome, nous proposons également une version Dockerisée. Il peut être utilisé de manière très similaire en tant qu'exécutable autonome, à l'exception de la nécessité de monter votre dossier local et de fournir votre jeton API DX.
Actuellement, nous proposons les balises d'image suivantes :
latest - la version la plus récente de la branche master
0.5.11 , 0.5.12 , ... - balises dédiées pour chaque version (à partir de 0.5.11)
Exemple d'utilisation :
$ docker run -v $PWD:/workdir -w /workdir -e DX_API_TOKEN=$DX_API_TOKEN dnanexus/dxda:latest download -max_threads=20 manifest.json.bz2
où:
$PWD est un chemin vers le répertoire de votre ordinateur vers lequel télécharger des fichiers.
DX_API_TOKEN est un token pour accéder à notre plateforme (voir Démarrage rapide)
Pour diriger dx-download-agent vers un proxy, veuillez définir la variable d'environnement HTTP_PROXY sur quelque chose comme export HTTP_PROXY=hostname:port . HTTPS_PROXY est également pris en charge.
Par défaut, dx-download-agent utilise les certificats installés sur le système pour créer des connexions sécurisées. Si votre système nécessite un certificat TLS supplémentaire et dx-download-agent ne semble pas utiliser de certificat installé sur votre système, il existe deux options par ordre de préférence. Tout d’abord, définissez la variable d’environnement DX_TLS_CERTIFICATE_FILE sur le chemin du fichier de certificat TLS codé en PEM requis par votre organisation parent. En dernier recours, vous pouvez vous connecter de manière non sécurisée en évitant complètement la vérification du certificat en définissant DX_TLS_SKIP_VERIFY=true . Utilisez-le uniquement à des fins de test.
Pour plus de commodité, le fichier create_manifest.py dans le répertoire scripts/ est un moyen de créer des fichiers manifestes pour l'agent de téléchargement. Ce script nécessite que le dx-toolkit soit installé sur votre système et que vous soyez connecté à la plateforme DNAnexus. Un exemple de la façon dont il peut être utilisé :
python3 create_manifest.py "Projet :/Dossier" --recursive --output_file "myfiles.manifest.json.bz2"
Ici, un manifeste est créé pour tous les fichiers récursivement sous le nom du projet Project et dans le dossier Folder .
Le manifeste peut ensuite être filtré à l'aide du script filter_manifest.py . Par exemple, si vous souhaitez capturer des fichiers dans un dossier particulier (par exemple Folder ) contenant testcall (par exemple /Folder/ALL.chr22._testcall_20190222.genotypes.vcf.gz ), vous pouvez exécuter la commande :
$ python3 filter_manifest.py manifest.json.bz2 '^/Folder.*testcall.*'
où le deuxième argument donné au script est une expression régulière sur le chemin complet (dossier + nom de fichier).
Dans certains cas, il peut être souhaitable de diviser le manifeste de téléchargement en plusieurs fichiers manifestes à des fins de test ou de gérer plusieurs téléchargements d'un ensemble de données complet dans différents environnements. Pour diviser le fichier, nous fournissons un simple utilitaire Python qui ne nécessite aucun package supplémentaire dans le répertoire scripts/ . Par exemple, en exécutant la commande :
python3 scripts/split_manifest.py manifest.json.bz2 -n 100
créera des fichiers manifestes contenant chacun 100 fichiers par projet. Par exemple, s'il y a 300 fichiers au total dans manifest.json.bz2, la sortie de cette commande créera trois fichiers nommés : manifest_001.json.bz2 , manifest_002.json.bz2 et manifest_003.json.bz2 . Chacun de ces fichiers peut être utilisé indépendamment avec l'agent de téléchargement.
Ce référentiel peut également être utilisé directement comme module Go. Dans le répertoire cmd/dx-download-agent , le fichier dx-download-agent.go est un exemple de la façon dont il peut être utilisé.
Pour développer et expérimenter la source dans un environnement Docker isolé, le Dockerfile de ce référentiel peut être un bon début.
Après le téléchargement réussi (et éventuellement l'inspection post-téléchargement), vous devriez pouvoir déplacer les fichiers en toute sécurité vers l'emplacement souhaité.
AVERTISSEMENT : En général, nous vous conseillons de ne pas déplacer de fichiers au cours d'un téléchargement, mais leur déplacement peut être sûr dans certains cas particuliers. L'agent de téléchargement fonctionne en maintenant une base de données légère des parties de fichiers qui ont été téléchargées ou non. il fonctionne principalement à partir de. Cela signifie que même si vous déplacez des fichiers, l'agent de téléchargement ne s'en rendra pas compte tant que vous n'aurez pas exécuté la sous-commande inspect qui effectue des vérifications après téléchargement de l'intégrité des fichiers sur le disque. La commande inspect remarquera que les fichiers sont manquants, mettra à jour la base de données et, lorsque vous relancerez une commande de téléchargement, tentera de les télécharger à nouveau. Par conséquent, si vous déplacez les fichiers terminés et n’exécutez pas la sous-commande inspect, l’agent de téléchargement doit continuer là où il s’est arrêté. Cela étant dit, il existe un danger à déplacer des fichiers si le téléchargement du fichier n'est pas encore terminé. Dans ce cas vous aurez déplacé un dossier incomplet.
Seuls les objets de classe Fichier peuvent être téléchargés.
