Tutorial: Como usar o sdutil para carregar dados no Repositório Sísmico

O Repositório Sísmico é uma solução baseada em nuvem para armazenar e gerenciar conjuntos de dados de qualquer tamanho. Ele fornece uma maneira segura de acessar conjuntos de dados por meio de um mecanismo de autorização com escopo. O Repositório Sísmico supera as limitações de tamanho de objeto dos provedores de nuvem gerenciando conjuntos de dados genéricos como vários objetos independentes.

O Sdutil é uma ferramenta Python de linha de comando para interagir com o Repositório Sísmico. Você pode usar o sdutil para executar operações básicas, como carregar dados no Repositório Sísmico, baixar conjuntos de dados do Repositório Sísmico, gerenciar usuários e listar o conteúdo da pasta.

Neste tutorial, você aprenderá a:

• Configure e execute a ferramenta sdutil.
• Obtenha o URI do Repositório Sísmico.
• Crie um subprojeto.
• Registre um usuário
• Use o sdutil para gerenciar conjuntos de dados com o Repositório Sísmico.
• Execute testes para validar as funcionalidades da ferramenta sdutil.

Pré-requisitos

Instale os seguintes pré-requisitos com base no sistema operacional.

Windows:

• Python 3.8.3 de 64 bits
• Ferramentas de Compilação do Microsoft C++
• Subsistema Ubuntu Linux

Linux:

• Python 3.8.3 de 64 bits

Unix/Mac

• Python 3.8.3 de 64 bits
• Ferramentas de compilação do Apple Xcode C++s

O Sdutil requer outros módulos anotados em requirements.txt. É possível instalar os módulos como estão ou instalá-los em um ambiente virtual para manter o host limpo de conflitos de pacotes. Se você não deseja instalá-los em um ambiente virtual, ignore os quatro comandos de ambiente virtual abaixo. Além disso, se você estiver usando o Mac em vez do Ubuntu ou do WSL – Ubuntu 20.04, use homebrew em vez de apt-get como seu gerenciador de pacotes ou instale apt-get manualmente.

  # 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

Instale as dependências necessárias:

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

Uso

Configuração

1. Clone o repositório sdutil do branch azure-stableda comunidade do Azure e abra no editor favorito.

2. Substitua o conteúdo de config.yaml na pasta sdlib com o YAML a seguir. Preencha os três valores modelados (duas instâncias de <meds-instance-url> e uma instância 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'
   

   Observação

   Se um token ainda não estiver presente, obtenha um seguindo as instruções em Como gerar token de autenticação.

3. Em seguida, defina as seguintes variáveis de ambiente:

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

A execução da ferramenta

1. Execute a ferramenta sdutil da pasta do utilitário extraído:

     python sdutil
   

   Se você não especificar argumentos, esse menu será exibido:

     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. Se esta for a primeira vez que você usa a ferramenta, execute o comando sdutil config init para inicializar a configuração:

     python sdutil config init
   

3. Antes de começar a usar o utilitário e executar qualquer operação, será necessário entrar no sistema. Quando você executa o seguinte comando, o sdutil abre uma página de entrada em um navegador da Web:

     python sdutil auth login
   

   Depois de entrar com êxito, suas credenciais são válidas por uma semana. Você não precisa entrar novamente, a menos que as credenciais expirem.

   Observação

   Se você não estiver recebendo a mensagem sobre logon bem-sucedido, verifique se suas três variáveis de ambiente estão definidas e que você seguiu todas as etapas na seção Configuração vista anteriormente neste tutorial.

Recursos do Repositório Sísmico

Antes de começar a usar o sistema, é importante reconhecer como os recursos são endereçados no repositório sísmico. O Repositório Sísmico gerencia três tipos de recursos:

• Projeto de locatário: o projeto principal. O locatário é a primeira seção do caminho do Repositório Sísmico.
• Subprojeto: o subprojeto de trabalho, diretamente vinculado ao projeto de locatário principal. O subprojeto é a segunda seção do caminho do repositório sísmico.
• Conjunto de dados: a entidade do conjunto de dados. O conjunto de dados é a terceira e última seção do caminho do repositório sísmico. Você pode especificar o recurso do conjunto de dados usando o formulário path/dataset_name. Nesse formulário, path é opcional e tem o mesmo significado que um diretório em um sistema de arquivos genérico. A parte dataset_name é o nome da entidade do conjunto de dados.

O URI do Repositório Sísmico é uma cadeia de caracteres que você usa para abordar exclusivamente um recurso no sistema. Você pode obtê-lo acrescentando o prefixo sd:// ao caminho de recurso necessário:

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

Por exemplo, se tiver um conjunto de dados results.segy armazenado na estrutura de diretório qadata/ustest no subprojeto carbon no projeto de locatário gtc, o código sdpath correspondente será:

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

Você pode abordar todos os recursos usando a seção sdpath correspondente:

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

Subprojetos

Um subprojeto no Repositório Sísmico é uma unidade de trabalho na qual é possível salvar os conjuntos de dados. O sistema poderá manipular vários subprojetos em um projeto de locatário.

Somente um administrador de locatário pode criar um recurso de subprojeto usando o seguinte 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

Gerenciamento de usuários

Para poder usar o Repositório Sísmico, um usuário deverá estar registrado em pelo menos um recurso de subprojeto com uma função que defina o nível de acesso. O Repositório Sísmico dá suporte a duas funções com escopo no nível do subprojeto:

• Administrador: acesso de leitura/gravação e gerenciamento de usuário.
• Visualizador: acesso de lista/leitura.

Somente um administrador de subprojeto pode registrar um usuário usando o seguinte 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]

