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

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指出的其他模組。 您可以像往一樣安裝模組，或在虛擬環境中安裝模組，以保持主機免於套件衝突。 如果您不想在虛擬環境中安裝它們，請略過下列程序代碼中的四個虛擬環境命令。 此外，如果您使用 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. 從社群azure-stable分支複製 sdutil 存放庫，並在您慣用的編輯器中開啟。

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
   

   成功登入之後，您的認證有效期為一周。 除非認證過期，否則您不需要再次登入。

   注意

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

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，請完成下列步驟：

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

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
     

     注意

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

OSDU® 是開放群組的商標。

後續步驟

前進到下一個教學課程：

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