Tutoriel : Utiliser sdutil pour charger des données dans Seismic Store

Article
01/30/2024

Seismic Store est une solution basée sur le cloud pour stocker et gérer des jeux de données de toute taille. Il offre un moyen sécurisé d’accéder aux jeux de données à travers un mécanisme d’autorisation limitée. Seismic Store dépasse les limitations de taille d’objet des fournisseurs de cloud en gérant les jeux de données génériques sous la forme de plusieurs objets indépendants.

Sdutil est un outil Python en ligne de commande permettant d’interagir avec Seismic Store. Vous pouvez utiliser sdutil pour effectuer des opérations de base comme charger des données dans Seismic Store, télécharger des jeux de données à partir de Seismic Store, gérer des utilisateurs et lister le contenu des dossiers.

Dans ce tutoriel, vous allez apprendre à :

Configurer et exécuter l’outil sdutil.
Obtenir l’URI du Seismic Store.
Créer un sous-projet.
Inscrire un utilisateur.
Utiliser sdutil pour gérer des jeux de données avec Seismic Store.
Exécuter des tests pour valider les fonctionnalités de l’outil sdutil.

Prérequis

Installez les prérequis suivants en fonction de votre système d’exploitation.

Windows :

Linux :

Python 3.8.3 64 bits

Unix/Mac

Sdutil nécessite d’autres modules mentionnés dans requirements.txt. Vous pouvez installer les modules tels quels ou les installer dans un environnement virtuel pour éviter les conflits de package sur votre hôte. Si vous ne voulez pas les installer dans un environnement virtuel, ignorez les quatre commandes d’environnement virtuel du code suivant. Par ailleurs, si vous utilisez Mac au lieu d’Ubuntu ou WSL - Ubuntu 20.04, utilisez homebrew plutôt que apt-get comme gestionnaire de package, ou installez manuellement 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

Installez les dépendances nécessaires :

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

Utilisation

Configuration

Clonez le dépôt sdutil à partir de la branche azure-stable de la communauté et ouvrez-le dans votre éditeur favori.

