com.dxda
0.6.2
أداة CLI لإدارة تنزيل كميات كبيرة من الملفات من DNAnexus
ملاحظة: هذه نسخة مبكرة من هذه الأداة وتخضع للاختبار في مجموعة متنوعة من الإعدادات. يرجى الاتصال بـ DNAnexus إذا كنت مهتمًا بمعرفة ما إذا كانت هذه الأداة مناسبة لتطبيقك.
للبدء في استخدام dx-download-agent ، قم بتنزيل أحدث إصدار ثنائي تم تجميعه مسبقًا من صفحة الإصدار. يقبل وكيل التنزيل ملفين:
manifest_file : ملف بيان JSON مضغوط بـ BZ2 يصف، على الأقل، المعلومات التالية للتنزيل، على سبيل المثال:
{ "مشروع-AAAA": [
{ "id": "file-XXXX"، "name": "foo"، "folder": "/path/to"، "parts": { "1": { "size": 10، "md5": "49302323" }, "2": { "الحجم": 5, "md5": "39239329" }
}
}، "..."
], "مشروع-BBBB": [ "..." ]
}لبدء عملية التنزيل، قم أولاً بإنشاء رمز DNAnexus API المميز الذي يكون صالحًا لفترة زمنية تخطط لتنزيل الملفات فيها. قم بتخزينه في متغير البيئة التالي:
تصدير DX_API_TOKEN=
إذا لم يتم توفير رمز مميز لواجهة برمجة التطبيقات، فسيبحث وكيل التنزيل عن ملف ~/.dnanexus_config/environment.json المستخدم أيضًا بواسطة مجموعة أدوات dx.
لبدء التنزيل:
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)
تتم كتابة تقرير مستمر عن تقدم التنزيل على الشاشة. قبل البدء في نقل البيانات، يتم إجراء فحص للتأكد من وجود مساحة قرص كافية لقائمة الملفات بأكملها. إذا لم يكن الأمر كذلك، فسيتم الإبلاغ عن خطأ ولن يتم تنزيل أي شيء. لا تعكس سرعة التنزيل النطاق الترددي للشبكة فحسب، بل تعكس أيضًا قدرة الإدخال والإخراج (IO) لجهازك.
يحتوي سجل التنزيل على معلومات أكثر تفصيلاً حول التنزيل في حالة حدوث خطأ. إذا حدث خطأ ولم تفهم كيفية التعامل معه، فيرجى الاتصال [email protected] مع إرفاق ملف السجل وسنساعدك.
يرجى ملاحظة أن إعادة تشغيل أمر dx-download-agent download لن يؤدي إلى إعادة تنزيل أي ملفات تم تنزيلها مسبقًا والتي تم نقلها أو حذفها أو تعديلها لاحقًا. يرجى تشغيل dx-download-agent inspect (الموضح أدناه) لاكتشاف أي تغييرات على الملفات التي تم تنزيلها مسبقًا ووضع علامة عليها لإعادة التنزيل. راجع نقل الملفات التي تم تنزيلها لمزيد من التفاصيل.
يمكنك الاستعلام عن تقدم التنزيل الحالي في محطة منفصلة
dx-download-agent progress exome_bams_manifest.json.bz2
وستحصل على ملخص موجز لحالة التنزيلات:
21.6 MB/sec 1184/27078 MB 18/327 Parts Downloaded and written to disk
للتحقق من سلامة الملفات التي تم تنزيلها، يمكنك تشغيل
dx-download-agent inspect exome_bams_manifest.json.bz2
سيقوم هذا الأمر بإجراء فحص للملفات والتأكد من تطابق مجموع MD5sums الخاص بها مع البيان. إذا كان الملف مفقودًا أو لم يتطابق MD5sum، فسيقوم وكيل التنزيل بالإبلاغ عن الملفات المتأثرة ويمكنك بعد ذلك تشغيل dx-download-agent download مرة أخرى لإعادة تنزيل الملفات المتأثرة.
-num_threads (عدد صحيح): الحد الأقصى لعدد سلاسل الرسائل المتزامنة لاستخدامها عند تنزيل الملفات أو فحصها
على سبيل المثال، الأمر
dx-download-agent download -num_threads=20 exome_bams_manifest.json.bz2
سيقوم بإنشاء مجموعة عاملة مكونة من 20 موضوعًا والتي ستقوم بتنزيل أجزاء من الملفات بالتوازي. سيقوم 20 عاملاً كحد أقصى بإجراء التنزيلات في أي وقت. يمكن التحكم في تحديد معدل التنزيلات إلى حد ما عن طريق تغيير هذا العدد.
يتم الاحتفاظ بالمعلومات حول الأجزاء التي تم تنزيلها في ملف قاعدة بيانات sqlite3 الذي يحتوي على معلومات مشابهة لما هو موجود في تنسيق ملف JSON بالإضافة إلى حقل bytes_fetched الإضافي.
اسم الجدول: manifest_stats
الحقول (جميع الحقول عبارة عن سلاسل ما لم ينص على خلاف ذلك)
file_id : معرف الملف لجزء الملف
project : معرف المشروع لجزء الملف
name : اسم الملف
folder : مجلد يحتوي على ملف على DNAnexus
part_id (عدد صحيح): معرف الجزء للملف
md5 : md5sum لمعرف الجزء
size (عدد صحيح): حجم الجزء
block_size (عدد صحيح): حجم الكتلة الأساسي للملف (يفترض أنه يساوي size باستثناء الجزء الأخير)
bytes_fetched (عدد صحيح <= size ): إجمالي عدد البايتات التي تم تنزيلها
الأمر متروك للتنفيذ لتحديد ما إذا كان سيتم تحديث bytes_fetched بطريقة أكثر خشونة أم لا. على سبيل المثال، لا يمكن تحديث bytes_fetched إلا عند اكتمال تنزيل الجزء. في هذه الحالة، ستكون قيمها 0 فقط أو قيمة size .
يتضمن البيان أربعة حقول لكل ملف: file_id و project و name و parts . إذا تم تحديد الأربعة جميعها، فمن المفترض أن يكون الملف مباشرًا ومغلقًا، مما يجعله متاحًا للتنزيل. إذا تم حذف حقل parts ، فسيتم وصف الملف على المنصة. يتم استخدام الوصف المجمع للقيام بذلك بكفاءة للعديد من الملفات دفعة واحدة. لا يمكن تنزيل الملفات التي تم أرشفتها أو التي لم يتم إغلاقها، وسيؤدي ذلك إلى حدوث خطأ.
من الممكن تحميل روابط DNAx الرمزية التي لا تحتوي على أجزاء. الحقول المطلوبة للروابط الرمزية هي file_id ، و project ، و name . لاحظ أن الرابط الرمزي يحتوي على المجموع الاختباري الشامل لـ MD5، والذي يتم التحقق منه في نهاية التنزيل.
بصرف النظر عن برنامج Go الثنائي القائم بذاته، فإننا نقدم أيضًا إصدار Dockerized. يمكن استخدامه بطريقة مشابهة جدًا كبرنامج مستقل قابل للتنفيذ باستثناء الضرورة لتركيب المجلد المحلي الخاص بك وتوفير رمز DX API المميز الخاص بك.
حاليًا، نقدم علامات الصور التالية:
latest - أحدث بناء للفرع الرئيسي
0.5.11 , 0.5.12 , ... - علامات مخصصة لكل إصدار (بدءًا من 0.5.11)
مثال على الاستخدام:
$ docker run -v $PWD:/workdir -w /workdir -e DX_API_TOKEN=$DX_API_TOKEN dnanexus/dxda:latest download -max_threads=20 manifest.json.bz2
أين:
$PWD هو مسار إلى الدليل الموجود على جهاز الكمبيوتر الخاص بك لتنزيل الملفات إليه
DX_API_TOKEN هو رمز مميز للوصول إلى نظامنا الأساسي (راجع البداية السريعة)
لتوجيه dx-download-agent إلى وكيل، يرجى تعيين متغير البيئة HTTP_PROXY على شيء مثل export HTTP_PROXY=hostname:port . HTTPS_PROXY مدعوم أيضًا.
افتراضيًا، يستخدم dx-download-agent الشهادات المثبتة على النظام لإنشاء اتصالات آمنة. إذا كان نظامك يتطلب شهادة TLS إضافية ولا يبدو أن dx-download-agent يستخدم شهادة مثبتة على نظامك، فهناك خياران حسب ترتيب التفضيل. أولاً، قم بتعيين متغير البيئة DX_TLS_CERTIFICATE_FILE على مسار ملف شهادة TLS المشفر بـ PEM والمطلوب من قبل مؤسستك الأم. كملاذ أخير، يمكنك الاتصال بشكل غير آمن عن طريق تجنب التحقق من الشهادة معًا عن طريق تعيين DX_TLS_SKIP_VERIFY=true . استخدم هذا لأغراض الاختبار فقط.
للراحة، يعد الملف create_manifest.py الموجود في الدليل scripts/ إحدى الطرق لإنشاء ملفات البيان لوكيل التنزيل. يتطلب هذا البرنامج النصي تثبيت مجموعة أدوات dx على نظامك وتسجيل دخولك إلى منصة DNAnexus. مثال على كيفية استخدامه:
python3 create_manifest.py "Project:/Folder" --recursive --output_file "myfiles.manifest.json.bz2"
هنا، يتم إنشاء بيان لجميع الملفات بشكل متكرر تحت اسم المشروع Project وفي المجلد Folder .
يمكن تصفية البيان لاحقًا باستخدام البرنامج النصي filter_manifest.py . على سبيل المثال، إذا كنت تريد التقاط الملفات في مجلد معين (على سبيل المثال Folder ) مع testcall بداخلها (على سبيل المثال /Folder/ALL.chr22._testcall_20190222.genotypes.vcf.gz )، فيمكنك تشغيل الأمر:
$ python3 filter_manifest.pymanifest.json.bz2 '^/Folder.*testcall.*'
حيث تكون الوسيطة الثانية المعطاة للبرنامج النصي عبارة عن تعبير عادي على المسار بأكمله (المجلد + اسم الملف).
في بعض الحالات، قد يكون من المرغوب فيه تقسيم بيان التنزيل إلى ملفات بيان متعددة لأغراض الاختبار أو لإدارة التنزيلات المتعددة لمجموعة بيانات كاملة عبر بيئات مختلفة. لتقسيم الملف، نقدم أداة Python بسيطة لا تتطلب حزمًا إضافية في الدليل scripts/ . على سبيل المثال، تنفيذ الأمر:
python3 scripts/split_manifest.py manifest.json.bz2 -n 100
سيتم إنشاء ملفات بيان تحتوي كل منها على 100 ملف لكل مشروع. على سبيل المثال، إذا كان هناك 300 ملف إجمالي في البيان.json.bz2، فإن مخرجات هذا الأمر ستنشئ ثلاثة ملفات مسماة: manifest_001.json.bz2 و manifest_002.json.bz2 و manifest_003.json.bz2 . يمكن استخدام كل ملف من هذه الملفات بشكل مستقل مع وكيل التنزيل.
يمكن استخدام هذا المستودع مباشرةً كوحدة Go أيضًا. في الدليل cmd/dx-download-agent ، يعد ملف dx-download-agent.go مثالاً لكيفية استخدامه.
لتطوير المصدر وتجربته داخل بيئة Docker المعزولة، قد يكون ملف Dockerfile الموجود في هذا المستودع بداية جيدة.
بعد التنزيل بنجاح (وفحص ما بعد التنزيل بشكل اختياري)، يجب أن يكون من الآمن نقل الملفات إلى الموقع المطلوب.
تحذير: بشكل عام، ننصح بعدم نقل الملفات أثناء عملية التنزيل ولكن قد يكون نقلها آمنًا في بعض الحالات الخاصة. يعمل وكيل التنزيل من خلال الاحتفاظ بقاعدة بيانات خفيفة الوزن لأجزاء الملفات التي تم تنزيلها والتي لم يتم تنزيلها، وهذا هو ما تعمل في المقام الأول خارج. وهذا يعني أنه حتى إذا قمت بنقل الملفات، فلن يدرك وكيل التنزيل ذلك حتى تقوم بتشغيل أمر inspect الفرعي الذي يقوم بإجراء فحوصات ما بعد التنزيل للتأكد من سلامة الملف على القرص. سيلاحظ أمر الفحص أن الملفات مفقودة، ويقوم بتحديث قاعدة البيانات، وعندما تعيد إصدار أمر التنزيل، حاول تنزيلها مرة أخرى. ولذلك، إذا قمت بنقل الملفات المكتملة ولم تقم بتشغيل الأمر الفرعي للفحص، فيجب أن يستمر وكيل التنزيل من حيث توقف. ومع ذلك، هناك خطر في نقل الملفات إذا لم يكتمل تنزيل الملف بعد. في هذه الحالة ستكون قد قمت بنقل ملف غير مكتمل.
يمكن تنزيل كائنات ملف الفئة فقط.