Exemplos de uso

A seguir, é apresentado um exemplo de como usar o sdutil para gerenciar os conjuntos de dados com o repositório sísmico. Esse exemplo usa sd://gtc/carbon como o recurso de subprojeto.

  # 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

Teste de ferramentas

A pasta de teste contém um conjunto de testes de integral/unidade e regressões/e2e gravados para pytest. Execute esses testes para validar as funcionalidades da ferramenta sdutil.

Use este código para requisitos:

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

Use este código para testes integrais/de unidade:

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

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

Use este código para testes de regressão:

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

Perguntas frequentes

Como posso gerar um novo comando para a ferramenta?

Execute o script de geração de comando (./command_gen.py) para gerar automaticamente a infraestrutura básica e integrar o novo comando no utilitário do sdutil. O script cria uma pasta com a infraestrutura de comando em sdlib/cmd/new_command_name.

  ./scripts/command_gen.py new_command_name

Como fazer para excluir todos os arquivos em um diretório?

Use o seguinte código:

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

Como posso gerar o changelog da ferramenta?

Execute o script de log de mudanças (./changelog-generator.sh) para gerar automaticamente o log de mudanças de utilitário:

  ./scripts/changelog-generator.sh

Uso do Gerenciador de Dados de Energia do Azure

A instância do Azure Data Manager for Energia usa a versão OSDU® M12 do sdutil. Conclua as seguintes etapas se quiser usar o sdutil para aproveitar a API do Scientific Data Management System (SDMS) da instância do Azure Data Manager for Energy:

1. Verifique se você seguiu as etapas de instalação e configuração anteriores. Isso inclui baixar o código-fonte do SDUTIL, configurar seu ambiente virtual do Python, editar o arquivo config.yaml e definir suas três variáveis de ambiente.

2. Execute os comandos a seguir para realizar tarefas no Repositório Sísmico.

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

   • Entre:

       python sdutil config init
       python sdutil auth login
     

   • Listar arquivos no Repositório Sísmico:

       python sdutil ls sd://<tenant> # For example, sd://<instance-name>-<datapartition>
       python sdutil ls sd://<tenant>/<subproject> # For example, sd://<instance-name>-<datapartition>/test
     

   • Carregar um arquivo do computador para o Repositório Sísmico:

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

   • Baixar um arquivo do Repositório Sísmico no computador local:

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

     Observação

     Não use o comando cp para baixar arquivos VDS. A conversão de VDS resulta em vários arquivos, portanto, o comando cp não poderá baixar todos eles em um comando. Use a ferramenta SEGYExport ou VDSCopy. Essas ferramentas usam uma série de chamadas REST acessando um esquema de nomenclatura para recuperar informações sobre todos os arquivos VDS resultantes.

OSDU® é uma marca registrada do The Open Group.

Próxima etapa

Prosseguir para o próximo tutorial:

Tutorial: Como trabalhar com registros de dados well usando APIs do Well Delivery DDMS