全部产品
Search

搜索本产品

    对象存储 OSS：cp（下载文件）

    文档中心

    对象存储 OSS：cp（下载文件）

    更新时间：Jul 30, 2024

    当您需要将已上传至OSS的文件、图片、视频等资源下载到本地时，可以使用ossutil的cp命令。您也可以按照本文示例，下载多个文件、下载时限速，或者在已开启版本控制的Bucket内下载指定版本文件。

    注意事项

    • 要下载文件，您必须具有oss:GetObject或oss:ListObjects权限。具体操作，请参见为RAM用户授权自定义的权限策略。

    • 从ossutil 1.6.16版本开始，命令行中Binary名称支持直接使用ossutil，您无需根据系统刷新Binary名称。如果您的ossutil版本低于1.6.16，则需要根据系统刷新Binary名称。更多信息，请参见命令行工具ossutil命令参考。

      命令格式

      ossutil 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>]
[--start-time <value>]
[--end-time <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开始编号。

      • 指定区间

        例如指定为3-9，表示下载文件的第3个字节到第9个字节（包含第3和第9字节）。

      • 指定开始位置

        例如指定为3-，表示从第3个字节开始到文件结尾（包含第3个字节）。

      • 指定结束位置

        例如指定为-9，表示从0字节到第9个字节（包含第9个字节）。

      --encoding-type

      文件名称的编码方式。取值为url。如果不指定该选项，则表示文件名称未经过编码。

      --include

      包含符合指定条件的所有文件。

      更多信息，请参见include和exclude选项。

      --exclude

      不包含符合指定条件的文件。

      更多信息，请参见include和exclude选项。

      --meta

      设置文件的元数据，格式为header:value#header:value，示例为Cache-Control:no-cache#Content-Encoding:gzip。有关元数据的介绍，请参见set-meta（管理文件元数据）。

      --acl

      文件的读写权限ACL。取值如下：

      • default（默认值）：继承Bucket的读写权限。

      • private：只有该Bucket的拥有者可以对该Bucket内的文件进行读写操作，其他人无法访问该Bucket内的文件。

      • public-read：只有Bucket拥有者可以对该Bucket内的文件进行写操作，其他用户（包括匿名访问者）可以对该Bucket中的文件进行读操作。这有可能造成您数据的外泄以及费用激增，请谨慎操作。

      • public-read-write：任何人（包括匿名访问者）都可以对该Bucket内文件进行读写操作。这有可能造成您数据的外泄以及费用激增，如果被人恶意写入违法信息还可能会侵害您的合法权益。除特殊场景外，不建议您配置公共读写权限。

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

      --start-time

      Unix时间戳。如果输入这个选项，最后更新时间早于该时间的Object会被忽略。

      说明

      仅1.7.18及以上版本支持设置该参数。关于如何升级版本，请参见update（ossutil版本升级）。

      --end-time

      Unix时间戳。如果使用该选项，则最后更新时间晚于通过此选项指定时间的Object会被忽略。

      说明

      • 如果同时指定了start-time和end-time，文件的修改时间在start-time和end-time之间才会执行拷贝命令。

      • 仅1.7.18及以上版本支持设置该参数。关于如何升级版本，请参见update（ossutil版本升级）。

      从以上命令格式中的-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（根目录下的文件夹）

      下载单个文件

      下载文件时如果未指定文件名，则默认使用原文件名保存在本地。如果指定文件名，则按照指定文件名保存在本地。

      • 沿用原文件名保存文件

        ossutil cp oss://examplebucket/destfolder/examplefile.txt localfolder/

      • 按指定文件名保存文件

        ossutil cp oss://examplebucket/destfolder/examplefile.txt localfolder/example.txt

      下载多个文件

      ossutil不支持通过直接指定多个文件名的方式下载多个文件。您可以通过以下方式下载多个文件：

      • 下载某一类文件

        如果您希望同时下载多个文件名规律的文件，例如这些文件均包含相同前缀或者后缀，此时您可以结合--include和--exclude选项在下载时选择符合条件的文件。

        • 下载所有文件格式不为JPG的文件 

          ossutil cp oss://examplebucket/destfolder/ localfolder/ --exclude "*.jpg" -r

        • 下载所有文件名包含abc且不是JPG和TXT格式的文件 

          ossutil cp oss://examplebucket/destfolder/ localfolder/ --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -r

      • 下载文件夹（包含子目录）

        下载某一个文件夹（包含子目录）下所有文件的示例如下：

        ossutil cp -r oss://examplebucket/destfolder/ localfolder/

        当批量下载失败或者需要增量下载文件时，可以通过指定--update（可缩写为-u）选项选择跳过已经成功下载的文件。如果本地与OSS没有同名文件，或本地同名文件的最后修改时间早于OSS文件，ossutil会下载该文件。如果本地已有同名文件，且文件的最后修改时间晚于OSS内文件时，ossutil会跳过该文件。示例如下： 

        ossutil cp -r oss://examplebucket/destfolder/  localfolder/  --update

      • 下载文件夹（不包含子目录）

        如果您仅希望下载当前目录而忽略子目录下的文件时，可以通过指定--only-current-dir选项。示例如下：

        ossutil cp oss://examplebucket/destfolder/ localfolder/ --only-current-dir -r

      • 下载文件夹（指定时间戳）

        当某一个文件夹（包含子目录）下的文件修改时间在北京时间2023年10月31日10:09:18至2023年10月31日12:55:58内时，才会被下载。示例如下：

        ossutil cp -r oss://examplebucket/destfolder/ localfolder/ --start-time 1698718158 --end-time 1698728158

      • 下载Bucket根目录下的所有文件

        将examplebucket根目录下的所有文件下载到本地localfolder/目录，示例如下：

        ossutil cp -r oss://examplebucket  localfolder/

      下载时限速

      您可以在下载文件时，结合--maxdownspeed选项来限制下载的最大速度，单位为KB/s。示例如下：

      • 下载文件并设置限速为1 MB/s

        ossutil cp oss://examplebucket/destfolder/examplefile.txt  localfolder/ --maxdownspeed 1024

      • 下载文件夹并设置限速为1 MB/s 

        ossutil cp -r  oss://examplebucket/destfolder/  localfolder/ --maxdownspeed 1024

      范围下载

      下载文件时，可以通过--range选项指定下载范围。例如将examplefile.txt的第10到第20个字符作为一个文件下载到本地，命令如下：

      ossutil cp oss://examplebucket/destfolder/examplefile.txt localfolder/  --range=10-20
Succeed: Total num: 1, size: 11. OK num: 1(download 1 objects).

      下载并生成快照信息

      批量下载时，如果指定--snapshot-path选项，ossutil在指定的目录下生成文件下载的快照信息，在下一次指定该选项下载时，ossutil会读取指定路径下的快照信息进行增量下载。详情请参见上传并生成快照。

      ossutil cp -r oss://examplebucket/destfolder/ localfolder/ --snapshot-path=path

      在已开启版本控制的Bucket内下载指定版本文件

      开启Bucket的版本控制后，针对数据的覆盖和删除操作将会以历史版本的形式保存下来。您可以在cp命令中增加--version-id选项下载指定版本文件，命令如下：

      ossutil cp oss://my-bucket/test.jpg localfolder/ --version-id  CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3MDRk
      重要

      通用选项

      当您需要通过命令行工具ossutil切换至另一个地域的Bucket时，可以通过-e选项指定该Bucket所属的Endpoint。当您需要通过命令行工具ossutil切换至另一个阿里云账号下的Bucket时，可以通过-i选项指定该账号的AccessKey ID，并通过-k选项指定该账号的AccessKey Secret。

      说明

      您需要根据Bucket所在地域填写对应的Endpoint。更多信息，请参见访问域名和数据中心。

      例如，您需要将另一个阿里云账号下，华东2（上海）地域下存储空间examplebucket根目录下的文件exampleobject.txt下载至本地目录localfolder下，命令如下：

      ossutil cp oss://examplebucket/exampleobject.txt  localfolder/  -e oss-cn-shanghai.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA****  -k 67DLVBkH7EamOjy2W5RVAHUY9H****

      关于此命令的其他通用选项的更多信息，请参见通用选项。