Руководство по использованию sdutil для загрузки данных в Сейсмическое хранилище

Сейсмическое хранилище — это облачное решение для хранения и управления наборами данных любого размера. Он предоставляет безопасный способ доступа к наборам данных через механизм авторизации область. Сейсмическое хранилище преодолевает ограничения размера объектов поставщиков облачных служб путем управления универсальными наборами данных в виде нескольких независимых объектов.

Sdutil — это средство Python командной строки для взаимодействия с Сейсмическим хранилищем. Вы можете использовать sdutil для выполнения основных операций, таких как отправка данных в Сейсмическое хранилище, скачивание наборов данных из Сейсмического хранилища, управление пользователями и перечисление содержимого папки.

В этом руководстве описано следующее:

Необходимые компоненты

Установите следующие предварительные требования на основе операционной системы.

Windows:

• 64-разрядная версия Python 3.8.3
• Microsoft C++ Build Tools
• Ubuntu подсистемы Linux

Linux:

• 64-разрядная версия Python 3.8.3

Unix/Mac

• 64-разрядная версия Python 3.8.3
• Средства сборки Apple Xcode C++

Для sdutil требуются другие модули, отмеченные в requirements.txt. Вы можете установить модули как есть или установить их в виртуальной среде, чтобы обеспечить очистку узла от конфликтов пакетов. Если вы не хотите устанавливать их в виртуальной среде, пропустите четыре команды виртуальной среды в следующем коде. Кроме того, если вы используете Mac вместо Ubuntu или WSL — Ubuntu 20.04, используйте homebrew вместо apt-get диспетчера пакетов или вручную установите 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

Установите необходимые зависимости:

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

Использование

Настройка

1. Клонируйте репозиторий sdutil из ветви сообщества azure-stable и откройте его в избранном редакторе.

2. Замените содержимое config.yaml sdlib папки следующим yamL. Заполните три шаблонных значения (два экземпляра <meds-instance-url> и один экземпляр <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'
   

   Примечание.

   Если маркер еще не присутствует, получите его, следуя указаниям в руководстве по созданию маркера проверки подлинности.

3. Экспорт или установка следующих переменных среды:

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

Запуск инструмента

1. Запустите средство sdutil из извлеченной папки служебной программы:

     python sdutil
   

   Если аргументы не указаны, откроется следующее меню:

     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. Если вы впервые используете средство, выполните sdutil config init команду, чтобы инициализировать конфигурацию:

     python sdutil config init
   

3. Прежде чем начать использовать средство и выполнять любые операции, необходимо войти в систему. При выполнении следующей команды sdutil открывает страницу входа в веб-браузере:

     python sdutil auth login
   

   После успешного входа учетные данные действительны в течение недели. Если срок действия учетных данных не истекает, вам не нужно повторно входить.

   Примечание.

   Если вы не получаете сообщение об успешном входе, убедитесь, что заданы три переменных среды и выполнены все действия, описанные в разделе "Конфигурация" ранее в этом руководстве.

Ресурсы Сейсмического хранилища

Прежде чем приступить к использованию системы, важно понять, как Сейсмическое хранилище управляет ресурсами. Сейсмическое хранилище управляет тремя типами ресурсов:

• Проект клиента: основной проект. Клиент является первым разделом пути к Хранилищу сейсмических данных.
• Вложенный проект: рабочий подпроект, связанный непосредственно подпроектом основного клиента. Подпроект является вторым разделом пути к сейсмическим магазинам.
• Набор данных: сущность набора данных. Набор данных — это третий и последний раздел пути к хранилищу сейсмических данных. Ресурс набора данных можно указать с помощью формы path/dataset_name. В этой форме является необязательным и имеет то же значение, path что и каталог в универсальной файловой системе. Часть dataset_name — это имя сущности набора данных.

URI Хранилища сейсмических данных — это строка, используемая для уникального решения ресурса в системе. Его можно получить, добавив префикс sd:// в требуемый путь к ресурсу:

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

Например, если у вас есть results.segy набор данных, хранящийся в qadata/ustest структуре каталога в carbon подпроекте gtc клиента, соответствующий sdpath код:

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

Вы можете обратиться к каждому ресурсу с помощью соответствующего sdpath раздела:

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

Подпроекты

Подпроект в Хранилище сейсмических данных — это рабочая единица, в которой пользователь может сохранять наборы данных. Система может обрабатывать несколько вложенных проектов в проекте клиента.

Только администратор клиента может создать ресурс подпроекта с помощью следующей команды 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

Управление пользователями

Чтобы иметь возможность использовать Сейсмическое хранилище, пользователи должны быть зарегистрированы по крайней мере в подпроектном ресурсе с ролью, определяющей уровень доступа. Сейсмическое хранилище поддерживает две роли, область на уровне подпроекта:

• Администратор: доступ на чтение и запись и управление пользователями.
• Средство просмотра: доступ для чтения и списка.

Только администратор подпроекта может зарегистрировать пользователя с помощью следующей команды 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]

Примеры использования

В следующем коде приведен пример использования sdutil для управления наборами данных с помощью Сейсмического хранилища. В этом примере используется sd://gtc/carbon в качестве ресурса подпроекта.

  # 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

Тестирование инструментов

В тестовой папке содержится набор тестов целочисленного или единицного и регрессионных тестов, написанных для pytest. Выполните эти тесты, чтобы проверить функциональные возможности средства sdutil.

Используйте этот код для требований:

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

Используйте этот код для целых и модульных тестов:

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

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

Используйте этот код для тестов регрессии:

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

Вопросы и ответы

Как создать новую команду для средства?

Запустите скрипт создания команд (./command_gen.py), чтобы автоматически создать базовую инфраструктуру для интеграции новой команды в средство sdutil. Сценарий создает папку с инфраструктурой команд в sdlib/cmd/new_command_name.

  ./scripts/command_gen.py new_command_name

Как удалить все файлы в каталоге?

Используйте следующий код:

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

Как создать журнал изменений средства?

Запустите скрипт журнала изменений (./changelog-generator.sh) для автоматического создания журнала изменений средства:

  ./scripts/changelog-generator.sh

Использование для Azure Data Manager для энергетики

Экземпляр Azure Data Manager для энергетики использует версию SDutil OSDU® M12. Выполните следующие действия, если вы хотите использовать sdutil для использования API научной Управление данными системы (SDMS) экземпляра Azure Data Manager для энергетики:

1. Убедитесь, что вы выполнили предыдущие действия по установке и настройке . Эти действия включают загрузку исходного кода sdutil, настройку виртуальной среды Python, редактирование config.yaml файла и настройку трех переменных среды.

2. Выполните следующие команды, чтобы выполнять задачи в Сейсмическом хранилище.

   • Инициализации:

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

   • Вход.

       python sdutil config init
       python sdutil auth login
     

   • Вывод списка файлов в Хранилище Сейсмических данных:

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

   • Отправьте файл с локального компьютера в Хранилище Сейсмических данных:

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

   • Скачайте файл из Хранилища сейсмических данных на локальный компьютер:

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

     Примечание.

     Не используйте cp команду для скачивания файлов VDS. Преобразование VDS приводит к нескольким файлам, поэтому cp команда не сможет скачать все из них в одной команде. Вместо этого используйте средство SEGYExport или VDSCopy. Эти средства используют ряд вызовов REST, которые обращаются к схеме именования для получения сведений обо всех полученных файлах VDS.

OSDU® — это товарный знак Open Group.

Следующий шаг

Перейдите к следующему руководству: