命令行工具

更新时间:2020-06-01 21:08:33

快速入门

归档存储 提供了便于用户日常操作的命令行工具 oascmd.py,该文档将通过一些简单的操作帮助用户快速熟悉 归档存储 的使用

环境要求

oascmd.py 需要 Python 2.7.x 版本支持,目前无法支持 Python 2.7 以下的版本和 Python 3。

Linux & Mac OS X

Linux 和 Mac 一般自带 Python,打开终端

  1. $ python --version

确认版本是否符合要求。如果不符合要求,请在 Python 官网的指导下安装 2.7 版本的 Python

Windows

Windows 不自带 Python,您可以从 Python 官网下载最新的 Python 2.7,推荐下载 Python 2.7.9 以上的版本,该版本会自带下面需要用到的 pip。另外建议在安装时启用 Add python.exe to Path 这个功能,如下图所示。

安装完成以后,点击 开始 -> 所有程序 -> 附件 -> 命令提示符,输入

  1. python --version

查看版本号,如果出现如下错误提示:

  1. 'python' 不是内部或外部命令,也不是可运行的程序或批处理文件。

请确认安装过程中是否启用 Add python.exe to Path,如果没有,请卸载之后重新安装,并启用该特性。

oascmd.py 只支持 Python 2.7

工具安装

oascmd.py 依托于 Python SDK,安装的过程也即 Python SDK 的安装过程,您可选择以下方式的其中一种进行安装。

  1. 使用 pip 安装

    在终端运行

    1. $ pip install oassdk

    若已安装旧版本,则运行命令进行升级安装

    1. $ pip install --upgrade oassdk
  2. 使用源码安装

    您可通过 SDK 下载页获取最新版的 Python SDK。下载完成后,把压缩包解压至指定目录。

    解压完成后,使用以下命令安装依赖以及模块,

    1. $ pip install -r requirements.txt
    2. $ python setup.py install

    即可完成Python SDK的安装。

安装过程中有可能会提示用户没有相关权限,此时可切换至管理员账号或使用 sudo 执行相关命令。

安装验证

安装成功后,您可直接在终端或者命令提示符输入

  1. oascmd.py -h

oascmd.py 会打印相关帮助信息。

同时,在终端或者命令行提示符输入python,进入 Python 控制台,输入如下命令:

  1. import oas
  2. import oas.ease

若控制台没有提示任何错误,则表示模块安装成功。

开始使用

oascmd.py能满足基本的归档存储使用需求,它包含若干子命令,子命令列表可以通过

  1. $ oascmd.py -h

来查看,每个子命令也可以通过

  1. $ oascmd.py <subcommand> -h

