チュートリアル: sdutil を使用して Seismic Store にデータを読み込む

Seismic Store は、任意のサイズのデータセットを格納および管理するためのクラウドベースのソリューションです。 そこでは、スコープを使った認可メカニズムによって、データセットにアクセスするための安全な方法が提供されます。 Seismic Store は、汎用データセットを複数の独立したオブジェクトとして管理して、クラウド プロバイダーのオブジェクト サイズの制限を克服します。

Sdutil は、Seismic Store を操作するためのコマンド ライン Python ツールです。 sdutil を使うと、Seismic Store へのデータのアップロード、Seismic Store からのデータセットのダウンロード、ユーザーの管理、フォルダーの内容の一覧表示などの基本的な操作を実行できます。

このチュートリアルでは、次の作業を行う方法について説明します。

• sdutil ツールを設定して実行する。
• Seismic Store の URI を取得する。
• サブプロジェクトを作成する。
• ユーザーを登録します。
• sdutil を使って Seismic Store でデータセットを管理する。
• テストを実行して sdutil ツールの機能を検証する。

前提条件

お使いのオペレーティング システムに基づいて、次の前提条件をインストールします。

Windows:

• 64 ビット Python 3.8.3
• Microsoft C++ Build Tools
• Linux サブシステム Ubuntu

Linux:

• 64 ビット Python 3.8.3

Unix/Mac

• 64 ビット Python 3.8.3
• Apple Xcode C++ ビルド ツール

sdutil には、requirements.txt で示されている他のモジュールが必要です。 モジュールをそのままインストールすることも、仮想環境にインストールして、ホストをパッケージの競合からクリーンに保つこともできます。 仮想環境にインストールしない場合は、次のコードの 4 つの仮想環境コマンドをスキップしてください。 さらに、Ubuntu または WSL - Ubuntu 20.04 ではなく Mac をお使いの場合は、パッケージ マネージャーとして apt-get ではなく homebrew を使うか、手動で 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. コミュニティの azure-stable ブランチから sdutil リポジトリをクローンして、任意のエディターで開きます。

2. sdlib フォルダー内の config.yaml の内容を、次の YAML に置き換えます。 3 つのテンプレート化された値 (<meds-instance-url> の 2 つのインスタンスと <put refresh token here...> の 1 つのインスタンス) を入力します。

   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'
   

   Note

   トークンがまだない場合は、認証トークンの生成方法に関する記事の手順に従って取得します。

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 によって Web ブラウザーにサインイン ページが開かれます。

     python sdutil auth login
   

   正常にサインインした後、資格情報は 1 週間有効になります。 資格情報の有効期限が切れない限り、もう一度サインインする必要はありません。

   Note

   サインインが成功したことを示すメッセージが表示されない場合は、3 つの環境変数が設定されていることと、このチュートリアルで前に出てきた「構成」セクションのすべての手順を行ったことを確認してください。

Seismic Store のリソース

システムを使い始める前に、Seismic Store によるリソースの管理方法を理解しておくことが重要です。 Seismic Store では、次の 3 種類のリソースが管理されます。

• テナント プロジェクト: メイン プロジェクト。 テナントは、Seismic Store のパスの最初のセクションです
• サブプロジェクト: 作業サブプロジェクト。メイン テナント プロジェクトの下に直接リンクされています。 サブプロジェクトは、Seismic Store のパスの 2 番目のセクションです。
• データセット: データセット エンティティ。 データセットは、Seismic Store のパスの 3 番目で最後のセクションです。 path/dataset_name という形式を使って、データセット リソースを指定できます。 その形式で、path は省略可能であり、汎用ファイル システムのディレクトリと同じ意味を持ちます。 dataset_name の部分は、データセット エンティティの名前です。

Seismic Store の URI は文字列であり、それを使ってシステム内のリソースを一意にアドレス指定します。 これを取得するには、必要なリソース パスにプレフィックス sd:// を追加します。

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

たとえば、gtc テナント プロジェクトの下の carbon サブプロジェクト内の qadata/ustest ディレクトリ構造に results.segy データセットが格納されている場合、対応する sdpath のコードは次のようになります。

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

対応する sdpath セクションを使用して、すべてのリソースをアドレス指定できます

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

Subprojects

Seismic Store のサブプロジェクトは、ユーザーがデータセットを保存できる作業単位です。 システムは、テナント プロジェクトの下で複数のサブプロジェクトを処理できます。

次の 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

[ユーザー管理]

Seismic Store を使用できるようにするには、アクセス レベルが定義されているロールを使って、少なくともサブプロジェクト リソースにユーザーを登録する必要があります。 Seismic Store では、サブプロジェクト レベルでスコープ指定された 2 つのロールがサポートされています。

• 管理者: 読み取り/書き込みアクセスとユーザー管理。
• 閲覧者: 読み取り/一覧表示アクセス。

次の 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 を使って Seismic Store でデータセットを管理する方法の例です。 この例では、サブプロジェクト リソースとして 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 for Energy の使用状況

Azure Data Manager for Energy インスタンスでは、OSDU® M12 バージョンの sdutil が使われています。 sdutil を使って Azure Data Manager for Energy インスタンスの Scientific Data Management System (SDMS) API を利用する場合は、次の手順のようにします。

1. 前のインストールと構成のステップのようにしていることを確認します。 これらの手順には、sdutil のソース コードのダウンロード、Python 仮想環境の構成、config.yaml ファイルの編集、3 つの環境変数の設定が含まれます。

2. Seismic Store でタスクを行うには、次のコマンドを実行します。

   • 初期化する：

       (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
     

   • 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
     

   • ローカル コンピューターから Seismic Store にファイルをアップロードする:

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

   • Seismic Store からローカル コンピューターにファイルをダウンロードする:

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

     Note

     VDS ファイルのダウンロードには、cp コマンドを使わないでください。 VDS 変換では複数のファイルが作成され、cp コマンドでは、それらのすべてを 1 つのコマンドでダウンロードできません。 代わりに SEGYExport または VDSCopy ツールを使用してください。 これらのツールでは、名前付けスキームにアクセスして、結果のすべての VDS ファイルに関する情報を取得する、一連の REST 呼び出しが使われます。

OSDU® は The Open Group の商標です。

次のステップ

次のチュートリアルに進みます。

チュートリアル: Well Delivery DDMS API を使用してウェル データ レコードを操作する