Kurz: Použití nástroje sdutil k načtení dat do Seismic Storu

Seismic Store je cloudové řešení pro ukládání a správu datových sad libovolné velikosti. Poskytuje bezpečný způsob přístupu k datovým sadám prostřednictvím mechanismu autorizace s vymezeným oborem. Seismic Store překonat omezení velikosti objektů poskytovatelů cloudu tím, že spravuje obecné datové sady jako více nezávislých objektů.

Sdutil je nástroj pythonu příkazového řádku pro interakci se Seismic Storem. Nástroj sdutil můžete použít k provádění základních operací, jako je nahrávání dat do Seismic Storu, stahování datových sad ze Seismic Storu, správa uživatelů a výpis obsahu složek.

V tomto kurzu se naučíte:

• Nastavte a spusťte nástroj sdutil.
• Získejte identifikátor URI úložiště Seismic.
• Vytvořte dílčí projekt.
• Zaregistrujte uživatele.
• Použití nástroje sdutil ke správě datových sad pomocí Seismic Storu.
• Spuštěním testů ověřte funkce nástroje sdutil.

Požadavky

Na základě operačního systému nainstalujte následující požadavky.

Windows:

• 64bitová verze Pythonu 3.8.3
• Nástroje sestavení Microsoft C++
• Linux Subsystem Ubuntu

Linux:

• 64bitová verze Pythonu 3.8.3

Unix/Mac

• 64bitová verze Pythonu 3.8.3
• Nástroje sestavení Apple Xcode C++

Sdutil vyžaduje další moduly uvedené v requirements.txt. Moduly můžete nainstalovat tak, jak jsou, nebo je nainstalovat do virtuálního prostředí, aby byl hostitel čistý před konflikty balíčků. Pokud je nechcete instalovat do virtuálního prostředí, přeskočte čtyři příkazy virtuálního prostředí v následujícím kódu. Pokud navíc používáte Mac místo Ubuntu nebo WSL - Ubuntu 20.04, použijte homebrew apt-get místo správce balíčků nebo ručně nainstalujte 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

Instalace požadovaných závislostí:

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

Využití

Konfigurace

1. Naklonujte úložiště sdutil z větve komunity azure-stable a otevřete ho ve svém oblíbeném editoru.

