归档存储的命令行工具

oascmd.py 是 Python SDK 提供给用户的一个快捷的命令行测试工具，除了提供方便用户快捷使用的命令以外，还有分别与 归档存储 API 文档描述的接口一一对应的底层命令。
其中，[]内的参数为可选参数。字符串前缀 oas:// 仅仅作为资源标识，没有其他含义。除了特别说明外，所有结果均直接输出至命令行，输出结果为友好的自解释可读文本，因此下文不再对 oascmd.py 输出进行详细说明。

授权设置


oascmd.py 使用前需要进行授权信息的配置

格式


[backcolor=transparent] config [-h] --host host --id id --key key [--port port] [--config-file filename]

说明


配置用户的个人授权信息。

• 
  --host host
  必选。用户所使用的目标 Region 域名，详见 API 手册 2.1.1 节服务器地址。
• 
  -p port, --port port
  可选。用户所使用的目标 Region 地址，默认为 80。
• 
  -i id, --id id
  必选。用户的 Access Key ID。
• 
  -k key, --key key
  必选。用户的 Access Key Secret。
• 
  --config-file
  可选。配置信息保存的文件路径，默认保存在用户目录下的 .oascredentials。

示例oascmd.py config --host cn-hangzhou.oas.aliyuncs.com -i my_id -k my_key
oascmd.py config --host cn-hangzhou.oas.aliyuncs.com --id my_id --key my_key
oascmd.py config --host cn-hangzhou.oas.aliyuncs.com --id my_id --key my_key --config-file .oasconfig




公共选项


为了支持多节点、多帐号的用户使用，oascmd.py 将授权配置的配置项也作为公共选项，支持到所有的子命令（除help）
同 config 相比，这些公共选项的要求有以下几点不同：

1. 
   所有的参数均为可选，如果用户未提供这些选项，则默认从用户目录的 .oascredentials 读取配置，以ls为例 # 从 ~/.oascredentials 读取配置
2. oascmd.py ls
4. # 从 ~/.oascredentials 读取配置，但是需要访问其他 host
5. oascmd.py ls --host=<another-host>
7. # 从 ~/.oascredentials 读取配置，但是用其他 AccessId/AccessKey 来访问
8. oascmd.py ls -i <another-id> -k <another-key>

--config-file 的意义是用于指定读取配置的文件路径 # 从当前目录的 .oasconfig 文件读取访问配置
oascmd.py ls --config-file .oasconfig

如果同时指定 --config-file 和其他4个选项中的任意一个，则优先选择输入的配置，未指定的配置再由配置文件读取。 比如多 Region 的时候，如果 AccessId/AccessKey 不需要变化，可以通过以下方式来完成： oascmd.py ls --host=<another_host> --config-file <config-path>

除 config 和 help 以外，其他子命令都可以指定不同的 region 或账户

基础操作



创建 Vault



格式


[backcolor=transparent] cv(createvault) [-h] oas://vaultname

说明


创建名为 vaultname 的 Vault

• vaultname

必选，Vault 名称，必须加 oas:// 的前缀

示例oascmd.py cv oas://vaultname
oascmd.py createvault oas://vaultname




列出所有 Vault



格式


[backcolor=transparent] ls(listvault) [-h] [--limit limit] [--marker marker]

说明


列出已经创建的 Vault，以及各 Vault 的统计信息。Vault 的统计信息是由 归档存储 定期更新生成的，并非实时数据。

• --limit limit

可选，列出的Vault总数上限

• --marker marker

可选，显示的 Vault 列表非全部的 Vault 时，ls 会返回一个非空的 marker，该 marker 可以作为 ls 的参数， 用来取出其他未显示的 Vault 列表

各 Vault 的统计信息并非实时生成。

示例oascmd.py ls
oascmd.py listvault
oascmd.py ls --limit 3
oascmd.py ls --marker <Marker_last_ls_returned> --limit 1




上传文件



格式


[backcolor=transparent] upload [-h] [--desc DESC] [-p PART_SIZE] oas://vaultname filename [uploadid]

说明


上传本地文件到指定 Vault，每一个完整上传的文件都对应 归档存储 里面的一个 Archive，每个 Archive 都会用唯一的 Archive ID 来标识， 所有储存在 归档存储 里的文件都必须通过该 Archive ID 才能访问，同名文件多次上传会生成多个 Archive，并不会产生覆盖操作。
如果本地文件较大（超过 100MB），upload 命令会自动采用 Multipart Upload 的方式， 并将 Multipart Upload ID 输出。
uploadid 可以用作续传，每次启用 Multipart Upload 的时候，upload 都会返回给用户一个 MultiPart Upload ID，当前一次传输出现中断的时候， 可以在前一次命令的基础之上，提供该ID，oascmd.py 会自动根据该ID定位上到上次中断的位置，并根据上次的分段大小继续上传。

• vaultname

必选，保存文件的 Vault 的名称，必须包含 oas:// 前缀

• filename

必选，本地文件名

• uploadid

可选，用于文件续传。当 upload 启用 Multipart Upload 上传方式时，由网络中断等原因引起的上传失败，可以在重新上传时指定 upload 输出的 Multipart Upload ID，继续完成上次未完成的操作。未指定则上传整个文件

• --desc desc

可选，Archive 的描述信息，不指定则默认为文件名，超过 128 字节长度，只取前 128 字节内容。

• -p PART_SIZE, --part-size PART_SIZE

可选，Multipart Upload 时指定的分段大小，不指定则由 oascmd.py 自动计算，分段大小必须在 32MB 到 4GB的范围（包括两端）， 且满足 2^N，其中N是正整数，PART_SIZE支持带单位的输入，且各单位不区分大小写（不包括B），如 32M, 64M, 128MB 等。
如果指定的 PART_SIZE 与文件大小不匹配，oascmd.py会自动忽略该配置，如文件大小小于 32MB，即使指定该选项，仍会被 oascmd.py 忽略，选择直接上传。
续传时该选项会被忽略，不论是否指定新的 PART_SIZE。

同名文件的多次上传会产生多个 Archive，并不会产生覆盖操作，因此文件名不能用于 Archive 的检索
续传功能需要显式指明 Multipart Upload ID，否则全部重新上传。

示例oascmd.py upload oas://vaultname local_file
oascmd.py upload oas://vaultname local_file -p 64M
oascmd.py upload oas://vaultname local_file --desc "description of the file"




删除 Archive 或 Vault



格式


[backcolor=transparent] rm [-h] oas://vaultname [archiveId]

说明


删除指定的 Vault，或者 archiveId 对应的 Archive。
归档存储 的 Vault 统计信息是定期更新的，只有当所有的 Archive 都被删除，且 ls 显示 Vault 统计信息里 Archive的总数为 0，Vault 才能够成功删除。 其他情况下，删除 Vault 操作会被 归档存储 拒绝。

• vaultnane

必选，需要删除的 Vault 或 Archive 所在的 Vault 的名称，必须包含 oas:// 前缀。

• archiveId

可选，未指定则是删除整个 Vault。

删除 Vault 可能会被 归档存储 拒绝，即使在刚刚删除完 Vault 里所有的 Archive，也无法立即删除 Vault。

示例oascmd.py rm oas://vaultname
oascmd.py rm oas://vaultname <archiveId>




创建 inventory-retrieval 或者 archive-retrieval Job



格式


[backcolor=transparent] createjob [-h] oas://vaultname [archiveId] [--start START] [--size SIZE] [--desc DESC]

说明


不指定 archiveId 创建 inventory-retrieval Job 用于获取 Vault 的详细统计信息， 或指定 archiveId 创建 archive-retrieval Job 用于下载 Archive。
archive-retrieval Job 支持带范围的数据提取，inventory-retrieval Job 暂不支持。
createjob 会返回一个 Job ID，该 ID 可以用于后续的 Job 提取数据的下载。

• vaultname

必选，Job 操作的 Vault 名称，必须以 oas:// 作为前缀

• archiveId

可选，创建 archive-retrieval Job 时必须指定对应 Archive 的 Archive ID。

• --start start

可选，用于指定 archive-retrieval Job 的数据提取起始位置，支持带单位的输入，单位不区分大小写（除B以外）， 如 0, 32M, 64M 等。不指定则默认为0。

• --size size

可选，用于指定 archive-retrieval Job 的数据提取大小，支持带单位的输入，单位不区分大小写（除B以外）， 如 32M, 1G 等。不指定则默认为从 start 开始到 Archive 最后的大小。

• --desc desc

可选，创建 Job 时的描述信息，不具有 Job 检索功能。

示例oascmd.py createjob oas://vaultname
oascmd.py createjob oas://vaultname <archiveId>
oascmd.py createjob oas://vaultname <archiveId> --desc "retrieve archiveId"
# 提取前64M的数据
oascmd.py createjob oas://vaultname <archiveId> --size 64M
# 提取自64M以后的数据
oascmd.py createjob oas://vaultname <archiveId> --start 64M

如果并不需要取出 Archive 的全部数据，建议加上 --start 和 --size 选项。

在 OSS 与 归档存储 之间转移数据



格式


[backcolor=transparent] cp [-h] [--osshost OSSHOST] [--desc DESC] source destination

说明


启动 OSS 和 归档存储 之间的数据转移 Job 任务。
[backcolor=transparent]注意： 目前只支持内网的 OSS 域名。

• source

必选，转移源地址，从 OSS 到 归档存储，source 和 destination 需要分别配置为 oss://bucketname/objectname 和 oas://vaultname。 从 归档存储 提取文件到 OSS，source 和 destination 格式分别为 oas://vaultname/archiveid 和 oss://bucketname/objectname。

查询 OSS object 到 归档存储 对应 Archive 的 Archive ID，需要用 getjobdesc 命令，使用方法会由 cp 命令在成功提交 Job 之后自动输出。

• destination

必选，转移目的地，参考 source 说明

• osshost

可选，需要转移数据的 OSS 访问地址，若不指定，则按照 归档存储 配置文件的 osshost 配置、用户目录的 .osscredentials 的 host 配置的顺序来读取

• desc

可选，转移 Job 任务的描述信息，oascmd.py 会默认加上 copy from/to OSS-object-path 格式的描述信息。

示例# 拷贝 OSS object bucketname/object-path 到 归档存储的 vaultname
# 注意目的地不需要指定，只能由 归档存储 生成对应的 Archive。
oascmd.py cp oss://bucketname/object-path oas://vaultname

# 拷贝 归档存储 vaultname 下面的 archiveId 到 OSS 的 bucketname/dest-object-path 路径
oascmd.py cp oas://vaultname/archiveId oss://bucketname/dest-object-path

注意从 OSS 到 归档存储 的过程，destination 只需要指定到 vaultname 即可，归档存储会自动生成对应的 Archive ID，OSS object 的名称也会添加到该 Archive 的描述信息里。

下载 Job 结果



格式


[backcolor=transparent] fetch(fetchjoboutput) [-h] [-f] oas://vaultname jobid localfile [--start START] [--size SIZE]

说明


Job 完成时，下载 jobid 的输出结果到本地的文件 localfile，如果 Job 未完成，则仅提示 Job 未完成。

• vaultname

必选，Job 创建时的 Vault 名称，必须以 oas:// 作为前缀

• jobid

必选，Job 创建时返回的 Job ID

• localfile

必选，Job 结果保存的本地文件名

• --start START

可选，指定 Job 已提取数据的起始下载位置，该位置相对于提取数据，支持带单位的输入， 单位不区分大小写（除B以外），如 0, 32M, 64M 等。不指定则下载全部的提取数据。
不指定则默认为 0。

• --size SIZE

可选，指定需要从 Job 已提取数据下载的大小，支持带单位的输入， 单位不区分大小写（除B以外），如 0, 32M, 64M 等。不指定则下载全部的提取数据。
不指定则默认为从 start 开始，一直到提取数据结尾的大小。

• -f, --force

可选，当指定的 localfile 如果在本地已经存在同名文件，则强制覆盖写，不指定则提示是否进行覆盖写入。

注意 Job 的结果最长可能需要4小时才能获取到

