البرنامج التعليمي: استخدام sdutil لتحميل البيانات في Seismic Store

مقالة
02/02/2024

Seismic Store هو حل قائم على السحابة لتخزين مجموعات البيانات وإدارتها من أي حجم. يوفر طريقة آمنة للوصول إلى مجموعات البيانات من خلال آلية تخويل محددة النطاق. يتغلب Seismic Store على قيود حجم عناصر موفري السحابة من خلال إدارة مجموعات البيانات العامة ككائنات مستقلة متعددة.

Sdutil هي أداة Python سطر الأوامر للتفاعل مع Seismic Store. يمكنك استخدام sdutil لتنفيذ العمليات الأساسية مثل تحميل البيانات إلى Seismic Store وتنزيل مجموعات البيانات من Seismic Store وإدارة المستخدمين وإدراج محتويات المجلد.

في هذا البرنامج التعليمي، تتعلم كيفية:

إعداد وتشغيل أداة sdutil.
احصل على URI لمتجر Seismic.
إنشاء مشروع فرعي.
تسجيل مستخدم.
استخدم sdutil لإدارة مجموعات البيانات باستخدام Seismic Store.
قم بإجراء الاختبارات للتحقق من صحة وظائف أداة sdutil.

المتطلبات الأساسية

قم بتثبيت المتطلبات الأساسية التالية استنادا إلى نظام التشغيل الخاص بك.

Windows:

Linux:

64 بت Python 3.8.3

Unix/Mac

يتطلب Sdutil وحدات نمطية أخرى ملاحظا في requirements.txt. يمكنك إما تثبيت الوحدات كما هي أو تثبيتها في بيئة ظاهرية للحفاظ على المضيف نظيفا من تعارضات الحزمة. إذا كنت لا تريد تثبيتها في بيئة ظاهرية، فتخط أوامر البيئة الظاهرية الأربعة في التعليمات البرمجية التالية. بالإضافة إلى ذلك، إذا كنت تستخدم Mac بدلا من Ubuntu أو WSL - Ubuntu 20.04، فاستخدم homebrew بدلا من apt-get مدير الحزمة، أو قم بتثبيت apt-getيدويا .

  # Check if virtualenv is already installed
  virtualenv --version

  # If not, install it via pip or apt-get
  pip install virtualenv
  # or sudo apt-get install python3-venv for WSL

  # Create a virtual environment for sdutil
  virtualenv sdutilenv
  # or python3 -m venv sdutilenv for WSL

  # Activate the virtual environment
  Windows:    sdutilenv/Scripts/activate  
  Linux:      source sdutilenv/bin/activate

تثبيت التبعيات المطلوبة:

  # Run this from the extracted sdutil folder
  pip install -r requirements.txt

الاستخدام

التكوين

انسخ مستودع sdutil من فرع المجتمع azure-stable وافتحه في المحرر المفضل لديك.

استبدل محتويات config.yaml في sdlib المجلد ب YAML التالي. املأ القيم الثلاث ذات القوالب (مثيلان ومثيل <meds-instance-url> واحد من <put refresh token here...>).

seistore:
  service: '{"azure": {"azureGlabEnv":{"url": "https://<meds-instance-url>/seistore-svc/api/v3", "appkey": ""}}}'
  url: 'https://<meds-instance-url>/seistore-svc/api/v3'
  cloud_provider: 'azure'
  env: 'glab'
  auth-mode: 'JWT Token'
  ssl_verify: False
auth_provider:
  azure: '{
        "provider": "azure",
        "authorize_url": "https://login.microsoftonline.com/",
        "oauth_token_host_end": "/oauth2/token",
        "scope_end":"/.default openid profile offline_access",
        "redirect_uri":"http://localhost:8080",
        "login_grant_type": "refresh_token",
        "refresh_token": "<put refresh token here from auth_token.http authorize request>"
        }'
azure:
  empty: 'none'

إشعار

إذا لم يكن الرمز المميز موجودا بالفعل، فاحصل على واحد باتباع التوجيهات في كيفية إنشاء رمز المصادقة المميز.

تصدير متغيرات البيئة التالية أو تعيينها:

  export AZURE_TENANT_ID=<your-tenant-id>
  export AZURE_CLIENT_ID=<your-client-id>
  export AZURE_CLIENT_SECRET=<your-client-secret>

تشغيل الأداة

تشغيل أداة sdutil من مجلد الأداة المساعدة المستخرجة:

  python sdutil

إذا لم تحدد أي وسيطات، فستظهر هذه القائمة:

  Seismic Store Utility

  > python sdutil [command]

  available commands:

  * auth    : authentication utilities
  * unlock  : remove a lock on a seismic store dataset
  * version : print the sdutil version
  * rm      : delete a subproject or a space separated list of datasets
  * mv      : move a dataset in seismic store
  * config  : manage the utility configuration
  * mk      : create a subproject resource
  * cp      : copy data to(upload)/from(download)/in(copy) seismic store
  * stat    : print information like size, creation date, legal tag(admin) for a space separated list of tenants, subprojects or datasets
  * patch   : patch a seismic store subproject or dataset
  * app     : application authorization utilities
  * ls      : list subprojects and datasets
  * user    : user authorization utilities

