Esercitazione: Usare sdutil per caricare i dati nell'archivio Sismico

Seismic Store è una soluzione basata sul cloud per l'archiviazione e la gestione di set di dati di qualsiasi dimensione. Offre un modo sicuro per accedere ai set di dati tramite un meccanismo di autorizzazione con ambito. Seismic Store supera le limitazioni delle dimensioni degli oggetti dei provider di servizi cloud gestendo set di dati generici come più oggetti indipendenti.

Sdutil è uno strumento Python da riga di comando per interagire con Seismic Store. È possibile usare sdutil per eseguire operazioni di base, ad esempio il caricamento dei dati in Seismic Store, il download di set di dati da Seismic Store, la gestione degli utenti e la presentazione dei contenuti delle cartelle.

In questa esercitazione apprenderai a:

Prerequisiti

Installare i prerequisiti seguenti in base al sistema operativo.

Windows:

• Python a 64 bit 3.8.3
• Microsoft C++ Build Tools
• Sottosistema Linux Ubuntu

Linux:

• Python a 64 bit 3.8.3

Unix/Mac

• Python a 64 bit 3.8.3
• Strumenti di compilazione di Apple Xcode C++

Sdutil richiede altri moduli indicati in requirements.txt. È possibile installare i moduli così come sono o installarli in un ambiente virtuale per mantenere l'host pulito dai conflitti dei pacchetti. Se non si vuole installarli in un ambiente virtuale, ignorare i quattro comandi dell'ambiente virtuale nel codice seguente. Inoltre, se si usa Mac invece di Ubuntu o WSL - Ubuntu 20.04, usare homebrew anziché apt-get come gestione pacchetti o installare apt-getmanualmente .

  # 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

Installare le dipendenze necessarie:

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

Utilizzo

Impostazione

1. Clonare il repository sdutil dal ramo community azure-stable e aprire nell'editor preferito.

