Samouczek: ładowanie danych do magazynu seismic za pomocą narzędzia sdutil

Magazyn seismic to oparte na chmurze rozwiązanie do przechowywania zestawów danych o dowolnym rozmiarze i zarządzania nimi. Zapewnia bezpieczny sposób uzyskiwania dostępu do zestawów danych za pomocą mechanizmu autoryzacji w zakresie. Magazyn seismic pozwala wyeliminować ograniczenia rozmiaru obiektów dostawców chmury, zarządzając ogólnymi zestawami danych jako wieloma niezależnymi obiektami.

Sdutil to narzędzie wiersza polecenia języka Python do interakcji z magazynem Seismic Store. Za pomocą narzędzia sdutil można wykonywać podstawowe operacje, takie jak przekazywanie danych do magazynu Seismic Store, pobieranie zestawów danych ze sklepu Seismic Store, zarządzanie użytkownikami i wyświetlanie zawartości folderu.

Z tego samouczka dowiesz się, jak wykonywać następujące czynności:

• Skonfiguruj i uruchom narzędzie sdutil.
• Uzyskaj identyfikator URI magazynu sejsmicznego.
• Utwórz podprojekt.
• Zarejestruj użytkownika.
• Użyj narzędzia sdutil do zarządzania zestawami danych za pomocą magazynu Seismic Store.
• Uruchom testy, aby zweryfikować funkcje narzędzia sdutil.

Wymagania wstępne

Zainstaluj następujące wymagania wstępne na podstawie systemu operacyjnego.

Windows:

• 64-bitowy język Python w wersji 3.8.3
• Microsoft C++ Build Tools
• Podsystem Linux Ubuntu

Linux:

• 64-bitowy język Python w wersji 3.8.3

Unix/Mac

• 64-bitowy język Python w wersji 3.8.3
• Apple Xcode C++ Build Tools

Sdutil wymaga innych modułów zanotowany w pliku requirements.txt. Możesz zainstalować moduły w taki sposób, jak to jest, lub zainstalować je w środowisku wirtualnym, aby zachować czysty host przed konfliktami pakietów. Jeśli nie chcesz ich instalować w środowisku wirtualnym, pomiń cztery polecenia środowiska wirtualnego w poniższym kodzie. Ponadto jeśli używasz komputerów Mac zamiast Ubuntu lub WSL — Ubuntu 20.04, użyj polecenia homebrew zamiast apt-get jako menedżera pakietów lub ręcznie zainstaluj program 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

Zainstaluj wymagane zależności:

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

Użycie

Konfigurowanie

1. Sklonuj repozytorium sdutil z gałęzi community azure-stable i otwórz je w ulubionym edytorze.

2. Zastąp zawartość config.yaml pliku w folderze sdlib następującym kodem YAML. Wypełnij trzy wartości templatized (dwa wystąpienia <meds-instance-url> i jedno wystąpienie <put refresh token here...>klasy ).

   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'
   

   Uwaga

   Jeśli token nie jest jeszcze obecny, uzyskaj go, postępując zgodnie z instrukcjami w temacie Jak wygenerować token uwierzytelniania.

3. Wyeksportuj lub ustaw następujące zmienne środowiskowe:

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

Uruchamianie narzędzia

1. Uruchom narzędzie sdutil z wyodrębnionego folderu narzędzia:

     python sdutil
   

   Jeśli nie określisz żadnych argumentów, zostanie wyświetlone następujące menu:

     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. Jeśli używasz narzędzia po raz pierwszy, uruchom sdutil config init polecenie , aby zainicjować konfigurację:

     python sdutil config init
   

3. Przed rozpoczęciem korzystania z narzędzia i wykonywania jakichkolwiek operacji należy zalogować się do systemu. Po uruchomieniu następującego polecenia sdutil otwiera stronę logowania w przeglądarce internetowej:

     python sdutil auth login
   

   Po pomyślnym zalogowaniu poświadczenia są ważne przez tydzień. Nie musisz się ponownie logować, chyba że poświadczenia wygasają.

   Uwaga

   Jeśli nie otrzymujesz komunikatu o pomyślnym zalogowaniu, upewnij się, że ustawiono trzy zmienne środowiskowe i zostały wykonane wszystkie kroki opisane w sekcji Konfiguracja we wcześniejszej części tego samouczka.

Zasoby magazynu seismic

Przed rozpoczęciem korzystania z systemu ważne jest, aby zrozumieć, jak magazyn Seismic zarządza zasobami. Magazyn seismic zarządza trzema typami zasobów:

• Projekt dzierżawy: główny projekt. Dzierżawa jest pierwszą sekcją ścieżki sklepu Seismic Store.
• Podprojekt: podprojekt roboczy, który jest bezpośrednio połączony w głównym projekcie dzierżawy. Podprojekt jest drugą sekcją ścieżki Sklepu Seismic.
• Zestaw danych: jednostka zestawu danych. Zestaw danych jest trzecią i ostatnią sekcją ścieżki sklepu Seismic Store. Zasób zestawu danych można określić przy użyciu formularza path/dataset_name. W tym formularzu path jest opcjonalny i ma takie samo znaczenie jak katalog w ogólnym systemie plików. Część dataset_name jest nazwą jednostki zestawu danych.

