Bagikan melalui

Tutorial: Menggunakan sdutil untuk memuat data ke Seismic Store

  • Artikel

Seismic Store adalah solusi berbasis cloud untuk menyimpan dan mengelola himpunan data dalam berbagai ukuran. Ini menyediakan cara yang aman untuk mengakses himpunan data melalui mekanisme otorisasi tercakup. Seismic Store mengatasi batasan ukuran objek penyedia cloud dengan mengelola himpunan data generik sebagai beberapa objek independen.

Sdutil adalah alat Python baris perintah untuk berinteraksi dengan Seismic Store. Anda dapat menggunakan sdutil untuk melakukan operasi dasar seperti mengunggah data ke Seismic Store, mengunduh himpunan data dari Seismic Store, mengelola pengguna, dan mencantumkan konten folder.

Dalam tutorial ini, Anda akan mempelajari cara:

  • Siapkan dan jalankan alat sdutil.
  • Dapatkan URI Seismic Store.
  • Buat subproyek.
  • Mendaftarkan pengguna.
  • Gunakan sdutil untuk mengelola himpunan data dengan Seismic Store.
  • Jalankan pengujian untuk memvalidasi fungsionalitas alat sdutil.

Prasyarat

Instal prasyarat berikut berdasarkan sistem operasi Anda.

Windows:

Linux:

Unix/Mac

Sdutil memerlukan modul lain yang dicatat dalam requirements.txt. Anda dapat menginstal modul apa adanya atau menginstalnya di lingkungan virtual untuk menjaga host Anda tetap bersih dari konflik paket. Jika Anda tidak ingin menginstalnya di lingkungan virtual, lewati empat perintah lingkungan virtual dalam kode berikut. Selain itu, jika Anda menggunakan Mac alih-alih Ubuntu atau WSL - Ubuntu 20.04, gunakan homebrew alih-alih apt-get sebagai manajer paket Anda, atau instal apt-getsecara manual .

  # 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

Instal dependensi yang diperlukan:

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

Penggunaan

Konfigurasi

  1. Kloning repositori sdutil dari cabang komunitas azure-stable dan buka di editor favorit Anda.

  2. Ganti konten config.yaml dalam sdlib folder dengan YAML berikut. Isi tiga nilai templat (dua instans dan satu instans <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'

    Catatan

    Jika token belum ada, dapatkan dengan mengikuti petunjuk dalam Cara menghasilkan token autentikasi.

  3. Ekspor atau atur variabel lingkungan berikut:

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

Menjalankan alat

  1. Jalankan alat sdutil dari folder utilitas yang diekstrak:

      python sdutil

    Jika Anda tidak menentukan argumen apa pun, menu ini akan muncul:

      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

  2. Jika ini pertama kalinya Anda menggunakan alat ini, jalankan sdutil config init perintah untuk menginisialisasi konfigurasi:

      python sdutil config init

  3. Sebelum mulai menggunakan alat dan melakukan operasi apa pun, Anda harus masuk ke sistem. Saat Anda menjalankan perintah berikut, sdutil membuka halaman masuk di browser web:

      python sdutil auth login

    Setelah berhasil masuk, kredensial Anda berlaku selama seminggu. Anda tidak perlu masuk lagi kecuali kredensial kedaluwarsa.

    Catatan

    Jika Anda tidak mendapatkan pesan tentang keberhasilan masuk, pastikan bahwa tiga variabel lingkungan Anda diatur dan Anda mengikuti semua langkah di bagian Konfigurasi sebelumnya dalam tutorial ini.

Sumber daya Seismic Store

Sebelum Anda mulai menggunakan sistem, penting untuk memahami bagaimana Seismic Store mengelola sumber daya. Seismic Store mengelola tiga jenis sumber daya:

  • Proyek penyewa: Proyek utama. Penyewa adalah bagian pertama dari jalur Seismic Store.
  • Subproyek: Subproyek yang berfungsi, yang langsung ditautkan di bawah proyek penyewa utama. Subproyek adalah bagian kedua dari jalur Seismic Store.
  • Himpunan data: Entitas himpunan data. Himpunan data adalah bagian ketiga dan terakhir dari jalur Seismic Store. Anda dapat menentukan sumber daya himpunan data dengan menggunakan formulir path/dataset_name. Dalam bentuk itu, path bersifat opsional dan memiliki arti yang sama dengan direktori dalam sistem file generik. Bagian dataset_name tersebut adalah nama entitas himpunan data.

URI Seismic Store adalah string yang Anda gunakan untuk mengatasi sumber daya secara unik dalam sistem. Anda dapat memperolehnya dengan menambahkan awalan sd:// ke jalur sumber daya yang diperlukan:

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

Misalnya, jika Anda memiliki himpunan data yang results.segy disimpan dalam qadata/ustest struktur direktori di carbon subproyek di bawah gtc proyek penyewa, kode yang sdpath sesuai adalah:

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

Anda dapat mengatasi setiap sumber daya dengan menggunakan bagian yang sdpath sesuai:

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

Subproyek

Subproyek di Seismic Store adalah unit kerja tempat pengguna dapat menyimpan himpunan data. Sistem dapat menangani beberapa subproyek di bawah proyek penyewa.

Hanya admin penyewa yang dapat membuat sumber daya subproyek dengan menggunakan perintah sdutil berikut:

  > 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

Pengelolaan pengguna

Agar dapat menggunakan Seismic Store, pengguna harus didaftarkan ke setidaknya sumber daya subproyek dengan peran yang menentukan tingkat akses mereka. Penyimpanan seismik mendukung dua peran yang tercakup pada tingkat subproyek:

  • Admin: Akses baca/tulis dan manajemen pengguna.
  • Penampil: Akses baca/daftar.

Hanya admin subproyek yang dapat mendaftarkan pengguna dengan menggunakan perintah sdutil berikut:

  > 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]