Remplacez le contenu de config.yaml dans le dossier sdlib par le code YAML suivant. Renseignez les trois valeurs modélisées (deux instances de <meds-instance-url> et une instance 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'

Remarque

Si aucun jeton n’est présent, obtenez-en un en suivant les instructions de Comment générer un jeton d’authentification.

Exportez ou définissez les variables d’environnement suivantes :

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

Exécution de l’outil

Exécutez l’outil sdutil à partir du dossier de l’utilitaire extrait :

  python sdutil

Si vous ne spécifiez aucun argument, ce menu s’affiche :

  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 c’est la première fois que vous utilisez l’outil, exécutez la commande sdutil config init pour initialiser la configuration :
```
  python sdutil config init
```
Avant de commencer à utiliser l’outil et à effectuer des opérations, vous devez vous connecter au système. Quand vous exécutez la commande suivante, sdutil ouvre une page de connexion dans un navigateur web :
```
  python sdutil auth login
```
Une fois connecté, vos informations d’identification sont valides pendant une semaine. Vous n’avez pas besoin de vous reconnecter, sauf si les informations d’identification expirent.

Remarque

Si vous n’obtenez pas le message confirmant la connexion, vérifiez que vos trois variables d’environnement sont définies et que vous avez suivi toutes les étapes de la section Configuration plus haut dans ce tutoriel.

Ressources du Seismic Store

Avant de commencer à utiliser le système, vous devez bien comprendre comment Seismic Store gère les ressources. Seismic Store gère trois types de ressources :

Projet de locataire : le projet principal. Le locataire est la première section du chemin du Seismic Store.
Sous-projet : sous-projet de travail, directement lié au projet de locataire principal. Le sous-projet est la deuxième section du chemin du Seismic Store.
Jeu de données: entité de jeu de données. Le jeu de données est la troisième et dernière section du chemin du Seismic Store. Vous pouvez spécifier la ressource de jeu de données en utilisant le formulaire path/dataset_name. Dans ce formulaire, path est facultatif et a la même signification qu’un répertoire dans un système de fichiers générique. La partie dataset_name est le nom de l’entité de jeu de données.

L’URI de Seismic Store est une chaîne que vous utilisez pour traiter de manière unique une ressource dans le système. Vous pouvez l’obtenir en ajoutant le préfixe sd:// au chemin de la ressource nécessaire :

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

Par exemple, si vous avez un jeu de données results.segy stocké dans la structure de répertoires qadata/ustest dans le sous-projet carbon du projet de locataire gtc, le code sdpath correspondant est :

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

Vous pouvez traiter chaque ressource en utilisant la section sdpath correspondante :

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

Sous-projets

Un sous-projet du Seismic Store est une unité de travail où l’utilisateur peut enregistrer les jeux de données. Le système peut gérer plusieurs sous-projets sous un projet de locataire.

Seul un administrateur du locataire peut créer une ressource de sous-projet en utilisant la commande sdutil suivante :

  > 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

Gestion des utilisateurs

Pour pouvoir utiliser Seismic Store, les utilisateurs doivent être inscrits à au moins une ressource de sous-projet avec un rôle qui définit leur niveau d’accès. Seismic Store prend en charge deux rôles limités au niveau du sous-projet :

Administrateur : accès en lecture/écriture et gestion des utilisateurs.
Lecteur : accès en lecture/liste.

Seul un administrateur de sous-projet peut inscrire un utilisateur en utilisant la commande sdutil suivante :

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

Exemples d'utilisation

Le code suivant est un exemple d’utilisation de sdutil pour gérer des jeux de données avec Seismic Store. Cet exemple utilise sd://gtc/carbon comme ressource de sous-projet.

  # 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 de l’outil

Le dossier de test contient un ensemble de tests intégraux/unitaires et de tests de régression écrits pour pytest. Exécutez ces tests pour valider les fonctionnalités de l’outil sdutil.

Utilisez ce code pour les exigences :

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

Utilisez ce code pour les tests intégraux/unitaires :

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

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

Utilisez ce code pour les tests de régression :

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

FAQ

Comment générer une nouvelle commande pour l’outil ?

Exécutez le script de génération de commande (./command_gen.py) pour générer automatiquement l’infrastructure de base permettant d’intégrer une nouvelle commande dans l’outil sdutil. Le script crée un dossier avec l’infrastructure de commandes dans sdlib/cmd/new_command_name.

  ./scripts/command_gen.py new_command_name

Comment puis-je supprimer tous les fichiers d’un répertoire ?

Utilisez le code suivant :

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

Comment générer le journal des modifications de l’outil ?

Exécutez le script du journal de modifications (./changelog-generator.sh) pour générer automatiquement le journal des modifications de l’outil :

  ./scripts/changelog-generator.sh

Utilisation pour Azure Data Manager for Energy

L’instance Azure Data Manager for Energy utilise la version OSDU® M12 de sdutil. Effectuez les étapes suivantes si vous voulez utiliser sdutil pour tirer parti de l’API SDMS (Scientific Data Management System) de votre instance Azure Data Manager for Energy :

Vérifiez que vous avez suivi les étapes d’installation et de configuration précédentes. Ces étapes comprennent le téléchargement du code source de sdutil, la configuration de votre environnement virtuel Python, la modification du fichier config.yaml et la définition de vos trois variables d’environnement.

Exécutez les commandes suivantes pour effectuer des tâches dans Seismic Store.

Initialiser :

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

Connexion :

  python sdutil config init
  python sdutil auth login

Lister les fichiers dans 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

Charger un fichier de votre machine locale dans Seismic Store :

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

Télécharger un fichier de Seismic Store sur votre machine locale :
```
  python sdutil cp sd://<datapartition>/test/file-name-at-ddms.txt local-dir/file-name-at-destination.txt
```
Remarque

N’utilisez pas la commande cp pour télécharger des fichiers VDS. Comme la conversion VDS génère plusieurs fichiers, la commande cp ne peut pas tous les télécharger avec une seule commande. Utilisez plutôt l’outil SEGYExport ou VDSCopy. Ces outils utilisent une série d’appels REST qui accèdent à un schéma de nommage pour récupérer des informations sur tous les fichiers VDS obtenus.

OSDU® est une marque déposée de The Open Group.

Étape suivante

Passez au tutoriel suivant :

Tutoriel : Utiliser des enregistrements de données de puits en utilisant les API DDMS Well Delivery

Partager via