归档存储的命令行工具

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

环境要求


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

Linux & Mac OS X


Linux 和 Mac 一般自带 Python，打开终端$ python --version
确认版本是否符合要求。如果不符合要求，请在 Python 官网的指导下安装 2.7 版本的 Python

Windows


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

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

查看版本号，如果出现如下错误提示： 'python' 不是内部或外部命令，也不是可运行的程序或批处理文件。

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

oascmd.py 只支持 Python 2.7

工具安装


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

1. 
   使用 pip 安装
   在终端运行$ pip install oassdk

若已安装旧版本，则运行命令进行升级安装 $ pip install --upgrade oassdk

使用源码安装
您可通过 SDK 下载页获取最新版的 Python SDK。下载完成后，把压缩包解压至指定目录。
解压完成后，使用以下命令安装依赖以及模块， $ pip install -r requirements.txt
$ python setup.py install

即可完成Python SDK的安装。

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

安装验证


安装成功后，您可直接在终端或者命令提示符输入 oascmd.py -h

oascmd.py 会打印相关帮助信息。
同时，在终端或者命令行提示符输入python，进入 Python 控制台，输入如下命令： import oas
import oas.ease

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

开始使用


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

来查看，每个子命令也可以通过 $ oascmd.py <subcommand> -h

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

1. 
   配置oascmd.py
   第一次使用oascmd.py的时候，需要配置归档存储访问信息 $ 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等。

创建Vault
所有的文件上传都必须指定Vault，这是访问上传内容的入口，以oascmd-test-vault为例, 使用cv子命令 $ oascmd.py cv oas://oascmd-test-vault

其中oas://前缀是作为归档存储 Vault的标识，oascmd.py所有需要指明Vault的地方都必须加上该前缀。
ls命令可以查看已经创建的Vault列表，以及每个Vault的统计信息，但是这个统计信息并非实时，而是定期更新的。 $ oascmd.py ls

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

上传文件
上传使用upload子命令，需要指明上传的目标Vault以及本地文件的路径
每一次完整的文件上传操作对应归档存储里的一个Archive，Archive是归档存储里的另一个重要概念， 上传完成以后，oascmd.py会返回一个Archive的ID，这个ID是操作该Archive的唯一入口， 本地文件名称会默认加入到Archive的description字段，但是它不能作为检索 Archive 的依据。 $ oascmd.py upload oas://oascmd-test-vault <localfile>

Archive ID 是用户操作 Archive 的关键所在，同个文件多次上传，会产生多个不同 Archive，而不是覆盖，因此文件名不能作为 Archive 操作的依据。
如果 upload 不指定 description，默认为本地文件名，注意长度不要超过128字节， 否则只取前128字节的内容。

归档存储有一个Multipart Upload的概念，简单来说就是将一个大文件拆分成多个part进行上传， 它的好处是可以避免较大文件在上传的时候出现网络错误，而必须全部重新上传的问题， 当指定的文件大小超过100MB之后，oascmd.py会自动采用该方式进行上传，因此可能在上传文件时出现类似下面的提示： $ oascmd.py upload oas://oascmd-test-vault localfile
File larger than 100MB, multipart upload will be used
Use 4 parts with partsize 32.00 MB to upload
MultiPartUpload ID: 8F8093C75B714C189D944A1FA9A1FA42
Uploading part 1...
Upload success
...
Archive ID: 43FD1A7A34804D64BDA69C9BE709B12F5E2C656458B1A1100177FC9A725E94A86A954BA8C778CCD3AA218104D38D8D16

每个Multipart Upload也会对应一个 Multipart Upload ID，如果在传输过程中由于网络中断等原因导致数据传输失败， 您可以额外提供upload命令上次返回的MultipartUpload ID， oascmd.py会根据该ID自动计算上次中断的位置，重新上传未传输完成的part。 $ oascmd.py upload oas://oascmd-test-vault test-input
File larger than 100MB, multipart upload will be used
Use 4 parts with partsize 32.00 MB to upload
MultiPartUpload ID: 16C0AAC6B6C047A0AC837DE397DF3EE5    # 注意这一行返回的ID可以用作续传
Uploading part 1...
Upload success
Uploading part 2...
Upload success
Uploading part 3...
... # 网络中断发生

# 在upload命令后面加上之前upload返回的 MultiPartUpload ID
$ oascmd.py upload oas://oascmd-test-vault test-input 16C0AAC6B6C047A0AC837DE397DF3EE5
Resume last upload with partsize 32.00 MB
Uploading part 3...
Upload success
Uploading part 4...
Upload success
Archive ID: 82F1C196E7044635A56A2ABCA1AAF718EAD10923CFA9DD9E65B9894E220F27BBD01F16BAC1FB320922FC8F82D08336E1
6.379(s) elapsed

oascmd.py 会自动根据上传文件的大小调整 part 的大小，您也可以手工指定 part 的大小: # 使用每个 part 64MB 的分段方式进行上传, part 大小必须能够被 32MB 整除
$ oascmd.py upload oas://oascmd-test-vault localfile -p 64M

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

查询Vault的Archive列表与Archive的下载
归档存储的Archive列表查询和Archive的下载并不是实时完成的，需要分成两个步骤来完成：首先提交一个Job， 然后等待归档存储在后台处理完成该Job之后，再进行Job的下载。
注意Job的完成最长可能需要[backcolor=transparent]4小时的时间。
Job提交时，Vault的列表获取仅需要指定Vault即可，下载Archive则需要额外提供要下载的Archive的ID
Archive的提取支持带范围提取，通过 --start 和 --size 两个参数来控制提取的起始位置和提取数据大小 # 获取Vault的Archive列表
$ oascmd.py createjob oas://oascmd-test-vault

# 下载Archive
$ oascmd.py createjob oas://oascmd-test-vault <archive_id>

# 只取出Archive前32M的数据
$ oascmd.py createjob oas://oascmd-test-vault <archive_id> --size 32M

# 只取Archive 64M-128M的数据
$ oascmd.py createjob oas://oascmd-test-vault <archive_id> --start 64M --size 64M

# 取出Archive 128M 之后的数据
$ oascmd.py createjob oas://oascmd-test-vault <archive_id> --start 128M

每次的 createjob 都会返回一个Job ID，该ID是接下来下载Job结果的访问入口
Job提交完成以后，通过fetch子命令可以完成Job数据的下载，fetch命令会将内容下载到本地文件
对于较大的数据，建议增加 --start 和 --size 选项来控制每次下载的数据量， 该下载范围是相对于 createjob 时指定的范围，使用方法同 createjob # 注意该Job可能需要4个小时以后才能获取到下载结果
$ oascmd.py fetch oas://oascmd-test-vault <job_id> <localfile>

# 只下载取出数据的前32M, 注意这个范围是相对于createjob的取出范围
$ oascmd.py fetch oas://oascmd-test-vault <job_id> <localfile> --size 32M

Archive的和Vault的删除
删除一个Archive，使用rm子命令 $ oascmd.py rm oas://oascmd-test-vault <archive_id>

删除一个Vault，同样是rm，只需要指定Vault即可。
由于归档存储是定时更新Vault的库存，因此即使您将该Vault下所有的Archive都已经删除，也不一定能够将该Vault删除掉， 一般需要一天时间才能删除该Vault，您可以通过ls命令来查看需要删除的Vault是否显示总Archive数量为0，如果是0， 则可以将该Vault删除。 # 可能无法第一时间删除成功
$ 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使用手册。