Contoh penggunaan

Kode berikut adalah contoh cara menggunakan sdutil untuk mengelola himpunan data dengan Seismic Store. Contoh ini menggunakan sd://gtc/carbon sebagai sumber daya subproyek.

  # 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

Pengujian alat

Folder pengujian berisi serangkaian tes integral/unit dan regresi yang ditulis untuk pytest. Jalankan pengujian ini untuk memvalidasi fungsionalitas alat sdutil.

Gunakan kode ini untuk persyaratan:

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

Gunakan kode ini untuk pengujian integral/unit:

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

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

Gunakan kode ini untuk pengujian regresi:

  # 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)

FAQ

Bagaimana cara membuat perintah baru untuk alat ini?

Jalankan skrip pembuatan perintah (./command_gen.py) untuk secara otomatis menghasilkan infrastruktur dasar untuk mengintegrasikan perintah baru di alat sdutil. Skrip membuat folder dengan infrastruktur perintah di sdlib/cmd/new_command_name.

  ./scripts/command_gen.py new_command_name

Bagaimana cara menghapus semua file dalam direktori?

Gunakan kode berikut:

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

Bagaimana cara menghasilkan changelog alat?

Jalankan skrip changelog (./changelog-generator.sh) untuk menghasilkan changelog alat secara otomatis:

  ./scripts/changelog-generator.sh

Penggunaan untuk Azure Data Manager for Energy

Instans Azure Data Manager for Energy menggunakan versi OSDU® M12 dari sdutil. Selesaikan langkah-langkah berikut jika Anda ingin menggunakan sdutil untuk memanfaatkan API Scientific Data Management System (SDMS) instans Azure Data Manager for Energy Anda:

  1. Pastikan Anda mengikuti langkah-langkah penginstalan dan konfigurasi sebelumnya. Langkah-langkah ini termasuk mengunduh kode sumber sdutil, mengonfigurasi lingkungan virtual Python Anda, mengedit config.yaml file, dan mengatur tiga variabel lingkungan Anda.

  2. Jalankan perintah berikut untuk melakukan tugas di Seismic Store.

    • Menginisialisasi:

        (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.

    • Masuk:

        python sdutil config init
  python sdutil auth login

    • Mencantumkan file di 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

    • Unggah file dari komputer lokal Anda ke Seismic Store:

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

    • Unduh file dari Seismic Store ke komputer lokal Anda:

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

      Catatan

      Jangan gunakan cp perintah untuk mengunduh file VDS. Konversi VDS menghasilkan beberapa file, sehingga cp perintah tidak akan dapat mengunduh semuanya dalam satu perintah. Gunakan alat SEGYExport atau VDSCopy sebagai gantinya. Alat-alat ini menggunakan serangkaian panggilan REST yang mengakses skema penamaan untuk mengambil informasi tentang semua file VDS yang dihasilkan.

OSDU® adalah merek dagang dari The Open Group.

Langkah selanjutnya

Melanjutkan ke tutorial berikutnya:

Tutorial: Bekerja dengan catatan data yang baik dengan menggunakan API DDMS Pengiriman Yang Baik