您可以通过cp命令将OSS的文件(Object)下载到本地。
命令格式
./ossutil64 cp cloud_url file_url
[-r, --recursive]
[-f --force]
[-u --update]
[--maxdownspeed <value>]
[--disable-ignore-error]
[--only-current-dir]
[--bigfile-threshold <value>]
[--part-size <value>]
[--checkpoint-dir <value>]
[--range <value>]
[--encoding-type <value>]
[--include <value>]
[--exclude <value>]
[--meta <value>]
[--acl <value>]
[--snapshot-path <value>]
[--disable-crc64]
[--payer <value>]
[--partition-download <value>]
[-j, --job <value>]
[--parallel <value>]
[--version-id <value>]
参数及选项说明如下:
配置项 | 说明 |
---|---|
cloud_url | OSS文件路径。格式为oss://bucketname/objectname 。例如oss://examplebucket/examplefile.txt 。 |
file_url | 本地文件路径。例如Linux系统文件路径/localfolder/examplefile.txt ,Windows系统文件路径D:\localfolder\examplefile.txt 。 |
-r, --recursive | 递归操作。当指定该选项时,ossutil会对Bucket下所有符合条件的Object进行操作,否则只对指定的单个Object进行操作。 |
-f --force | 强制操作,不进行询问提示。 |
-u,--update | 只有当目标文件不存在,或源文件的最后修改时间晚于目标文件时,ossutil才会执行下载操作。 |
--maxdownspeed | 最大下载速度,单位为KB/s。默认值为0,表示不限制下载速度。 |
--disable-ignore-error | 批量操作时不忽略错误。 |
--only-current-dir | 仅下载当前目录下的文件,忽略子目录及子目录下的文件。 |
--bigfile-threshold | 设置断点续传文件的大小阈值,单位为字节。 默认值:100 MB 取值范围:0~9223372036854775807 |
--part-size | 设置分片大小,单位为字节。默认情况下ossutil会根据文件大小自行计算合适的分片大小值。 取值范围:1~9223372036854775807 |
--checkpoint-dir | 指定断点续传记录信息所在的目录。断点续传操作失败时,ossutil会自动创建名为.ossutil_checkpoint 的目录,并在该目录下记录checkpoint信息,断点续传成功后会删除该目录。如果指定了该选项,请确保指定的目录可以被删除。 |
--range | 下载目标文件的指定字段,并保存为一个新的文件,字段从0开始编号。
|
--encoding-type | 文件名称的编码方式。取值为url。如果不指定该选项,则表示文件名称未经过编码。 |
--include | 包含符合指定条件的所有文件。 说明 不支持通过该选项指定为目录的形式,例如 ./ossutil64 cp oss://examplebucket/destfolder/ localfolder/ --include dir/ ,否则报错--include or --exclude does not support format containing dir info。 |
--exclude | 不包含符合指定条件的文件。 说明 不支持通过该选项指定为目录的形式,例如 ./ossutil64 cp oss://examplebucket/destfolder/ localfolder/ --exclude dir/ ,否则报错--include or --exclude does not support format containing dir info。 |
--meta | 设置文件的元信息,格式为header:value#header:value ,示例为Cache-Control:no-cache#Content-Encoding:gzip 。有关元信息的介绍,请参见set-meta(管理文件元信息)。 |
--acl | 文件的读写权限ACL。取值如下:
|
--snapshot-path | 指定保存下载文件时的快照信息所在的目录。在下一次下载文件时,ossutil会读取指定目录下的快照信息进行增量下载。 |
--disable-crc64 | 关闭CRC64数据校验。默认情况下,ossutil进行数据传输时都会打开CRC64校验。 |
--payer | 请求的支付方式。如果希望访问指定路径下的资源产生的流量、请求次数等费用由请求者支付,请将此选项的值设置为requester。 |
--partition-download | 用于分区下载。该选项取值格式为分区编号:总分区数 。例如1:5,表示当前ossutil下载分区1,总共有5个分区。分区号从1开始编号,Object的分区规则由工具内部算法决定。通过该选项将待下载的Object分成多个分区,并由多个ossutil命令并行下载,各个ossutil命令下载各自的分区。 |
-j,--job | 多文件操作时的并发任务数,默认值为3,取值范围为1~10000。 |
--parallel | 单文件操作时的并发任务数,取值范围为1~10000。 如果不设置此选项,默认由ossutil根据操作类型和文件大小自行决定。 |
--version-id | 下载指定版本的文件,仅支持在已开启版本控制的Bucket内使用。 |
从以上命令格式中的-j,--jobs和--parallel选项得知,当ossutil自行设置的默认并发数达不到用户的性能要求时,您可以自行调整这两个选项来升降性能。默认情况下,ossutil会根据文件大小来计算parallel个数。当批量下载大文件时,实际的并发数为jobs个数乘以parallel个数。
- 当ECS虚拟机或者服务器在网络、内存、CPU等资源不是特别大的情况下,建议将并发数调整到100以下。如果网络、内存、CPU等资源没有占满,可以适当增加并发数。
- 由于线程间资源切换及抢夺等原因,如果并发数过大,ossutil下载性能可能会下降。此外,并发数过大还可能产生EOF错误。所以请根据实际的机器情况调整-j,--jobs和--parallel选项的数值。如果要进行压测,可在一开始时调低这两项数值,然后逐渐调大直至找到最优值。
示例环境
本文以Linux系统为例,将OSS内的文件下载到本地。您在实际使用中,请根据您的系统和使用环境修改对应参数。示例环境如下:
- 操作系统:Linux
- 目标Bucket:examplebucket
- 目标Bucket指定目录:destfolder
- 本地文件:examplefile.txt(根目录下的文件)
- 本地文件夹:localfolder(根目录下的文件夹)
下载单个文件
下载文件时如果未指定文件名,则默认使用原文件名保存在本地。如果指定文件名,则按照指定文件名保存在本地。
- 沿用原文件名保存文件
./ossutil64 cp oss://examplebucket/destfolder/examplefile.txt localfolder/
- 按指定文件名保存文件
./ossutil64 cp oss://examplebucket/destfolder/examplefile.txt localfolder/example.txt
下载多个文件
ossutil不支持通过直接指定多个文件名的方式下载多个文件。您可以通过以下方式下载多个文件:
- 下载某一类文件
如果您希望同时下载多个文件名规律的文件,例如这些文件均包含相同前缀或者后缀,此时您可以结合--include和--exclude选项在下载时选择符合条件的文件。
- 下载所有文件格式不为JPG的文件
./ossutil64 cp oss://examplebucket/destfolder/ localfolder/ --exclude "*.jpg" -r
- 下载所有文件名包含abc且不是JPG和TXT格式的文件
./ossutil64 cp oss://examplebucket/destfolder/ localfolder/ --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -r
- 下载所有文件格式不为JPG的文件
- 下载文件夹(包含子目录)
下载某一个文件夹(包含子目录)下所有文件的示例如下:
./ossutil64 cp -r oss://examplebucket/destfolder/ localfolder/
当批量下载失败或者需要增量下载文件时,可以通过指定--update(可缩写为-u)选项选择跳过已经成功下载的文件。如果本地与OSS没有同名文件,或本地同名文件的最后修改时间早于OSS文件,ossutil会下载该文件。如果本地已有同名文件,且文件的最后修改时间晚于OSS内文件时,ossutil会跳过该文件。示例如下:
./ossutil64 cp -r oss://examplebucket/destfolder/ localfolder/ --update
- 下载文件夹(不包含子目录)
如果您仅希望下载当前目录而忽略子目录下的文件时,可以通过指定--only-current-dir选项。示例如下:
./ossutil64 cp oss://examplebucket/destfolder/ localfolder/ --only-current-dir -r
- 下载Bucket根目录下的所有文件
将examplebucket根目录下的所有文件下载到本地localfolder/目录,示例如下:
./ossutil64 cp -r oss://examplebucket localfolder/
下载时限速
- 下载文件并设置限速为1 MB/s
./ossutil64 cp oss://examplebucket/destfolder/examplefile.txt localfolder/ --maxdownspeed 1024
- 下载文件夹并设置限速为1 MB/s
./ossutil64 cp -r oss://examplebucket/destfolder/ localfolder/ --maxdownspeed 1024
范围下载
./ossutil64 cp oss://examplebucket/destfolder/examplefile.txt localfolder/ --range=10-20
Succeed: Total num: 1, size: 11. OK num: 1(download 1 objects).
下载并生成快照信息
./ossutil64 cp -r oss://examplebucket/destfolder/ localfolder/ --snapshot-path=path
在已开启版本控制的Bucket内下载指定版本文件
./ossutil64 cp oss://my-bucket/test.jpg localfolder/ --version-id CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3MDRk
- 使用--version-id选项前,需使用ls --all-versions命令获取文件的versionid。
- --version-id选项仅支持在已开启版本控制的Bucket内使用。开启Bucket版本控制命令请参见bucket-versioning(版本控制)。
通用选项
当您需要通过命令行工具ossutil切换至另一个地域的Bucket时,可以通过-e选项指定该Bucket所属的Endpoint。当您需要通过命令行工具ossutil切换至另一个阿里云账号下的Bucket时,可以通过-i选项指定该账号的AccessKey ID,并通过-k选项指定该账号的AccessKey Secret。
./ossutil64 cp oss://examplebucket/exampleobject.txt localfolder/ -e oss-cn-shanghai.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA**** -k 67DLVBkH7EamOjy2W5RVAHUY9H****
关于此命令的其他通用选项的更多信息,请参见通用选项。