Partilhar via

Tutorial: Usar sdutil para carregar dados no Repositório Sísmico

  • Artigo

A Seismic Store é uma solução baseada na nuvem para armazenar e gerir 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 Seismic Store supera as limitações de tamanho de objeto dos provedores de nuvem gerenciando conjuntos de dados genéricos como vários objetos independentes.

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

Neste tutorial, irá aprender a:

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

Pré-requisitos

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

Windows:

Linux:

Unix/Mac

Sdutil requer outros módulos anotados em requirements.txt. Você pode instalar os módulos como estão ou instalá-los em um ambiente virtual para manter seu host limpo de conflitos de pacote. Se você não quiser instalá-los em um ambiente virtual, ignore os quatro comandos de ambiente virtual no código a seguir. Além disso, se você estiver usando Mac em vez de Ubuntu ou WSL - Ubuntu 20.04, use homebrew em vez de como seu gerenciador de apt-get pacotes, ou instale apt-getmanualmente o .

  # 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

Utilização

Configuração

  1. Clone o repositório sdutil da ramificação da comunidade azure-stable e abra no seu editor favorito.

  2. Substitua o conteúdo de config.yaml na pasta com o sdlib seguinte YAML. Preencha os três valores templatizados (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'

    Nota

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

  3. Exporte ou 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>

Executando a ferramenta

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

      python sdutil

    Se você não especificar nenhum argumento, este 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 sdutil config init comando para inicializar a configuração:

      python sdutil config init

  3. Antes de começar a usar a ferramenta e executar quaisquer operações, você deve 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 iniciar sessão com êxito, as suas credenciais são válidas durante uma semana. Você não precisa entrar novamente, a menos que as credenciais expirem.

    Nota

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

Recursos da Loja Sísmica

Antes de começar a usar o sistema, é importante entender como a Seismic Store gerencia os recursos. A Loja Sísmica gere três tipos de recursos:

  • Projeto do inquilino: O projeto principal. O inquilino é a primeira seção do caminho da Loja Sísmica.
  • Subprojeto: O subprojeto de trabalho, que está diretamente ligado no projeto do locatário principal. O subprojeto é a segunda seção do caminho da Loja Sísmica.
  • 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 de conjunto de dados usando o formulário path/dataset_name. Nessa forma, path é opcional e tem o mesmo significado que um diretório em um sistema de arquivos genérico. A dataset_name parte é o nome da entidade do conjunto de dados.

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

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

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

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

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

  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 onde um usuário pode salvar conjuntos de dados. O sistema pode lidar com 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

Gestão de utilizadores

Para poder usar o Repositório Sísmico, os usuários devem estar registrados em pelo menos um recurso de subprojeto com uma função que defina seu nível de acesso. O armazenamento sísmico suporta duas funções com escopo no nível do subprojeto:

  • Admin: Acesso de leitura/gravação e gerenciamento de usuários.
  • Visualizador: Acesso de leitura/lista.

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 utilização

O código a seguir é um exemplo de como usar sdutil para gerenciar conjuntos de dados com o Seismic Store. Este 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 integrais/unitários e de regressão escritos 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/unitários:

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

FAQ

Como posso gerar um novo comando para a ferramenta?

Execute o script de geração de comandos (./command_gen.py) para gerar automaticamente a infraestrutura base para integrar um novo comando na ferramenta 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 posso excluir todos os arquivos em um diretório?

Utilize 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 changelog (./changelog-generator.sh) para gerar automaticamente o changelog da ferramenta:

  ./scripts/changelog-generator.sh

Utilização do Azure Data Manager for Energy

A instância do Azure Data Manager for Energy usa a versão OSDU® M12 do sdutil. Conclua as etapas a seguir se quiser usar o sdutil para aproveitar a API do Sistema de Gerenciamento de Dados Científicos (SDMS) da sua instância do Azure Data Manager for Energy:

  1. Certifique-se de que seguiu os passos de instalação e configuração anteriores. Essas etapas incluem baixar o código-fonte sdutil, configurar seu ambiente virtual Python, editar o config.yaml arquivo e definir suas três variáveis de ambiente.

  2. Execute os seguintes comandos para executar tarefas no 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.

    • Iniciar sessão:

        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

    • Carregue um ficheiro da sua máquina local para a Loja Sísmica:

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

    • Transfira um ficheiro da Loja Sísmica para a sua máquina local:

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

      Nota

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

OSDU® é uma marca comercial do The Open Group.

Próximo passo

Avance para o tutorial seguinte:

Tutorial: Trabalhar com registros de dados de poço usando APIs DDMS de entrega de poço