Zelfstudie: Sdutil gebruiken om gegevens te laden in Seismic Store

Seismic Store is een cloudoplossing voor het opslaan en beheren van gegevenssets van elke grootte. Het biedt een veilige manier om toegang te krijgen tot gegevenssets via een autorisatiemechanisme binnen een bereik. Seismic Store ondervangt de objectgroottebeperkingen van cloudproviders door algemene gegevenssets als meerdere onafhankelijke objecten te beheren.

Sdutil is een python-opdrachtregelprogramma voor interactie met Seismic Store. U kunt sdutil gebruiken om basisbewerkingen uit te voeren, zoals het uploaden van gegevens naar Seismic Store, het downloaden van gegevenssets uit Seismic Store, het beheren van gebruikers en het weergeven van mapinhoud.

In deze zelfstudie leert u het volgende:

• Het hulpprogramma sdutil instellen en uitvoeren.
• Haal de Seismic Store-URI op.
• Maak een subproject.
• Een gebruiker registreren.
• Gebruik sdutil om gegevenssets te beheren met Seismic Store.
• Voer tests uit om de functionaliteiten van het sdutil-hulpprogramma te valideren.

Vereisten

Installeer de volgende vereisten op basis van uw besturingssysteem.

Windows:

• 64-bits Python 3.8.3
• Microsoft C++ Build Tools
• Linux-subsysteem Ubuntu

Linux:

• 64-bits Python 3.8.3

Unix/Mac

• 64-bits Python 3.8.3
• Buildhulpprogramma's voor Apple Xcode C++

Sdutil vereist andere modules die worden vermeld in requirements.txt. U kunt de modules als zodanig installeren of installeren in een virtuele omgeving om uw host schoon te houden tegen pakketconflicten. Als u deze niet wilt installeren in een virtuele omgeving, slaat u de vier opdrachten van de virtuele omgeving over in de volgende code. Als u mac gebruikt in plaats van Ubuntu of WSL - Ubuntu 20.04, gebruikt homebrew u in plaats van apt-get als pakketbeheerder of handmatig installeert 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

Vereiste afhankelijkheden installeren:

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

Gebruik

Configuratie

1. Kloon de sdutil-opslagplaats vanuit de communitybranch azure-stable en open deze in uw favoriete editor.