إذا كانت هذه هي المرة الأولى التي تستخدم فيها الأداة، فقم sdutil config init بتشغيل الأمر لتهيئة التكوين:
```
  python sdutil config init
```
قبل البدء في استخدام الأداة وتنفيذ أي عمليات، يجب عليك تسجيل الدخول إلى النظام. عند تشغيل الأمر التالي، يفتح sdutil صفحة تسجيل الدخول في مستعرض ويب:
```
  python sdutil auth login
```
بعد تسجيل الدخول بنجاح، تكون بيانات الاعتماد صالحة لمدة أسبوع. لا تحتاج إلى تسجيل الدخول مرة أخرى ما لم تنتهي صلاحية بيانات الاعتماد.

إشعار

إذا لم تكن تتلقى الرسالة حول تسجيل الدخول الناجح، فتأكد من تعيين متغيرات البيئة الثلاثة وأنك اتبعت جميع الخطوات في قسم التكوين في وقت سابق من هذا البرنامج التعليمي.

موارد Seismic Store

قبل البدء في استخدام النظام، من المهم فهم كيفية إدارة Seismic Store للموارد. يدير Seismic Store ثلاثة أنواع من الموارد:

مشروع المستأجر: المشروع الرئيسي. المستأجر هو القسم الأول من مسار Seismic Store.
المشروع الفرعي: المشروع الفرعي العامل، المرتبط مباشرة ضمن مشروع المستأجر الرئيسي. المشروع الفرعي هو القسم الثاني من مسار Seismic Store.
مجموعة البيانات: كيان مجموعة البيانات. مجموعة البيانات هي القسم الثالث والأخير من مسار Seismic Store. يمكنك تحديد مورد مجموعة البيانات باستخدام النموذج path/dataset_name. في هذا النموذج، path هو اختياري وله نفس معنى الدليل في نظام ملفات عام. الجزء dataset_name هو اسم كيان مجموعة البيانات.

Seismic Store URI هو سلسلة تستخدمها لمعالجة مورد في النظام بشكل فريد. يمكنك الحصول عليه عن طريق إلحاق البادئة sd:// بمسار المورد المطلوب:

  sd://<tenant>/<subproject>/<path>*/<dataset>

على سبيل المثال، إذا كان لديك مجموعة results.segy بيانات مخزنة في qadata/ustest بنية الدليل في carbon المشروع الفرعي ضمن gtc مشروع المستأجر، فإن التعليمات البرمجية المقابلة sdpath هي:

  sd://gtc/carbon/qadata/ustest/results.segy

يمكنك معالجة كل مورد باستخدام القسم المقابل sdpath :

  Tenant: sd://gtc
  Subproject: sd://gtc/carbon
  Dataset: sd://gtc/carbon/qadata/ustest/results.segy

المشاريع الفرعية

المشروع الفرعي في Seismic Store هو وحدة عمل حيث يمكن للمستخدم حفظ مجموعات البيانات. يمكن للنظام معالجة مشاريع فرعية متعددة ضمن مشروع مستأجر.

يمكن فقط لمسؤول المستأجر إنشاء مورد مشروع فرعي باستخدام الأمر sdutil التالي:

  > python sdutil mk *sdpath *admin@email *legaltag (options)

    create a new subproject resource in Seismic Store. user can interactively
    set the storage class for the subproject. only tenant admins are allowed to create subprojects.

    *sdpath       : the seismic store subproject path. sd://<tenant>/<subproject>
    *admin@email  : the email of the user to be set as the subproject admin
    *legaltag     : the default legal tag for the created subproject

    (options)     | --idtoken=<token> pass the credential token to use, rather than generating a new one

إدارة المستخدمين

لكي تتمكن من استخدام Seismic Store، يجب تسجيل المستخدمين في مورد مشروع فرعي على الأقل مع دور يحدد مستوى الوصول الخاص بهم. يدعم متجر Seismic دورين محددين على مستوى المشروع الفرعي:

مسؤول: الوصول للقراءة/الكتابة وإدارة المستخدم.
العارض: الوصول للقراءة/القائمة.

يمكن لمسؤول المشروع الفرعي فقط تسجيل مستخدم باستخدام الأمر sdutil التالي:

  > python sdutil user [ *add | *list | *remove | *roles ] (options)

    *add       $ python sdutil user add [user@email] [sdpath] [role]*
                add a user to a subproject resource

                [user@email]  : email of the user to add
                [sdpath]      : seismic store subproject path, sd://<tenant>/<subproject>
                [role]        : user role [admin|viewer]

أمثلة الاستخدام