示例oascmd.py fetch oas://vaultname <jobId> localfile
oascmd.py fetch -f oas://vaultname <jobId> localfile
oascmd.py fetch -f oas://vaultname <jobId> localfile --size 64M
oascmd.py fetch -f oas://vaultname <jobId> localfile --start 64M --size 64M
oascmd.py fetch -f oas://vaultname <jobId> localfile --start 128M




Vault 操作



创建 Vault


参考 cv

删除 Vault


参考 rm，无 rm 的 archiveId 参数

获取 Vault 信息



格式


[backcolor=transparent] getvaultdesc [-h] oas://vaultname

说明


获取指定名称的 Vault 的描述。

• vaultname

必选，需要查询的 Vault 的名称，必须包含 oas:// 前缀。

示例oascmd.py getvaultdesc oas://vault




Vault 列表


参考 ls

Archive 操作



上传 Archive



格式


[backcolor=transparent] postarchive [-h] [--desc DESC] oas://vaultname filename [etag] [tree_etag]

说明


上传本地文件至指定 Vault。校验码 etag, tree_etag 的计算方式请参考 API使用手册

• vaultname

必选，保存文件的 Vault 的名称，必须包含 oas:// 前缀

• filename

必选，本地文件名

• etag

可选，文件的 etag，用作上传的数据校验，可以由 fileetag 命令计算得到，不提供则由 oascmd.py 自动计算

• tree_etag

可选，文件的 tree_etag，用作上传的数据校验，可以由 fileetag 命令计算得到，不提供则由 oascmd.py 自动计算

• --desc desc

可选，Archive 的描述信息，不指定则默认为文件名，超过 128 字节长度，只取前 128 字节内容。

示例oascmd.py postarchive oas://vaultname local_file
oascmd.py postarchive oas://vaultname local_file --desc "My File Description"
oascmd.py postarchive oas://vaultname local_file E0706E072A00E7BBFDC52AEAEE53E428 93C106A8937AC115BD21A63FE9114B1C




删除 Archive



格式


[backcolor=transparent] deletearchive [-h] oas://vaultname archiveId

说明 & 示例


参考 rm

Multipart Upload 操作



初始化 Multipart Upload 任务



格式


[backcolor=transparent] createmupload [-h] [--desc DESC] vault part_size

说明


创建 Multipart Upload 上传任务，任务创建完成后，会返回一个 Multipart Upload ID，该 ID 是完成后续 Multipart Upload 操作的依据

• vaultname

必选，Multipart Upload 任务所在 Vault 的名称，必须包含 oas:// 前缀。

• part_size

必选，Multipart Upload 时指定的分段大小，分段大小必须在 32MB 到 4GB的范围（包括两端），且满足 2^N，其中N是正整数， 支持带单位的输入，且各单位不区分大小写（不包括B），如 32M, 64M, 128MB 等。

• --desc desc

可选，Multipart Upload 的描述信息，默认为空。

Multipart Upload 任务自创建开始，只保留24小时的有效期，超过之后会被 归档存储 回收

示例oascmd.py createmupload oas://vaultname 64M
oascmd.py createmupload oas://vaultname 128M --desc "Task Description"




获取 Multipart Upload 任务列表



格式


[backcolor=transparent] listmupload [-h] oas://vaultname [--marker marker] [--limit limit]

说明

• vaultname

必选，需要查看 Multipart Upload 任务列表的 Vault 的名称，必须包含 oas:// 前缀。

• --limit limit

可选，列出的任务总数上限

• --marker marker

可选，显示的任务列表非全部任务时，listmupload 会返回一个非空的 marker，该 marker 可以作为 listmupload 的参数， 用来取出其他未显示的任务列表。

示例oascmd.py listmupload oas://vault
oascmd.py listmupload oas://vault --limit 100
oascmd.py listmupload oas://vault --marker marker_str --limit 250




删除 Multipart Upload 任务



格式


[backcolor=transparent] deletemupload [-h] oas://vaultname uploadid

说明


删除指定 ID 的任务。

• vaultname

必选，任务所在 Vault 的名称，必须包含 oas:// 前缀。

• uploadid

必选，待取消的 Multipart Upload 任务的 ID。