Identyfikator URI magazynu seismic jest ciągiem używanym do unikatowego adresowania zasobu w systemie. Można go uzyskać, dołączając prefiks do wymaganej ścieżki sd:// zasobu:

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

Jeśli na przykład masz results.segy zestaw danych przechowywany w strukturze katalogów qadata/ustest w podprojektie carbon w projekcie gtc dzierżawy, odpowiedni sdpath kod to:

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

Każdy zasób można rozwiązać, korzystając z odpowiedniej sdpath sekcji:

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

Podprojekty

Podprojekt w magazynie seismic jest jednostką roboczą, w której użytkownik może zapisywać zestawy danych. System może obsługiwać wiele podprojektów w ramach projektu dzierżawy.

Tylko administrator dzierżawy może utworzyć zasób podprojektu przy użyciu następującego polecenia 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

Zarządzanie użytkownikami

Aby móc korzystać ze sklepu Seismic Store, użytkownicy muszą być zarejestrowani w co najmniej zasobie podprojektu z rolą, która definiuje ich poziom dostępu. Magazyn seismic obsługuje dwie role o określonym zakresie na poziomie podprojektu:

• Administracja: dostęp do odczytu/zapisu i zarządzanie użytkownikami.
• Osoba przeglądająca: dostęp do odczytu/listy.

Tylko administrator podprojektu może zarejestrować użytkownika przy użyciu następującego polecenia 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]

Przykłady użycia

Poniższy kod to przykład użycia narzędzia sdutil do zarządzania zestawami danych za pomocą magazynu Seismic Store. W tym przykładzie użyto sd://gtc/carbon jako zasobu podprojektu.

  # 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

Testowanie narzędzi

Folder testowy zawiera zestaw testów całkowitych/jednostkowych i regresji napisanych dla biblioteki pytest. Uruchom te testy, aby zweryfikować funkcje narzędzia sdutil.

Użyj tego kodu w celu spełnienia wymagań:

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

Użyj tego kodu do testów całkowitych/jednostkowych:

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

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

Użyj tego kodu do testów regresji:

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

Często zadawane pytania

Jak mogę wygenerować nowe polecenie dla narzędzia?

Uruchom skrypt generowania poleceń (./command_gen.py), aby automatycznie wygenerować infrastrukturę podstawową na potrzeby integracji nowego polecenia w narzędziu sdutil. Skrypt tworzy folder z infrastrukturą poleceń w programie sdlib/cmd/new_command_name.

  ./scripts/command_gen.py new_command_name

Jak usunąć wszystkie pliki w katalogu?

Użyj następującego kodu:

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

Jak mogę wygenerować dziennik zmian narzędzia?

Uruchom skrypt dziennika zmian (./changelog-generator.sh), aby automatycznie wygenerować dziennik zmian narzędzia:

  ./scripts/changelog-generator.sh

Użycie usługi Azure Data Manager for Energy

Wystąpienie usługi Azure Data Manager for Energy używa wersji OSDU® M12 sdutil. Wykonaj następujące kroki, jeśli chcesz użyć narzędzia sdutil, aby skorzystać z interfejsu API Scientific Zarządzanie danymi System (SDMS) wystąpienia usługi Azure Data Manager for Energy:

1. Upewnij się, że wykonano wcześniejsze kroki instalacji i konfiguracji . Te kroki obejmują pobieranie kodu źródłowego sdutil, konfigurowanie środowiska wirtualnego języka Python, edytowanie config.yaml pliku i ustawianie trzech zmiennych środowiskowych.

2. Uruchom następujące polecenia, aby wykonać zadania w magazynie seismic.

   • Zainicjować:

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

   • Rejestrowanie:

       python sdutil config init
       python sdutil auth login
     

   • Wyświetlanie listy plików w magazynie seismic:

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

   • Przekaż plik z komputera lokalnego do magazynu seismic:

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

   • Pobierz plik ze sklepu Seismic Store na komputer lokalny:

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

     Uwaga

     Nie używaj polecenia do pobierania cp plików VDS. Konwersja VDS powoduje wiele plików, więc cp polecenie nie będzie mogło pobrać wszystkich z nich w jednym poleceniu. Zamiast tego użyj narzędzia SEGYExport lub VDSCopy. Te narzędzia używają serii wywołań REST, które uzyskują dostęp do schematu nazewnictwa w celu pobrania informacji o wszystkich wynikowych plikach VDS.

OSDU® jest znakiem towarowym grupy Open.

Następny krok

Przejdź do następnego samouczka:

Samouczek: praca z rekordami danych przy użyciu interfejsów API usługi Well Delivery DDMS