التعليمات البرمجية التالية هي مثال على كيفية استخدام sdutil لإدارة مجموعات البيانات باستخدام Seismic Store. يستخدم sd://gtc/carbon هذا المثال كمورد مشروع فرعي.

  # Create a new file
  echo "My Test Data" > data1.txt

  # Upload the created file to Seismic Store
  ./sdutil cp data1.txt sd://gtc/carbon/test/mydata/data.txt

  # List the contents of the Seismic Store subproject
  ./sdutil ls sd://gtc/carbon/test/mydata/  (display: data.txt)
  ./sdutil ls sd://gtc                      (display: carbon)
  ./sdutil ls sd://gtc/carbon               (display: test/)
  ./sdutil ls sd://gtc/carbon/test          (display: data/)

  # Download the file from Seismic Store
  ./sdutil cp sd://gtc/carbon/test/mydata/data.txt data2.txt

  # Check if the original file matches the one downloaded from Seismic Store
  diff data1.txt data2.txt

اختبار الأداة

يحتوي مجلد الاختبار على مجموعة من اختبارات التكامل/الوحدة والانحدار المكتوبة ل pytest. قم بإجراء هذه الاختبارات للتحقق من صحة وظائف أداة sdutil.

استخدم هذه التعليمة البرمجية للمتطلبات:

  # Install required dependencies  
  pip install -r test/e2e/requirements.txt

استخدم هذه التعليمة البرمجية لاختبارات التكامل/الوحدة:

  # Run integral/unit test
  ./devops/scripts/run_unit_tests.sh

  # Test execution parameters
  --mnt-volume = sdapi root dir (default=".")

استخدم هذه التعليمة البرمجية لاختبارات الانحدار:

  # Run regression test
  ./devops/scripts/run_regression_tests.sh --cloud-provider= --service-url= --service-key= --idtoken= --tenant= --subproject=

  # Test execution parameters
  --mnt-volume = sdapi root dir (default=".")
  --disable-ssl-verify (to disable ssl verification)

الأسئلة المتداولة

كيف يمكنني إنشاء أمر جديد للأداة؟

قم بتشغيل البرنامج النصي لإنشاء الأوامر (./command_gen.py) لإنشاء البنية الأساسية تلقائيا لدمج أمر جديد في أداة sdutil. يقوم البرنامج النصي بإنشاء مجلد مع البنية الأساسية للأمر في sdlib/cmd/new_command_name.

  ./scripts/command_gen.py new_command_name

كيف يمكنني حذف كافة الملفات في دليل؟

استخدم التعليمات البرمجية التالية:

  ./sdutil ls -lr sd://tenant/subproject/your/folder/here | xargs -r ./sdutil rm --idtoken=x.xxx.x

كيف يمكنني إنشاء سجل التغيير الخاص بالأداة؟

تشغيل البرنامج النصي changelog (./changelog-generator.sh) لإنشاء سجل تغيير الأداة تلقائيا:

  ./scripts/changelog-generator.sh

استخدام Azure Data Manager for Energy

يستخدم Azure Data Manager لمثيل الطاقة إصدار OSDU® M12 من sdutil. أكمل الخطوات التالية إذا كنت تريد استخدام sdutil للاستفادة من واجهة برمجة تطبيقات نظام إدارة البيانات العلمية (SDMS) من Azure Data Manager لمثيل الطاقة:

تأكد من اتباع خطوات التثبيت والتكوين السابقة. تتضمن هذه الخطوات تنزيل التعليمات البرمجية المصدر sdutil وتكوين بيئة Python الظاهرية وتحرير config.yaml الملف وتعيين متغيرات البيئة الثلاثة.

قم بتشغيل الأوامر التالية لتنفيذ المهام في Seismic Store.

تهيئه:

  (sdutilenv) > python sdutil config init
  [one] Azure
  Select the cloud provider: **enter 1**
  Insert the Azure (azureGlabEnv) application key: **just press enter--no need to provide a key**

  sdutil successfully configured to use Azure (azureGlabEnv)

  Should display sign in success message. Credentials expiry set to 1 hour.

تسجيل الدخول:

  python sdutil config init
  python sdutil auth login

سرد الملفات في Seismic Store:

  python sdutil ls sd://<tenant> # For example, sd://<instance-name>-<datapartition>
  python sdutil ls sd://<tenant>/<subproject> # For example, sd://<instance-name>-<datapartition>/test

تحميل ملف من جهازك المحلي إلى Seismic Store:

  python sdutil cp local-dir/file-name-at-source.txt sd://<datapartition>/test/file-name-at-destination.txt

قم بتنزيل ملف من Seismic Store إلى جهازك المحلي:
```
  python sdutil cp sd://<datapartition>/test/file-name-at-ddms.txt local-dir/file-name-at-destination.txt
```
إشعار

لا تستخدم cp الأمر لتنزيل ملفات VDS. ينتج عن تحويل VDS ملفات متعددة، لذلك cp لن يتمكن الأمر من تنزيلها جميعا في أمر واحد. استخدم أداة SEGYExport أو VDSCopy بدلا من ذلك. تستخدم هذه الأدوات سلسلة من استدعاءات REST التي تصل إلى نظام تسمية لاسترداد معلومات حول جميع ملفات VDS الناتجة.

OSDU® هي علامة تجارية للمجموعة المفتوحة.

الخطوة التالية

تقدم إلى البرنامج التعليمي الآتي:

البرنامج التعليمي: العمل مع سجلات بيانات جيدة باستخدام واجهات برمجة تطبيقات DDMS للتسليم الجيد

Share via