教學課程：使用 sdutil 將數據載入地震存放區

文章
02/02/2024

Seismic Store 是一種雲端式解決方案，可用於儲存和管理任何大小的數據集。它提供安全的方式，可透過限定範圍的授權機制存取數據集。 Seismic Store 藉由將一般數據集管理為多個獨立對象，藉以克服雲端提供者的物件大小限制。

Sdutil 是與 Seismic Store 互動的命令行 Python 工具。您可以使用 sdutil 來執行基本作業，例如將數據上傳至 Seismic Store、從 Seismic Store 下載數據集、管理使用者，以及列出資料夾內容。

在本教學課程中，您會了解如何：

設定並執行 sdutil 工具。
取得 Seismic Store URI。
建立子專案。
註冊使用者。
使用 sdutil 搭配 Seismic Store 管理數據集。
執行測試來驗證 sdutil 工具的功能。

必要條件

根據您的作業系統安裝下列必要條件。

Windows：

Linux：

64 位 Python 3.8.3

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

使用方式

組態

從社群azure-stable分支複製 sdutil 存放庫，並在您慣用的編輯器中開啟。

將資料夾中的內容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'

注意

如果令牌尚未存在，請遵循如何產生驗證令牌中的指示取得令牌。

匯出或設定下列環境變數：

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

執行工具

從擷取的公用程式資料夾執行 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

如果這是您第一次使用此工具，請執行 sdutil config init 命令來初始化組態：
```
  python sdutil config init
```
開始使用工具並執行任何作業之前，您必須登入系統。當您執行下列命令時，sdutil 會在網頁瀏覽器中開啟登入頁面：
```
  python sdutil auth login
```
成功登入之後，您的認證有效期為一周。除非認證過期，否則您不需要再次登入。

注意

如果您未收到有關成功登入的訊息，請確定已設定您的三個環境變數，並遵循本教學課程稍早的設定一節中的所有步驟。

Seismic Store 資源

開始使用系統之前，請務必瞭解 Seismic Store 如何管理資源。 Seismic Store 會管理三種類型的資源：

租用戶專案：主要專案。租使用者是 Seismic Store 路徑的第一個區段。
子專案：主要租用戶專案下直接連結的工作子專案。子專案是 Seismic Store 路徑的第二個區段。
數據集：數據集實體。數據集是 Seismic Store 路徑的第三個和最後一個區段。您可以使用表單 path/dataset_name來指定資料集資源。在該表單中，是選擇性的， path 而且與一般文件系統中的目錄具有相同的意義。元件 dataset_name 是數據集實體的名稱。

Seismic Store URI 是用來唯一尋址系統中資源的字串。您可以將前置詞 sd:// 附加至所需的資源路徑，以取得它：

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

例如，如果您的results.segy數據集儲存在qadata/ustest租用戶專案下的gtc子專案中的目錄結構carbon中，對應的sdpath程式代碼為：

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

您可以使用對應的 sdpath 區段來解決每個資源：

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

子專案

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，用戶必須至少註冊至子項目資源，且具有定義其存取層級的角色。地震存放區支援在子專案層級設定的兩個角色：

管理員：讀取/寫入存取權和使用者管理。
查看器：讀取/清單存取權。

只有子專案管理員可以使用下列 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 文稿（./changelog-generator.sh）以自動產生工具的變更記錄：

  ./scripts/changelog-generator.sh

適用於能源的 Azure Data Manager 使用量

適用於能源的 Azure 數據管理員實例會使用 OSDU® M12 版本的 sdutil。如果您想要使用 sdutil 來利用 Azure Data Manager for Energy 實例的科學資料管理系統（SDMS） API，請完成下列步驟：

請確定您已遵循先前的安裝和設定步驟。這些步驟包括下載 sdutil 原始程式碼、設定 Python 虛擬環境、編輯檔案，以及設定您的三個 config.yaml 環境變數。

執行下列命令，以在 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
```
注意

請勿使用 cp 命令來下載 VDS 檔案。 VDS 轉換會產生多個檔案，因此 cp 命令將無法在一個命令中下載所有檔案。請改用 SEGYExport 或 VDSCopy 工具。這些工具會使用一系列的 REST 呼叫來存取命名配置，以擷取所有產生的 VDS 檔案的相關信息。

OSDU® 是開放群組的商標。

後續步驟

前進到下一個教學課程：

教學課程：使用良好傳遞 DDMS API 來處理良好的數據記錄

分享方式：