2. config.yaml Obsah složky sdlib nahraďte následujícím kódem YAML. Vyplňte tři šablonované hodnoty (dvě instance <meds-instance-url> a jednu instanci <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'
   

   Poznámka:

   Pokud token ještě není k dispozici, získejte ho podle pokynů v části Jak vygenerovat ověřovací token.

3. Exportujte nebo nastavte následující proměnné prostředí:

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

Spuštění nástroje

1. Spusťte nástroj sdutil ze složky extrahovaného nástroje:

     python sdutil
   

   Pokud nezadáte žádné argumenty, zobrazí se tato nabídka:

     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. Pokud nástroj používáte poprvé, spusťte sdutil config init příkaz pro inicializaci konfigurace:

     python sdutil config init
   

3. Než začnete nástroj používat a provedete jakékoli operace, musíte se přihlásit k systému. Když spustíte následující příkaz, nástroj sdutil otevře přihlašovací stránku ve webovém prohlížeči:

     python sdutil auth login
   

   Po úspěšném přihlášení jsou vaše přihlašovací údaje platné po dobu týdne. Pokud nevyprší platnost přihlašovacích údajů, nemusíte se znovu přihlašovat.

   Poznámka:

   Pokud se vám nezobrazuje zpráva o úspěšném přihlášení, ujistěte se, že jsou nastavené tři proměnné prostředí a že jste postupovali podle všech kroků v části Konfigurace dříve v tomto kurzu.

Seismic Store – prostředky

Než začnete používat systém, je důležité pochopit, jak Seismic Store spravuje prostředky. Seismic Store spravuje tři typy prostředků:

• Projekt tenanta: Hlavní projekt. Tenant je první část cesty k Seismic Storu.
• Dílčí projekt: Pracovní dílčí projekt, který je přímo propojený v rámci hlavního projektu tenanta. Dílčí projekt je druhou částí cesty Seismic Store.
• Datová sada: Entita datové sady. Datová sada je třetí a poslední částí cesty Seismic Store. Prostředek datové sady můžete zadat pomocí formuláře path/dataset_name. V této podobě path je nepovinný a má stejný význam jako adresář v obecném systému souborů. Součástí dataset_name je název entity datové sady.

Identifikátor URI úložiště Seismic je řetězec, který použijete k jedinečné adrese prostředku v systému. Můžete ho získat připojením předpony sd:// k požadované cestě prostředku:

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

Pokud máte například datovou sadu uloženou results.segy v qadata/ustest adresářové struktuře v dílčím carbon projektu v gtc projektu tenanta, odpovídající sdpath kód je:

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

Každý prostředek můžete vyřešit pomocí odpovídajícího sdpath oddílu:

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

Dílčích projektů

Dílčí projekt v Seismic Storu je pracovní jednotka, ve které může uživatel ukládat datové sady. Systém může zpracovávat více dílčích projektů v rámci projektu tenanta.

Pomocí následujícího příkazu sdutil může vytvořit pouze správce tenanta prostředek dílčího projektu:

  > 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

Správa uživatelů

Aby uživatelé mohli používat Seismic Store, musí být zaregistrovaní alespoň k dílčímu prostředku projektu s rolí, která definuje jejich úroveň přístupu. Úložiště Seismic podporuje dvě role vymezené na úrovni dílčího projektu:

• Správa: Přístup pro čtení a zápis a správu uživatelů.
• Prohlížeč: Přístup pro čtení a seznam

Pomocí následujícího příkazu sdutil může uživatele zaregistrovat pouze správce dílčích projektů:

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

Příklady použití

Následující kód je příkladem použití nástroje sdutil ke správě datových sad pomocí Seismic Storu. Tento příklad se používá sd://gtc/carbon jako zdroj dílčího projektu.

  # 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

Testování nástrojů

Složka testu obsahuje sadu integrálních/jednotek a regresních testů napsaných pro pytest. Spuštěním těchto testů ověřte funkce nástroje sdutil.

Tento kód použijte pro požadavky:

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

Tento kód použijte pro celočíselné testy/testy jednotek:

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

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

Tento kód použijte pro regresní testy:

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

Často kladené dotazy

Jak můžu pro nástroj vygenerovat nový příkaz?

Spuštěním skriptu generování příkazů (./command_gen.py) automaticky vygenerujte základní infrastrukturu pro integraci nového příkazu v nástroji sdutil. Skript vytvoří složku s infrastrukturou příkazů v sdlib/cmd/new_command_name.

  ./scripts/command_gen.py new_command_name

Jak můžu odstranit všechny soubory v adresáři?

Použijte následující kód:

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

Jak můžu vygenerovat protokol změn nástroje?

Spuštěním skriptu protokolu změn (./changelog-generator.sh) automaticky vygenerujte protokol změn nástroje:

  ./scripts/changelog-generator.sh

Využití azure Data Manageru pro energii

Instance Azure Data Manageru pro energii používá verzi nástroje sdutil M12 OSDU®. Pokud chcete použít nástroj sdutil k využití rozhraní API SDMS (Scientific Správa dat System) vaší instance Azure Data Manageru pro energii, proveďte následující kroky:

1. Ujistěte se, že jste postupovali podle předchozích kroků instalace a konfigurace . Mezi tyto kroky patří stažení zdrojového kódu nástroje sdutil, konfigurace virtuálního prostředí Pythonu, úprava config.yaml souboru a nastavení tří proměnných prostředí.

2. Spuštěním následujícíchpříkazůch

   • Inicializovat:

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

   • Přihlásit se:

       python sdutil config init
       python sdutil auth login
     

   • Výpis souborů v Seismic Storu:

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

   • Nahrajte soubor z místního počítače do Seismic Storu:

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

   • Stáhněte si soubor ze Seismic Storu do místního počítače:

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

     Poznámka:

     K stahování souborů VDS nepoužívejte cp tento příkaz. Výsledkem převodu VDS je více souborů, takže cp příkaz nebude moct stáhnout všechny soubory v jednom příkazu. Místo toho použijte nástroj SEGYExport nebo VDSCopy. Tyto nástroje používají řadu volání REST, která přistupují k schématu pojmenování a načítají informace o všech výsledných souborech VDS.

OSDU® je ochranná známka the Open Group.

Další krok

Přejděte k dalšímu kurzu:

Kurz: Práce s datovými záznamy s využitím rozhraní API Well Delivery DDMS