的方式来查看其使用方法,下面仅介绍一个常用流程,各命令的详细使用请参考各自的帮助信息或命令行帮助文档

  1. 配置oascmd.py

    第一次使用oascmd.py的时候,需要配置归档存储访问信息

    1. $ oascmd.py config --host=xxx -i <access_id> -k <access_key>

    —host 指定归档存储服务访问地址,-i 和 -k 指定用户的AccessID和AccessKey信息,该信息可以在阿里云官网账户管理页面上找到, 并请确保该账户已经开通归档存储的使用权限。

    归档存储服务访问地址详见 API 手册 2.1.1 节服务器地址.

    • 公网域名:[ RegionName ].oas.aliyuncs.com
    • 内网域名:[ RegionName ].oas-internal.aliyuncs.com

      其中,[ RegionName ]取值为: cn-hangzhou、cn-qingdao、cn-beijing、cn-hongkong等。

  2. 创建Vault

    所有的文件上传都必须指定Vault,这是访问上传内容的入口,以oascmd-test-vault为例, 使用cv子命令

    1. $ oascmd.py cv oas://oascmd-test-vault

    其中oas://前缀是作为归档存储 Vault的标识,oascmd.py所有需要指明Vault的地方都必须加上该前缀。

    ls命令可以查看已经创建的Vault列表,以及每个Vault的统计信息,但是这个统计信息并非实时,而是定期更新的。

    1. $ oascmd.py ls

    Vault列表展示的统计信息并非是实时数据

  3. 上传文件

    上传使用upload子命令,需要指明上传的目标Vault以及本地文件的路径

    每一次完整的文件上传操作对应归档存储里的一个Archive,Archive是归档存储里的另一个重要概念, 上传完成以后,oascmd.py会返回一个Archive的ID,这个ID是操作该Archive的唯一入口, 本地文件名称会默认加入到Archive的description字段,但是它不能作为检索 Archive 的依据。

    1. $ oascmd.py upload oas://oascmd-test-vault <localfile>

    Archive ID 是用户操作 Archive 的关键所在,同个文件多次上传,会产生多个不同Archive,而不是覆盖,因此文件名不能作为 Archive 操作的依据。

    如果 upload 不指定 description,默认为本地文件名,注意长度不要超过128字节,否则只取前128字节的内容。

    归档存储有一个Multipart Upload的概念,简单来说就是将一个大文件拆分成多个part进行上传, 它的好处是可以避免较大文件在上传的时候出现网络错误,而必须全部重新上传的问题, 当指定的文件大小超过100MB之后,oascmd.py会自动采用该方式进行上传,因此可能在上传文件时出现类似下面的提示:

    1. $ oascmd.py upload oas://oascmd-test-vault localfile
    2. File larger than 100MB, multipart upload will be used
    3. Use 4 parts with partsize 32.00 MB to upload
    4. MultiPartUpload ID: 8F8093C75B714C189D944A1FA9A1FA42
    5. Uploading part 1...
    6. Upload success
    7. ...
    8. Archive ID: 43FD1A7A34804D64BDA69C9BE709B12F5E2C656458B1A1100177FC9A725E94A86A954BA8C778CCD3AA218104D38D8D16

    每个Multipart Upload也会对应一个 Multipart Upload ID,如果在传输过程中由于网络中断等原因导致数据传输失败, 您可以额外提供upload命令上次返回的MultipartUpload ID, oascmd.py会根据该ID自动计算上次中断的位置,重新上传未传输完成的part。

    1. $ oascmd.py upload oas://oascmd-test-vault test-input
    2. File larger than 100MB, multipart upload will be used
    3. Use 4 parts with partsize 32.00 MB to upload
    4. MultiPartUpload ID: 16C0AAC6B6C047A0AC837DE397DF3EE5 # 注意这一行返回的ID可以用作续传
    5. Uploading part 1...
    6. Upload success
    7. Uploading part 2...
    8. Upload success
    9. Uploading part 3...
    10. ... # 网络中断发生
    11. # 在upload命令后面加上之前upload返回的 MultiPartUpload ID
    12. $ oascmd.py upload oas://oascmd-test-vault test-input 16C0AAC6B6C047A0AC837DE397DF3EE5
    13. Resume last upload with partsize 32.00 MB
    14. Uploading part 3...
    15. Upload success
    16. Uploading part 4...
    17. Upload success
    18. Archive ID: 82F1C196E7044635A56A2ABCA1AAF718EAD10923CFA9DD9E65B9894E220F27BBD01F16BAC1FB320922FC8F82D08336E1
    19. 6.379(s) elapsed

    oascmd.py 会自动根据上传文件的大小调整 part 的大小,您也可以手工指定 part 的大小:

    1. # 使用每个 part 64MB 的分段方式进行上传, part 大小必须能够被 32MB 整除
    2. $ oascmd.py upload oas://oascmd-test-vault localfile -p 64M

    文件超过100MB之后,oascmd.py 会自动启动 Multipart Upload,如果需要续传,需要显式指明Multipart Upload ID,否则全部重新上传

  4. 查询Vault的Archive列表与Archive的下载

    归档存储的Archive列表查询和Archive的下载并不是实时完成的,需要分成两个步骤来完成:首先提交一个Job, 然后等待归档存储在后台处理完成该Job之后,再进行Job的下载。

    注意Job的完成最长可能需要4小时的时间。

    Job提交时,Vault的列表获取仅需要指定Vault即可,下载Archive则需要额外提供要下载的Archive的ID

    Archive的提取支持带范围提取,通过 —start 和 —size 两个参数来控制提取的起始位置和提取数据大小

    1. # 获取Vault的Archive列表
    2. $ oascmd.py createjob oas://oascmd-test-vault
    3. # 下载Archive
    4. $ oascmd.py createjob oas://oascmd-test-vault <archive_id>
    5. # 只取出Archive前32M的数据
    6. $ oascmd.py createjob oas://oascmd-test-vault <archive_id> --size 32M
    7. # 只取Archive 64M-128M的数据
    8. $ oascmd.py createjob oas://oascmd-test-vault <archive_id> --start 64M --size 64M
    9. # 取出Archive 128M 之后的数据
    10. $ oascmd.py createjob oas://oascmd-test-vault <archive_id> --start 128M

    每次的 createjob 都会返回一个Job ID,该ID是接下来下载Job结果的访问入口

    Job提交完成以后,通过fetch子命令可以完成Job数据的下载,fetch命令会将内容下载到本地文件

    对于较大的数据,建议增加 —start 和 —size 选项来控制每次下载的数据量, 该下载范围是相对于 createjob 时指定的范围,使用方法同 createjob

    1. # 注意该Job可能需要4个小时以后才能获取到下载结果
    2. $ oascmd.py fetch oas://oascmd-test-vault <job_id> <localfile>
    3. # 只下载取出数据的前32M, 注意这个范围是相对于createjob的取出范围
    4. $ oascmd.py fetch oas://oascmd-test-vault <job_id> <localfile> --size 32M
  5. Archive的和Vault的删除

    删除一个Archive,使用rm子命令

    1. $ oascmd.py rm oas://oascmd-test-vault <archive_id>

    删除一个Vault,同样是rm,只需要指定Vault即可。

    由于归档存储是定时更新Vault的库存,因此即使您将该Vault下所有的Archive都已经删除,也不一定能够将该Vault删除掉, 一般需要一天时间才能删除该Vault,您可以通过ls命令来查看需要删除的Vault是否显示总Archive数量为0,如果是0, 则可以将该Vault删除。

    1. # 可能无法第一时间删除成功
    2. $ oascmd.py rm oas://oascmd-test-vault

更多功能

以上可能是您日常使用最多的操作,如果需要额外的功能,请参考命令行工具,它提供了所有oascmd.py支持的命令操作说明,其中包括一些更底层的命令的使用。

除了oascmd.py以外,您也可以选择手工写程序的方式,代码示例页面提供了一些使用基于 Python SDK 开发的Demo程序,您可以在此基础之上根据自身需求进行修改。Java SDK Demo请移步Java SDK实例程序

关于 归档存储 使用上遇到的一些概念,请参考 归档存储 API 手册的前两章; API 的结构调用说明,请参考该文档的后续章节;除此之外,各语言的SDK也提供了对应的SDK使用手册,Python SDK使用手册Java SDK使用手册