Tutorial: Uso de sdutil para cargar datos en Seismic Store

Artículo
02/01/2024

Seismic Store es una solución basada en la nube para almacenar y administrar conjuntos de datos de cualquier tamaño. Proporciona una manera segura de acceder a los conjuntos de datos a través de un mecanismo de autorización con ámbito. Seismic Store supera las limitaciones de tamaño de objetos de los proveedores de nube mediante la administración de conjuntos de datos genéricos como varios objetos independientes.

Sdutil es una herramienta de Python de línea de comandos para interactuar con Seismic Store. Puede usar sdutil para realizar operaciones básicas como cargar datos en Seismic Store, descargar conjuntos de datos de Seismic Store, administrar usuarios y enumerar el contenido de las carpetas.

En este tutorial, aprenderá a:

Configure y ejecute la herramienta sdutil.
Obtenga el URI de Seismic Store.
Cree un subproyecto.
Registre un usuario.
Use sdutil para administrar conjuntos de datos con Seismic Store.
Ejecute pruebas para validar las funcionalidades de la herramienta sdutil.

Requisitos previos

Instale los siguientes requisitos previos en función de su sistema operativo.

Windows:

Linux:

Python de 64 bits 3.8.3

Unix/Mac

Sdutil requiere otros módulos indicados en requirements.txt. Puede instalar los módulos tal cual o instalarlos en un entorno virtual para mantener el host limpio de conflictos de paquetes. Si no desea instalarlos en un entorno virtual, omita los cuatro comandos de entorno virtual del siguiente código. Además, si usa Mac en lugar de Ubuntu o WSL: Ubuntu 20.04, use homebrew en lugar de apt-get como administrador de paquetes o instale 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

Instalar las dependencias necesarias:

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

Uso

Configuración

Clone el repositorio sdutil, que está en la rama azure-stable de la comunidad, y abra su editor favorito.

