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

  • Статья

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

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

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

  • Настройте и запустите средство sdutil.
  • ПОЛУЧИТЕ универсальный код ресурса (URI) в хранилище сейсмических данных.
  • Создайте вложенный проект.
  • Зарегистрируйте пользователя.
  • Используйте sdutil для управления наборами данных с помощью Хранилища сейсмических данных.
  • Выполните тесты, чтобы проверить функциональные возможности средства sdutil.

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

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

Windows:

Linux:

Unix/Mac

Для 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.yamlsdlib папки следующим 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.

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

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

Руководство. Работа с хорошо записями данных с помощью API-интерфейсов DDMS для доставки