教程：使用 sdutil 将数据加载到 Seismic Store 中

Seismic Store 是一种基于云的解决方案，用于存储和管理任何大小的数据集。 它提供了一种通过限定范围的授权机制访问数据集的安全方法。 Seismic Store 通过将常规数据集作为多个独立对象进行管理，摆脱了云服务提供商的对象大小限制。

Sdutil 是一个用于与 Seismic Store 交互的命令行 Python 工具。 可以使用 sdutil 执行基本操作，例如将数据上传到 Seismic Store、从 Seismic Store 下载数据集、管理用户和列出文件夹内容。

本教程介绍如何执行下列操作：

先决条件

根据操作系统安装以下必备组件。

Windows：

• 64 位 Python 3.8.3
• Microsoft C++ 生成工具
• Linux Subsystem 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. 将 sdlib 文件夹中 config.yaml 的内容替换为以下 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. 从解压缩的 utility 文件夹中运行 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
   

   成功登录后，你的凭据将在一周内保持有效。 除非凭据过期，否则无需再次登录。

   注意

   如果未看到有关成功登录的消息，请确保已设置三个环境变量，并且已按照本教程前面的配置部分中的所有步骤操作。

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，必须至少将用户注册到一个子项目资源并为其分配一个用于定义其访问级别的角色。 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-generator.sh) 以自动生成工具更改日志：

  ./scripts/changelog-generator.sh

Azure Data Manager for Energy 的用法

Azure Data Manager for Energy 实例使用 sdutil 的 OSDU® M12 版本。 如果要使用 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® 是 Open Group 的商标。

下一步

转到下一教程：