2. Vervang de inhoud van config.yaml de sdlib map door de volgende YAML. Vul de drie ge templatiseerde waarden in (twee exemplaren van <meds-instance-url> en één exemplaar van <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'
   

   Notitie

   Als er nog geen token aanwezig is, kunt u er een verkrijgen door de aanwijzingen in Verificatietoken te genereren.

3. Exporteer of stel de volgende omgevingsvariabelen in:

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

Het hulpprogramma uitvoeren

1. Voer het hulpprogramma sdutil uit vanuit de uitgepakte hulpprogrammamap:

     python sdutil
   

   Als u geen argumenten opgeeft, wordt dit menu weergegeven:

     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. Als dit de eerste keer is dat u het hulpprogramma gebruikt, voert u de sdutil config init opdracht uit om de configuratie te initialiseren:

     python sdutil config init
   

3. Voordat u het hulpprogramma gaat gebruiken en bewerkingen uitvoert, moet u zich aanmelden bij het systeem. Wanneer u de volgende opdracht uitvoert, opent sdutil een aanmeldingspagina in een webbrowser:

     python sdutil auth login
   

   Nadat u zich hebt aangemeld, zijn uw referenties een week geldig. U hoeft u niet opnieuw aan te melden, tenzij de referenties verlopen.

   Notitie

   Als u het bericht over geslaagde aanmelding niet krijgt, moet u ervoor zorgen dat uw drie omgevingsvariabelen zijn ingesteld en dat u alle stappen in de sectie Configuratie eerder in deze zelfstudie hebt gevolgd.

Seismic Store-resources

Voordat u het systeem gaat gebruiken, is het belangrijk om te begrijpen hoe Seismic Store resources beheert. Seismic Store beheert drie soorten resources:

• Tenantproject: het hoofdproject. De tenant is de eerste sectie van het Seismic Store-pad.
• Subproject: Het werkende subproject, dat rechtstreeks is gekoppeld onder het hoofdtenantproject. Het subproject is de tweede sectie van het pad Seismic Store.
• Gegevensset: de entiteit gegevensset. De gegevensset is het derde en laatste gedeelte van het Seismic Store-pad. U kunt de gegevenssetresource opgeven met behulp van het formulier path/dataset_name. In deze vorm path is dit optioneel en heeft dezelfde betekenis als een map in een algemeen bestandssysteem. Het dataset_name onderdeel is de naam van de entiteit gegevensset.

De Seismic Store-URI is een tekenreeks die u gebruikt om een resource in het systeem uniek aan te pakken. U kunt dit verkrijgen door het voorvoegsel sd:// toe te voegen aan het vereiste resourcepad:

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

Als u bijvoorbeeld een results.segy gegevensset hebt opgeslagen in de qadata/ustest mapstructuur in het carbon subproject onder het gtc tenantproject, is de bijbehorende sdpath code:

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

U kunt elke resource adresseren met behulp van de bijbehorende sdpath sectie:

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

Subprojecten

Een subproject in Seismic Store is een werkeenheid waarin een gebruiker gegevenssets kan opslaan. Het systeem kan meerdere subprojecten verwerken onder een tenantproject.

Alleen een tenantbeheerder kan een subprojectresource maken met behulp van de volgende sdutil-opdracht:

  > 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

Gebruikersbeheer

Als u Seismic Store wilt kunnen gebruiken, moeten gebruikers zijn geregistreerd bij ten minste een subprojectresource met een rol die hun toegangsniveau definieert. Seismic Store ondersteunt twee rollen binnen het bereik van het subprojectniveau:

• Beheer: lees-/schrijftoegang en gebruikersbeheer.
• Viewer: Lees-/lijsttoegang.

Alleen een subprojectbeheerder kan een gebruiker registreren met behulp van de volgende sdutil-opdracht:

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

Voorbeelden van gebruik

De volgende code is een voorbeeld van het gebruik van sdutil voor het beheren van gegevenssets met Seismic Store. In dit voorbeeld wordt de subprojectresource gebruikt 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

Hulpprogramma testen

De testmap bevat een set integrale/eenheids- en regressietests die zijn geschreven voor pytest. Voer deze tests uit om de functionaliteiten van het sdutil-hulpprogramma te valideren.

Gebruik deze code voor vereisten:

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

Gebruik deze code voor integrale/eenheidstests:

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

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

Gebruik deze code voor regressietests:

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

Veelgestelde vragen

Hoe kan ik een nieuwe opdracht voor het hulpprogramma genereren?

Voer het script voor het genereren van opdrachten (./command_gen.py) uit om automatisch de basisinfrastructuur te genereren voor het integreren van een nieuwe opdracht in het hulpprogramma sdutil. Het script maakt een map met de opdrachtinfrastructuur in sdlib/cmd/new_command_name.

  ./scripts/command_gen.py new_command_name

Hoe kan ik alle bestanden in een map verwijderen?

Gebruik de volgende code:

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

Hoe kan ik het wijzigingenlogboek van het hulpprogramma genereren?

Voer het changelog-script (./changelog-generator.sh) uit om automatisch het wijzigingenlogboek van het hulpprogramma te genereren:

  ./scripts/changelog-generator.sh

Gebruik voor Azure Data Manager voor Energie

De Azure Data Manager for Energy-instantie maakt gebruik van de OSDU® M12-versie van sdutil. Voer de volgende stappen uit als u sdutil wilt gebruiken om te profiteren van de SDMS-API (Scientific Gegevensbeheer System) van uw Azure Data Manager for Energy-exemplaar:

1. Zorg ervoor dat u de eerdere installatie - en configuratiestappen hebt gevolgd. Deze stappen omvatten het downloaden van de sdutil-broncode, het configureren van uw virtuele Python-omgeving, het bewerken van het bestand en het config.yaml instellen van uw drie omgevingsvariabelen.

2. Voer de volgende opdrachten uit om taken uit te voeren in Seismic Store.

   • Initialiseren:

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

   • Aanmelden:

       python sdutil config init
       python sdutil auth login
     

   • Bestanden weergeven 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
     

   • Upload een bestand van uw lokale computer naar Seismic Store:

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

   • Download een bestand van Seismic Store naar uw lokale computer:

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

     Notitie

     Gebruik de cp opdracht niet om VDS-bestanden te downloaden. De VDS-conversie resulteert in meerdere bestanden, zodat de cp opdracht niet alle bestanden in één opdracht kan downloaden. Gebruik in plaats daarvan het hulpprogramma SEGYExport of VDSCopy . Deze hulpprogramma's gebruiken een reeks REST-aanroepen die toegang hebben tot een naamgevingsschema om informatie over alle resulterende VDS-bestanden op te halen.

OSDU® is een handelsmerk van The Open Group.

Volgende stap

Ga door naar de volgende zelfstudie:

Zelfstudie: Werken met brongegevensrecords met behulp van Well Delivery DDMS-API's