Självstudie: Använda sdutil för att läsa in data i Seismic Store

  • Artikel

Seismic Store är en molnbaserad lösning för lagring och hantering av datamängder av valfri storlek. Det ger ett säkert sätt att komma åt datauppsättningar via en begränsad auktoriseringsmekanism. Seismic Store övervinner molnleverantörernas begränsningar för objektstorlek genom att hantera generiska datauppsättningar som flera oberoende objekt.

Sdutil är ett kommandoradsverktyg för Python för interaktion med Seismic Store. Du kan använda sdutil för att utföra grundläggande åtgärder som att ladda upp data till Seismic Store, ladda ned datauppsättningar från Seismic Store, hantera användare och visa mappinnehåll.

I den här självstudien lär du dig att:

  • Konfigurera och kör verktyget sdutil.
  • Hämta Seismic Store-URI:n.
  • Skapa ett underprojekt.
  • Registrera en användare.
  • Använd sdutil för att hantera datauppsättningar med Seismic Store.
  • Kör tester för att verifiera sdutil-verktygets funktioner.

Förutsättningar

Installera följande krav baserat på ditt operativsystem.

Windows:

Linux:

Unix/Mac

Sdutil kräver andra moduler som anges i requirements.txt. Du kan antingen installera modulerna som de är eller installera dem i en virtuell miljö för att hålla värden ren från paketkonflikter. Om du inte vill installera dem i en virtuell miljö hoppar du över de fyra kommandona för virtuell miljö i följande kod. Om du använder Mac i stället för Ubuntu eller WSL – Ubuntu 20.04 kan du antingen använda homebrew i stället för apt-get som pakethanterare eller manuellt installera 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

Installera nödvändiga beroenden:

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

Användning

Konfiguration

  1. Klona sdutil-lagringsplatsen från community-grenen azure-stable och öppna i din favoritredigerare.

  2. Ersätt innehållet config.yaml i i sdlib mappen med följande YAML. Fyll i de tre templaterade värdena (två instanser av <meds-instance-url> och en instans av <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'

    Kommentar

    Om det inte redan finns en token hämtar du en genom att följa anvisningarna i Generera autentiseringstoken.

  3. Exportera eller ange följande miljövariabler:

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

Köra verktyget

  1. Kör sdutil-verktyget från den extraherade verktygsmappen:

      python sdutil

    Om du inte anger några argument visas den här menyn:

      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. Om det här är första gången du använder verktyget kör du sdutil config init kommandot för att initiera konfigurationen:

      python sdutil config init

  3. Innan du börjar använda verktyget och utför några åtgärder måste du logga in på systemet. När du kör följande kommando öppnar sdutil en inloggningssida i en webbläsare:

      python sdutil auth login

    När du har loggat in är dina autentiseringsuppgifter giltiga i en vecka. Du behöver inte logga in igen om inte autentiseringsuppgifterna upphör att gälla.

    Kommentar

    Om du inte får meddelandet om lyckad inloggning kontrollerar du att dina tre miljövariabler har angetts och att du har följt alla steg i avsnittet Konfiguration tidigare i den här självstudien.

Seismic Store-resurser

Innan du börjar använda systemet är det viktigt att förstå hur Seismic Store hanterar resurser. Seismic Store hanterar tre typer av resurser:

  • Klientprojekt: Huvudprojektet. Klientorganisationen är det första avsnittet i Seismic Store-sökvägen.
  • Underprojekt: Det arbetsunderprojekt som är direkt länkat under huvudklientprojektet. Underprojektet är det andra avsnittet i Seismic Store-sökvägen.
  • Datauppsättning: Datamängdentiteten. Datamängden är det tredje och sista avsnittet i Seismic Store-sökvägen. Du kan ange datamängdsresursen med hjälp av formuläret path/dataset_name. I det formuläret path är det valfritt och har samma betydelse som en katalog i ett allmänt filsystem. Delen dataset_name är namnet på datauppsättningens entitet.

Seismic Store-URI:n är en sträng som du använder för att unikt adressera en resurs i systemet. Du kan hämta det genom att lägga till prefixet sd:// på den resurssökväg som krävs:

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

Om du till exempel har en results.segy datauppsättning lagrad i qadata/ustest katalogstrukturen i carbon underprojektet under gtc klientprojektet är motsvarande sdpath kod:

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

Du kan adressera varje resurs med hjälp av motsvarande sdpath avsnitt:

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

Underprojekt

Ett underprojekt i Seismic Store är en arbetsenhet där en användare kan spara datamängder. Systemet kan hantera flera underprojekt under ett klientprojekt.

Endast en klientadministratör kan skapa en underprojektresurs med hjälp av följande sdutil-kommando:

  > 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

Användarhantering

För att kunna använda Seismic Store måste användarna vara registrerade på minst en underprojektresurs med en roll som definierar deras åtkomstnivå. Seismic Store har stöd för två roller som är begränsade på underprojektnivå:

  • Administratör: Läs-/skrivåtkomst och användarhantering.
  • Visningsprogram: Läs-/liståtkomst.

Endast en underprojektadministratör kan registrera en användare med hjälp av följande sdutil-kommando:

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

Exempel på användning

Följande kod är ett exempel på hur du använder sdutil för att hantera datauppsättningar med Seismic Store. Det här exemplet används sd://gtc/carbon som underprojektresurs.

  # 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

Verktygstestning

Testmappen innehåller en uppsättning integral-/enhets- och regressionstester skrivna för pytest. Kör dessa tester för att verifiera sdutil-verktygets funktioner.

Använd den här koden för krav:

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

Använd den här koden för integral-/enhetstester:

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

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

Använd den här koden för regressionstester:

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

Vanliga frågor

Hur genererar jag ett nytt kommando för verktyget?

Kör kommandogenereringsskriptet (./command_gen.py) för att automatiskt generera basinfrastrukturen för att integrera ett nytt kommando i sdutil-verktyget. Skriptet skapar en mapp med kommandoinfrastrukturen i sdlib/cmd/new_command_name.

  ./scripts/command_gen.py new_command_name

Hur tar jag bort alla filer i en katalog?

Använd följande kod:

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

Hur kan jag generera verktygets ändringslogg?

Kör ändringsloggskriptet (./changelog-generator.sh) för att automatiskt generera verktygets ändringslogg:

  ./scripts/changelog-generator.sh

Användning för Azure Data Manager för energi

Azure Data Manager for Energy-instansen använder OSDU® M12-versionen av sdutil. Slutför följande steg om du vill använda sdutil för att dra nytta av SDMS-API:et (Scientific Datahantering System) i din Azure Data Manager for Energy-instans:

  1. Kontrollera att du följde de tidigare installations - och konfigurationsstegen . De här stegen omfattar att ladda ned sdutil-källkoden, konfigurera din virtuella Python-miljö, redigera config.yaml filen och ange dina tre miljövariabler.

  2. Kör följande kommandon för att utföra uppgifter i Seismic Store.

    • Initiera:

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

    • Logga in:

        python sdutil config init
  python sdutil auth login

    • Lista filer i 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

    • Ladda upp en fil från din lokala dator till Seismic Store:

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

    • Ladda ned en fil från Seismic Store till din lokala dator:

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

      Kommentar

      Använd cp inte kommandot för att ladda ned VDS-filer. VDS-konverteringen cp resulterar i flera filer, så kommandot kan inte ladda ned alla i ett kommando. Använd antingen VERKTYGET SEGYExport eller VDSCopy i stället. De här verktygen använder en serie REST-anrop som har åtkomst till ett namngivningsschema för att hämta information om alla resulterande VDS-filer.

OSDU® är ett varumärke som tillhör The Open Group.

Gå vidare

Gå vidare till nästa kurs:

Självstudie: Arbeta med väldataposter med hjälp av DDMS-API:er för well delivery