oascmd.py 是 Python SDK 提供给用户的一个快捷的命令行测试工具，除了提供方便用户快捷使用的命令以外，还有分别与归档存储API文档描述的接口一一对应的底层命令。

背景信息

其中，[]内的参数为可选参数。字符串前缀oas:// 仅仅作为资源标识，没有其他含义。除了特别说明外，所有结果均直接输出至命令行，输出结果为友好的自解释可读文本，因此下文不再对 oascmd.py 输出进行详细说明。

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

格式

说明

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

  • —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 相比，这些公共选项的要求有以下几点不同：

  • 所有的参数均为可选，如果用户未提供这些选项，则默认从用户目录的 .oascredentials 读取配置，以ls为例。

     # 从 ~/.oascredentials 读取配置
 oascmd.py ls

 # 从 ~/.oascredentials 读取配置，但是需要访问其他 host
 oascmd.py ls --host=<another-host>

 # 从 ~/.oascredentials 读取配置，但是用其他 AccessId/AccessKey 来访问
 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

格式

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

说明

创建名为 vaultname 的 Vault

  • vaultname

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

示例

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

列出所有 Vault

格式

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

上传文件

格式

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

格式

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

格式

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与归档存储之间转移数据

格式

cp [-h] [—osshost OSSHOST] [—desc DESC] source destination

说明

启动 OSS和归档存储之间的数据转移 Job 任务。

注意： 目前只支持内网的 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 结果

格式

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 信息

格式

getvaultdesc [-h] oas://vaultname

说明

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

  • vaultname

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

示例

oascmd.py getvaultdesc oas://vault

Vault 列表

参考 ls

Archive 操作

上传 Archive

格式

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

格式

deletearchive [-h] oas://vaultname archiveId

说明 & 示例

参考 rm

Multipart Upload 操作

初始化 Multipart Upload 任务

格式

deletearchive [-h] oas://vaultname archiveId

说明

创建 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 任务列表

格式

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 任务

格式

deletemupload [-h] oas://vaultname uploadid

说明

删除指定 ID 的任务。

  • vaultname

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

  • uploadid

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

示例

oascmd.py deletemupload oas://vault upload_id

Part 上传

格式

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 列表

格式

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 合并

格式

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 列表

格式

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 任务状态查询

格式

getjobdesc [-h] oas://vaultname jobid

说明

获取指定 Job 任务的信息。

  • vaultname

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

  • jobid

必选，createjob 返回的 Job ID。

示例

oascmd.py getjobdesc oas://vault jobid

其他操作

文件校验

格式

fileetag [-h] filename

说明

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

  • filename

必选，本地文件名称

示例

oascmd.py fileetag local_file

Part 校验

格式

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

  2. 创建 Vault

     oascmd.py createvault oas://vault_demo

  3. 显示 Vault 信息

     oascmd.py getvaultdesc oas://vault_demo

  4. 上传 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]

  5. 删除 Archive

     oascmd.py deletearchive oas://vault_demo archive_id

  6. 新建 Multipart Upload 任务（文件大小为 100MB）

     oascmd.py createmupload oas://vault_demo 67108864

 >> MultiPartUploadId: [upload_id]

  7. 上传文件的第一个 Part

     oascmd.py partetag ./random100M.bin 0 67108863

 >> etag:      DE70938849B75D3DB63BBA421C93E018
 >> tree_etag: A0ED854EE442051B249BFAD0F638BBEC

 oascmd.py postmpart oas://vault_demo upload_id ./random100M.bin 0 67108863 DE70938849B75D3DB63BBA421C93E018 A0ED854EE442051B249BFAD0F638BBEC

  8. 查看已上传的 Part

     oascmd.py listmpart oas://vault_demo upload_id

  9. 上传文件的第二个 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

  10. 完成 Multipart Upload 任务

    oascmd.py fileetag ./random100M.bin

>> etag:      B3163E84A5E2929F3CAC76D0109F3EC2
>> tree_etag: 12E3F713EFADBEDB95FA024AEC977876

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

>> ArchiveId: [archive_id]

  11. 下载 Archive，新建 Job 任务

    oascmd.py createjob oas://vault_demo archive_id

>> JobId: [job_id]

  12. 等待 Job 任务完成

    oascmd.py getjobdesc oas://vault_demo job_id

>> Completed: false

    反复执行该命令至输出为

    >> Completed: true

  13. 下载 Job 任务输出

    oascmd.py fetchjoboutput oas://vault_demo job_id download.bin