Reemplace el contenido de config.yaml de la carpeta sdlib por el siguiente código YAML. Rellene los tres valores con plantillas (dos instancias de <meds-instance-url> y una instancia de <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:

Si un token aún no está presente, obtenga uno siguiendo las instrucciones de Cómo generar el token de autenticación.

Exporte o establezca las siguientes variables de entorno:

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

Ejecución de la herramienta

Ejecute la herramienta sdutil desde la carpeta de utilidad extraída:

  python sdutil

Si no especifica ningún argumento, aparecerá este menú:

  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

Si esta es la primera vez que usa la herramienta, ejecute el comando sdutil config init para inicializar la configuración:
```
  python sdutil config init
```
Antes de empezar a usar la herramienta y realizar cualquier operación, debe iniciar sesión en el sistema. Al ejecutar el comando siguiente, sdutil abre una página de inicio de sesión en un explorador web:
```
  python sdutil auth login
```
Después de iniciar sesión correctamente, las credenciales son válidas durante una semana. No es necesario volver a iniciar sesión a menos que expiren las credenciales.

Nota:

Si no recibe el mensaje sobre el inicio de sesión correcto, asegúrese de que estén establecidas las tres variables de entorno y que ha seguido todos los pasos de la sección Configuración vista anteriormente en este tutorial.

Recursos de Seismic Store

Antes de empezar a usar el sistema, es importante comprender cómo Seismic Store administra los recursos. Seismic Store administra tres tipos de recursos:

Proyecto de inquilino: el proyecto principal. El inquilino es la primera sección de la ruta de acceso de Seismic Store.
Subproyecto: el subproyecto de trabajo, que está vinculado directamente en el proyecto de inquilino principal. El subproyecto es la segunda sección de la ruta de acceso de Seismic Store.
Conjunto de datos: la entidad del conjunto de datos. El conjunto de datos es la tercera y última sección de la ruta de acceso de Seismic Store. Puede especificar el recurso del conjunto de datos mediante el formulario path/dataset_name. En ese formato, path es opcional y tiene el mismo significado que un directorio de un sistema de archivos genérico. La parte dataset_name es el nombre de la entidad del conjunto de datos.

El URI de Seismic Store es una cadena que se usa para direccionar de forma única un recurso del sistema. Para obtenerlo, anexe el prefijo sd:// a la ruta de acceso de recurso necesaria:

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

Por ejemplo, si tiene un conjunto de datos results.segy almacenado en la estructura de directorios qadata/ustest del subproyecto carbon en el proyecto de inquilino gtc, el sdpath correspondiente será:

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

Puede abordar todos los recursos mediante la sección sdpath correspondiente:

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

Subproyectos

Un subproyecto de Seismic Store es una unidad de trabajo donde se pueden guardar conjuntos de datos. El sistema puede controlar varios subproyectos en un proyecto de inquilino.

Solo un administrador de inquilinos puede crear un recurso de subproyecto mediante el siguiente comando sdutil:

  > 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

Administración de usuarios

Para poder usar Seismic Store, los usuarios deben registrarse en al menos un recurso de subproyecto con un rol que defina su nivel de acceso. Seismic Store admite dos roles con ámbito en el nivel de subproyecto:

Administrador: acceso de lectura y escritura y administración de usuarios.
Visor: acceso de lectura y lista.

Solo un administrador de subproyectos puede registrar un usuario mediante el siguiente comando sdutil:

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

Ejemplos de uso

El código siguiente es un ejemplo de cómo usar sdutil para administrar conjuntos de datos con Seismic Store. En este ejemplo se usa sd://gtc/carbon como recurso de subproyecto.

  # 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

Pruebas de herramientas

La carpeta de prueba contiene un conjunto de pruebas integrales, unitarias y de regresión escritas para pytest. Ejecute estas pruebas para validar las funcionalidades de la herramienta sdutil.

Use este código para conocer los requisitos:

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

Use este código para pruebas integrales o unitarias:

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

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

Use este código para las pruebas de regresión:

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

Preguntas más frecuentes

¿Cómo puedo generar un nuevo comando para la herramienta?

Ejecute el script de generación de comandos (./command_gen.py) para generar automáticamente la infraestructura base para integrar el nuevo comando en la utilidad sdutil. El script crea una carpeta con la infraestructura de comandos de sdlib/cmd/new_command_name.

  ./scripts/command_gen.py new_command_name

¿Cómo puedo eliminar todos los archivos de un directorio?

Use el código siguiente:

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

¿Cómo puedo generar el registro de cambios de la herramienta?

Ejecute el script de registro de cambios (./changelog-generator.sh) para generar automáticamente el registro de cambios de la utilidad:

  ./scripts/changelog-generator.sh

Uso de Azure Data Manager for Energy

La instancia de Azure Data Manager for Energy usa la versión M12 de OSDU® de sdutil. Complete los pasos siguientes si desea usar sdutil para aprovechar la API del Sistema de administración de datos científicos (SDMS) de la instancia de Azure Data Manager for Energy:

Asegúrese de haber seguido los pasos de instalación y de configuración anteriores. Estos pasos incluyen descargar el código fuente de sdutil, configurar el entorno virtual de Python, editar el archivo config.yaml y establecer las tres variables de entorno.

Ejecute los siguientes comandos para realizar tareas en Seismic Store.

Inicializar:

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

Inicie sesión:

  python sdutil config init
  python sdutil auth login

Enumerar archivos en 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

Carga de un archivo desde la máquina local en Seismic Store:

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

Descargar un archivo de Seismic Store en la máquina local:
```
  python sdutil cp sd://<datapartition>/test/file-name-at-ddms.txt local-dir/file-name-at-destination.txt
```
Nota:

No use el comando cp para descargar archivos VDS. La conversión a VDS da como resultado varios archivos, por lo que el comando cp no podrá descargar todos ellos en un comando. En su lugar, use la herramienta SEGYExport o VDSCopy. Estas herramientas usan una serie de llamadas REST que acceden a un esquema de nomenclatura para recuperar información sobre todos los archivos VDS resultantes.

OSDU® es una marca comercial de The Open Group.

Paso siguiente

Avance hasta el siguiente tutorial:

Tutorial: Uso de registros de datos de pozos mediante las API de DDMS de Well Delivery

Compartir a través de