快速入门

归档存储提供了便于用户日常操作的命令行工具 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 的安装过程，您可选择以下方式的其中一种进行安装。

使用 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

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

配置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的完成最长可能需要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
```