2. Sostituire il contenuto di config.yaml nella sdlib cartella con il codice YAML seguente. Compilare i tre valori templati (due istanze di <meds-instance-url> e un'istanza di <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'
   

   Nota

   Se un token non è già presente, ottenerlo seguendo le istruzioni riportate in Come generare il token di autenticazione.

3. Esportare o impostare le variabili di ambiente seguenti:

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

Esecuzione dello strumento

1. Eseguire lo strumento sdutil dalla cartella dell'utilità estratta:

     python sdutil
   

   Se non si specificano argomenti, viene visualizzato questo 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. Se è la prima volta che si usa lo strumento, eseguire il sdutil config init comando per inizializzare la configurazione:

     python sdutil config init
   

3. Prima di iniziare a usare lo strumento ed eseguire qualsiasi operazione, è necessario accedere al sistema. Quando si esegue il comando seguente, sdutil apre una pagina di accesso in un Web browser:

     python sdutil auth login
   

   Dopo l'accesso, le credenziali sono valide per una settimana. Non è necessario eseguire di nuovo l'accesso a meno che le credenziali scadano.

   Nota

   Se non viene visualizzato il messaggio relativo all'accesso riuscito, assicurarsi che le tre variabili di ambiente siano impostate e che siano stati eseguiti tutti i passaggi della sezione Configurazione più indietro in questa esercitazione.

Risorse dell'archivio sismico

Prima di iniziare a usare il sistema, è importante comprendere come Seismic Store gestisce le risorse. Seismic Store gestisce tre tipi di risorse:

• Progetto tenant: progetto principale. Il tenant è la prima sezione del percorso dell'archivio sismico.
• Sottoprogetto: sottoprogetto funzionante, collegato direttamente al progetto tenant principale. Il sottoprogetto è la seconda sezione del percorso dell'archivio sismico.
• Set di dati: entità del set di dati. Il set di dati è la terza e l'ultima sezione del percorso dell'archivio sismico. È possibile specificare la risorsa del set di dati usando il formato path/dataset_name. In questo formato, path è facoltativo e ha lo stesso significato di una directory in un file system generico. La dataset_name parte è il nome dell'entità del set di dati.

L'URI dell'archivio Seismic è una stringa usata per indirizzare in modo univoco una risorsa nel sistema. È possibile ottenerlo aggiungendo il prefisso sd:// al percorso della risorsa richiesto:

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

Ad esempio, se si dispone di un results.segy set di dati archiviato nella qadata/ustest struttura di directory nel sottoprogetto nel carbon gtc progetto tenant, il codice corrispondente sdpath è:

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

È possibile gestire ogni risorsa usando la sezione corrispondente sdpath :

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

Sottoprogetti

Un sottoprogetto in Seismic Store è un'unità di lavoro in cui un utente può salvare i set di dati. Il sistema può gestire più sottoprogetti in un progetto tenant.

Solo un amministratore tenant può creare una risorsa sottoprogetto usando il comando sdutil seguente:

  > 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

Gestione utente

Per poter usare Seismic Store, gli utenti devono essere registrati in almeno una risorsa sottoprogetto con un ruolo che definisce il livello di accesso. L'archivio sismico supporta due ruoli con ambito a livello di sottoprogetto:

• Amministrazione: accesso in lettura/scrittura e gestione degli utenti.
• Visualizzatore: accesso in lettura/elenco.

Solo un amministratore del sottoprogetto può registrare un utente usando il comando sdutil seguente:

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

Esempi di utilizzo

Il codice seguente è un esempio di come usare sdutil per gestire i set di dati con Seismic Store. In questo esempio viene sd://gtc/carbon utilizzata come risorsa del sottoprogetto.

  # 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

Test degli strumenti

La cartella test contiene un set di test integrali/unit e regressioni scritti per pytest. Eseguire questi test per convalidare le funzionalità dello strumento sdutil.

Usare questo codice per i requisiti:

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

Usare questo codice per gli unit test integrali/unit test:

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

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

Usare questo codice per i test di regressione:

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

Domande frequenti

Come è possibile generare un nuovo comando per lo strumento?

Eseguire lo script di generazione dei comandi (./command_gen.py) per generare automaticamente l'infrastruttura di base per l'integrazione di un nuovo comando nello strumento sdutil. Lo script crea una cartella con l'infrastruttura dei comandi in sdlib/cmd/new_command_name.

  ./scripts/command_gen.py new_command_name

Come è possibile eliminare tutti i file in una directory?

Usare il codice seguente:

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

Come è possibile generare il log delle modifiche dello strumento?

Eseguire lo script del log delle modifiche (./changelog-generator.sh) per generare automaticamente il log delle modifiche dello strumento:

  ./scripts/changelog-generator.sh

Utilizzo per Azure Data Manager per l'energia

L'istanza di Azure Data Manager per l'energia usa la versione OSDU® M12 di sdutil. Completare i passaggi seguenti se si vuole usare sdutil per sfruttare l'API Scientific Gestione dati System (SDMS) dell'istanza di Azure Data Manager per l'energia:

1. Assicurarsi di aver seguito i passaggi di installazione e configurazione precedenti. Questi passaggi includono il download del codice sorgente sdutil, la configurazione dell'ambiente virtuale Python, la modifica del file e l'impostazione config.yaml delle tre variabili di ambiente.

2. Eseguire i comandi seguenti per eseguire attività in Seismic Store.

   • Inizializzare:

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

   • Eseguire l'accesso:

       python sdutil config init
       python sdutil auth login
     

   • Elencare i file in 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
     

   • Caricare un file dal computer locale in Seismic Store:

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

   • Scaricare un file da Seismic Store nel computer locale:

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

     Nota

     Non usare il cp comando per scaricare i file VDS. La conversione VDS genera più file, quindi il cp comando non sarà in grado di scaricarli tutti in un unico comando. Usare invece lo strumento edizione Standard GYExport o VDSCopy. Questi strumenti usano una serie di chiamate REST che accedono a uno schema di denominazione per recuperare informazioni su tutti i file VDS risultanti.

OSDU® è un marchio di The Open Group.

Passaggio successivo

Passare all'esercitazione successiva: