Tutorial: Verwenden von „sdutil“ zum Hochladen von Daten in Seismic Store

  • Artikel

Seismic Store ist eine cloudbasierte Lösung zum Speichern und Verwalten von Datasets beliebiger Größe. Sie bietet eine sichere Möglichkeit, über einen bereichsbezogenen Autorisierungsmechanismus auf Datasets zuzugreifen. Seismic Store überwindet die Einschränkungen des Cloudanbieter hinsichtlich der Objektgröße, indem er generische Datasets als mehrere unabhängige Objekte verwaltet.

„sdutil“ ist ein Python-Befehlszeilentool für die Interaktion mit Seismic Store. Sie können „sdutil“ verwenden, um grundlegende Vorgänge auszuführen, z. B. das Hochladen von Daten in Seismic Store, das Herunterladen von Datasets aus Seismic Store, das Verwalten von Benutzer*innen und das Auflisten von Ordnerinhalten.

In diesem Tutorial lernen Sie Folgendes:

  • Einrichten und Ausführen des sdutil-Tools
  • Abrufen des Seismic Store-URIs
  • Erstellen eines Unterprojekts
  • Registrieren von Benutzer*innen
  • Verwenden von „sdutil“ zum Verwalten von Datasets mit Seismic Store
  • Ausführen von Tests zum Überprüfen der Funktionen des sdutil-Tools

Voraussetzungen

Installieren Sie die folgenden erforderlichen Komponenten basierend auf Ihrem Betriebssystem.

Windows:

Linux:

Unix/Mac

„sdutil“ erfordert weitere Module, die in requirements.txtangegeben sind. Sie können die Module entweder unverändert installieren oder sie in einer virtuellen Umgebung installieren, um Paketkonflikte auf Ihrem Host zu vermeiden. Wenn Sie sie nicht in einer virtuellen Umgebung installieren möchten, überspringen Sie die folgenden vier Befehle für virtuelle Umgebungen im folgenden Code. Wenn Sie Mac anstelle von Ubuntu oder WSL (Ubuntu 20.04) nutzen, verwenden Sie außerdem homebrew anstelle von apt-get als Paket-Manager, oder installieren Sie apt-get manuell.

  # 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

Installieren Sie erforderliche Abhängigkeiten:

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

Verwendung

Konfiguration

  1. Klonen Sie das sdutil-Repository aus dem azure-stable-Branch der Community, und öffnen Sie es in Ihrem bevorzugten Editor.

  2. Ersetzen Sie den Inhalt von config.yaml im Ordner sdlib durch den folgenden YAML-Code. Geben Sie die drei Werte aus der Vorlage ein (zwei Instanzen von <meds-instance-url> und eine Instanz von <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'

    Hinweis

    Wenn noch kein Token vorhanden ist, rufen Sie anhand der Anweisungen in Generieren eines Authentifizierungstokens eines ab.

  3. Exportieren Sie anschließend die folgenden Umgebungsvariablen, oder legen Sie sie fest:

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

Ausführen des Tools

  1. Führen Sie das sdutil-Tool über den extrahierten Hilfsprogrammordner aus:

      python sdutil

    Wenn Sie keine Argumente angeben, wird dieses Menü angezeigt:

      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. Wenn Sie das Tool zum ersten Mal verwenden, führen Sie den Befehl sdutil config init aus, um die Konfiguration zu initialisieren.

      python sdutil config init

  3. Bevor Sie das Tool verwenden und Vorgänge damit durchführen können, müssen Sie sich beim System anmelden. Wenn Sie den folgenden Befehl ausführen, öffnet „sdutil“ eine Anmeldeseite in einem Webbrowser.

      python sdutil auth login

    Nachdem Sie sich erfolgreich angemeldet haben, sind Ihre Anmeldeinformationen für eine Woche gültig. Sie müssen sich nicht erneut anmelden, es sei denn, die Anmeldeinformationen laufen ab.

    Hinweis

    Wenn Sie die Meldung zur erfolgreichen Anmeldung nicht erhalten, stellen Sie sicher, dass Ihre drei Umgebungsvariablen festgelegt sind und dass Sie alle Schritte im Abschnitt Konfiguration weiter oben in diesem Tutorial ausgeführt haben.

Seismic Store-Ressourcen

Bevor Sie das System verwenden, ist es wichtig zu verstehen, wie Seismic Store Ressourcen verwaltet. Seismic Store verwaltet drei Typen von Ressourcen:

  • Mandantenprojekt: das Hauptprojekt. Der Mandant ist der erste Abschnitt des Seismic Store-Pfads.
  • Unterprojekt: das Arbeitsunterprojekt, das direkt mit dem Hauptprojekt des Mandanten verbunden ist. Das Unterprojekt ist der zweite Abschnitt des Seismic Store-Pfads.
  • Dataset: die Datasetentität. Das Dataset ist der dritte und letzte Abschnitt des Seismic Store-Pfads. Sie können die Datasetressource in der Form path/dataset_name angeben. In dieser Form ist path optional und hat die gleiche Bedeutung wie ein Verzeichnis in einem generischen Dateisystem. Der dataset_name-Teil ist der Name der Datasetentität.

Der Seismic Store-URI ist eine Zeichenfolge, die Sie verwenden, um eine Ressource im System eindeutig zuzuordnen. Sie können ihn abrufen, indem Sie das Präfix sd:// an den Pfad der erforderlichen Ressource anfügen:

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

Wenn Sie beispielsweise ein Dataset namens results.segy in der Verzeichnisstruktur qadata/ustest im Unterprojekt carbon unter dem Mandantenprojekt gtc gespeichert haben, lautet der entsprechende sdpath-Code:

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

Sie können jede Ressource über den entsprechenden sdpath-Abschnitt zuordnen:

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

Unterprojekte

Ein Unterprojekt in Seismic Store ist eine Arbeitseinheit, in der Datasets gespeichert werden können. Das System kann mehrere Unterprojekte unter einem Mandantenprojekt verwalten.

Eine Unterprojektressource kann nur von einem*r Mandantenadministrator*in mit dem folgenden sdutil-Befehl erstellt werden:

  > 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

Benutzerverwaltung

Um Seismic Store verwenden zu können, müssen Benutzer*innen mindestens bei einer Unterprojektressource mit einer Rolle registriert sein, die ihre Zugriffsebene definiert. Seismic Store unterstützt zwei Rollen, die auf der Unterprojektebene definiert sind:

  • Administrator: Lese-/Schreibzugriff und Benutzerverwaltung.
  • Viewer: Lese-/Schreibzugriff.

Ein*e Benutzer*in kann nur von einem*r Mandantenadministrator*in mit dem folgenden sdutil-Befehl registriert werden:

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

Anwendungsbeispiele

Der folgende Code ist ein Beispiel für die Verwenden von „sdutil“ zur Verwaltung von Datasets mit Seismic Store. Für dieses Beispiel wird sd://gtc/carbon als Unterprojektressource verwendet.

  # 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

Tooltests

Der Testordner enthält eine festgelegte Anzahl von Integral-/Komponenten- und Regressionstests, die für pytest geschrieben wurden. Führen Sie diese Tests aus, um die Funktionen des sdutil-Tools zu überprüfen.

Verwenden Sie diesen Code für Anforderungen:

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

Verwenden Sie diesen Code für Integral-/Komponententests:

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

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

Verwenden Sie diesen Code für Regressionstests:

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

Häufig gestellte Fragen

Wie kann ich einen neuen Befehl für das Tool generieren?

Führen Sie das Skript zur Befehlsgenerierung (./command_gen.py) aus, um automatisch die Basisinfrastruktur für die Integration eines neuen Befehls in das sdutil-Tool zu generieren. Das Skript erstellt einen Ordner mit der Befehlsinfrastruktur in sdlib/cmd/new_command_name.

  ./scripts/command_gen.py new_command_name

Wie kann ich alle Dateien in einem Verzeichnis löschen?

Verwenden Sie den folgenden Code:

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

Wie kann ich das Änderungsprotokoll des Tools generieren?

Führen Sie das Skript für das Änderungsprotokoll (./changelog-generator.sh) aus, um das Änderungsprotokoll des Tools automatisch zu generieren.

  ./scripts/changelog-generator.sh

Verwendung von Azure Data Manager for Energy

Die Azure Data Manager for Energy-Instanz verwendet die OSDU® M12-Version von „sdutil“. Führen Sie die folgenden Schritte aus, wenn Sie „sdutil“ verwenden möchten, um die SDMS-API (Scientific Data Management System) Ihrer Azure Data Manager for Energy-Instanz zu nutzen:

  1. Stellen Sie sicher, dass Sie die vorherigen Installation- und Konfigurationsschritte befolgt haben. Zu diesen Schritten gehören das Herunterladen des sdutil-Quellcodes, das Konfigurieren Ihrer virtuellen Python-Umgebung, das Bearbeiten der Datei config.yaml und das Festlegen Ihrer drei Umgebungsvariablen.

  2. Führen Sie die folgenden Befehle aus, um Aufgaben in Seismic Store auszuführen.

    • Initialisieren:

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

    • Anmelden:

        python sdutil config init
  python sdutil auth login

    • Auflisten von Dateien 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

    • Hochladen einer Datei von Ihrem lokalen Computer in Seismic Store:

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

    • Herunterladen einer Datei aus Seismic Store auf Ihren lokalen Computer:

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

      Hinweis

      Verwenden Sie nicht den Befehl cp, um VDS-Dateien herunterzuladen. Bei der VDS-Konvertierung entstehen mehrere Dateien, die sich nicht alle zusammen mit dem Befehl cp herunterladen lassen. Verwenden Sie stattdessen SEGYExport oder VDSCopy. Diese Tools verwenden eine Reihe von REST-Aufrufen, die auf ein Benennungsschema zugreifen, um Informationen zu allen resultierenden VDS-Dateien abzurufen.

OSDU® ist eine Marke von The Open Group.

Nächster Schritt

Fahren Sie mit dem nächsten Tutorial fort:

Tutorial: Arbeiten mit Bohrlochdatensätzen mithilfe der Well Delivery DDMS-APIs