示例oascmd.py deletemupload oas://vault upload_id




Part 上传



格式


[backcolor=transparent] postmpart [-h] oas://vaultname uploadid filename start end [etag] [tree_etag]

说明


上传 Archive 中的某个 Part。

• vaultname

必选，Multipart Upload 任务所在 Vault 的名称，必须包含 oas:// 前缀。

• uploadid

必选，createmupload 返回的 Multipart Upload 任务 ID

• filename

必选，本地文件名

• start

必选，文件上传的起始读取位置，支持带单位的输入，且各单位不区分大小写（不包括B），如 32M, 64M, 128MB 等。

• end

必选，文件上传的末尾读取位置，支持带单位的输入，但是需要注意的是该大小必须满足 start + part_size -1 或者 totalsize - 1，其中 part_size 是 createmupload 时指定的 part_size，totalsize 是文件的总大小。

• etag

可选，Part 的 etag，用作上传的数据校验，可以由 partetag 命令计算得到，不提供则由 oascmd.py 自动计算

• tree_etag

可选，Part 的 tree_etag，用作上传的数据校验，可以由 partetag 命令计算得到，不提供则由 oascmd.py 自动计算

示例oascmd.py postmpart oas://vault upload_id local_file 0 67108863 0EC0CFC8AEF45A5B76460419A56EE36F F60F379B33C234F69FA4F79254650F65
oascmd.py postmpart oas://vault upload_id local_file 64M 134217727




获取 Part 列表



格式


[backcolor=transparent] listmpart [-h] oas://vaultname uploadid [--maker marker] [--limit limit]

说明


获取指定 Multipart Upload 任务已上传的 Part 列表。

• vaultname

必选，Multipart Upload 任务所在 Vault 的名称，必须包含 oas:// 前缀。

• --limit limit

可选，列出的已上传的 part 总数上限

• --marker marker

可选，显示的 Part 列表非全部 Part 时，listmpart 会返回一个非空的 marker，该 marker 可以作为 listmpart 的参数， 用来取出其他未显示的 Part 列表。

示例oascmd.py listmpart oas://vault upload_id
oascmd.py listmpart oas://vault upload_id --limit 20
oascmd.py listmpart oas://vault upload_id --marker marker_str --limit 10




Part 合并



格式


[backcolor=transparent] completemupload [-h] oas://vaultname uploadid size tree_etag

说明


所有的 Part 都上传完成之后，对所上传的 part 进行合并。

• vaultname

必选，Multipart Upload 任务所在 Vault 的名称，必须包含 oas:// 前缀。

• uploadid

必选，createmupload 返回的 Multipart Upload 任务 ID。

• size

必选，本地文件的总大小，支持带单位的输入，且各单位不区分大小写（不包括B），如 32M, 64M, 128MB 等。

• tree_etag

必选，文件的 tree_etag，用作上传的数据校验，可以由 fileetag 命令计算得到。

所有的 Part 都上传完成之后，必须要执行一次 completemupload 才算完成上传， 否则24小时失效到期之后，任务所有的相关资源都会被清理。

示例oascmd.py completemupload oas://vault upload_id 100M 93C106A8937AC115BD21A63FE9114B1C




Job 操作



初始化 Job 任务


参考 createjob

Job Output 下载


参考 fetch

获取 Job 列表



格式


[backcolor=transparent] listjob [-h] oas://vaultname [--marker marker] [--limit limit]

说明


获取指定 Vault 下未失效的 Job 列表。

• vaultname

必选，需要查看 Job 列表的 Vault 的名称，必须包含 oas:// 前缀。

• --limit limit

可选，列出还未失效的 Job 总数上限

• --marker marker

可选，显示的 Job 列表非全部 Job 时，listjob 会返回一个非空的 marker，该 marker 可以作为 listjob 的参数， 用来取出其他未显示的 Job 列表。

示例oascmd.py listjob oas://vault
oascmd.py listjob oas://vault --limit 10
oascmd.py listjob oas://vault --marker marker_str --limit 10




Job 任务状态查询



格式


[backcolor=transparent] getjobdesc [-h] oas://vaultname jobid

说明


获取指定 Job 任务的信息。

• vaultname

必选，Job 操作的 Vault 名称，必须以 oas:// 作为前缀。

• jobid

必选，createjob 返回的 Job ID。

示例oascmd.py getjobdesc oas://vault jobid




其他操作



文件校验



格式


[backcolor=transparent] fileetag [-h] filename

说明


计算指定文件的 etag 和 tree_etag，返回值适用于 postarchive 和 completemupload

• filename

必选，本地文件名称

示例oascmd.py fileetag local_file




Part 校验



格式


[backcolor=transparent] partetag [-h] filename start end

说明


计算文件指定范围内的校验值

• filename

必选，本地文件名

• start

必选, 数据读取起始字节，包含该字节，支持单位输入

• end

必选，数据读取结束字节，包含该字节，支持单位输入

示例oascmd.py partetag local_file 0 67108863




基本命令使用示例


参考 最佳实践-快速上手

底层命令使用示例


以 >> 为前缀表明该行是输出，输出中包含的 [variable] 表明该输出依赖于用户的输入，此处以 variable 代替。本节提供的示例应顺序运行，因部分命令的输入依赖于前一条命令的输出。本节仅截取后续命令所依赖的输出信息，完整的输出信息请用户根据示例调用 oascmd.py。

1. 
   配置授权信息oascmd.py config --id my_id --key my_key --host cn-hangzhou.oas.aliyuncs.com

创建 Vault oascmd.py createvault oas://vault_demo

显示 Vault 信息 oascmd.py getvaultdesc oas://vault_demo

上传 Archive oascmd.py fileetag ./random10M.bin

>> etag:      8539EF1FBA74A70F5A77FCC3F25C1659
>> tree_etag: 6BE4CA328B19B165294D7332BEA0AE2B

oascmd.py postarchive oas://vault_demo ./random10M.bin 8539EF1FBA74A70F5A77FCC3F25C1659 6BE4CA328B19B165294D7332BEA0AE2B --desc "Test File"

>> ArchiveId: [archive_id]

删除 Archive oascmd.py deletearchive oas://vault_demo archive_id

新建 Multipart Upload 任务（文件大小为 100MB） oascmd.py createmupload oas://vault_demo 67108864

>> MultiPartUploadId: [upload_id]

上传文件的第一个 Part oascmd.py partetag ./random100M.bin 0 67108863

>> etag:      DE70938849B75D3DB63BBA421C93E018oascmd.py fetchjoboutput oas://vault_demo job_id download.bin
>> tree_etag: A0ED854EE442051B249BFAD0F638BBEC oascmd.py postmpart oas://vault_demo upload_id ./random100M.bin 0 67108863 DE70938849B75D3DB63BBA421C93E018 A0ED854EE442051B249BFAD0F638BBEC

查看已上传的 Part oascmd.py listmpart oas://vault_demo upload_id

上传文件的第二个 Part oascmd.py partetag ./random100M.bin 67108864 104857599

>> etag:      FBCCFC665BEDCE3F5676A910CE9D59EE
>> tree_etag: 7F0BE445401604B1DB8AB21C42231DBD

oascmd.py postmpart oas://vault_demo upload_id ./random100M.bin 67108864 104857599 FBCCFC665BEDCE3F5676A910CE9D59EE 7F0BE445401604B1DB8AB21C42231DBD

完成 Multipart Upload 任务[code]oascmd.py fileetag ./random100M.bin

>> etag:      B3163E84A5E2929F3CAC76D0109F3EC2
>> tree_etag: 12E3F713EFADBEDB95FA024AEC977876

oascmd.py completemupload oas://vault_demo upload_id 104857600 12E3F713EFADBEDB95FA024AEC977876

>> ArchiveId: [archive_id][/code]

下载 Archive，新建 Job 任务[code]oascmd.py createjob oas://vault_demo archive_id

>> JobId: [job_id][/code]

等待 Job 任务完成[code]oascmd.py getjobdesc oas://vault_demo job_id

>> Completed: false[/code]

反复执行该命令至输出为[code]>> Completed: true[/code]

下载 Job 任务输出