文档

cp(拷贝文件)

更新时间:

拷贝文件(Object)是指在不改变文件内容的情况下,将同一地域下的源存储空间(Bucket)内的文件复制到目标Bucket,或者将文件复制到相同存储空间(Bucket)的其他目录。您可以通过ossutil的cp完成拷贝。

注意事项

  • 本文各命令行示例均基于Linux 64位系统,其他系统请将命令开头的./ossutil64替换成对应的Binary名称。详情请参见命令行工具ossutil命令参考

  • 不支持通过cp命令跨账号或者跨地域拷贝文件。如果您需要跨账号或者跨地域拷贝(迁移)文件,请使用ossimport或者在线迁移服务

  • 目前只支持拷贝文件,不支持拷贝未完成的分片(Part)。

  • 不支持对通过追加上传方式生成的Object进行拷贝。

  • 您需要有源Object的读权限及目标Bucket的读写权限,否则无法完成拷贝操作。关于拷贝文件的更多信息,请参见拷贝文件

  • 当您在OSS ON云盒中使用该命令时:
    1. 将配置文件中的Endpoint替换为云盒Endpoint。更多信息,请参见云盒Endpoint
    2. 在本文已有示例的基础上添加--sign-version--region以及--cloudbox-id选项。关于这三个选项的具体用法,请参见通用选项

命令格式

./ossutil64 cp cloud_url cloud_url
[-r, --recursive]
[-f --force]
[-u --update]
[--disable-ignore-error]
[--only-current-dir]
[--bigfile-threshold <value>]
[--part-size <value>]
[--checkpoint-dir <value>]
[--encoding-type <value>]
[--include <value>]
[--exclude <value>]
[--meta <value>]
[--acl <value>]
[--disable-crc64]
[--payer <value>]
[-j, --job <value>]
[--parallel <value>]
[--version-id <value>]
[--start-time <value>]
[--end-time <value>]

参数及选项说明如下:

配置项

说明

cloud_url

分别填写OSS源文件和目标文件路径。格式为oss://bucketname/objectname。例如,将目标存储空间examplebucket下的源文件srcobject.jpg拷贝到相同存储空间下的目标文件destobject.jpg,则源文件路径填写为oss://examplebucket/srcobject.jpg,目标文件路径填写为oss://examplebucket/destobject.jpg

-r, --recursive

递归操作。当指定该选项时,ossutil会对Bucket下所有符合条件的Object进行操作,否则只对指定的单个Object进行操作。

-f --force

强制操作,不进行询问提示。

-u,--update

只有当目标文件不存在,或源文件的最后修改时间晚于目标文件时,ossutil才会执行拷贝操作。

--disable-ignore-error

批量操作时不忽略错误。

--only-current-dir

仅拷贝当前目录下的文件,忽略子目录及子目录下的文件。

-bigfile-threshold

设置断点续传文件的大小阈值,单位为字节。

默认值:100 MB

取值范围:0~9223372036854775807

--part-size

设置分片大小,单位为字节。默认情况下ossutil会根据文件大小自行计算合适的分片大小值。

取值范围:1~9223372036854775807

--checkpoint-dir

指定断点续传记录信息所在的目录。断点续传操作失败时,ossutil会自动创建名为.ossutil_checkpoint的目录,并在该目录下记录checkpoint信息,断点续传成功后会删除该目录。如果指定了该选项,请确保指定的目录可以被删除。

--encoding-type

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

--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内文件进行读写操作。这有可能造成您数据的外泄以及费用激增,请谨慎操作。

--disable-crc64

关闭CRC64数据校验。默认情况下,ossutil进行数据传输时都会打开CRC64校验。

--payer

请求的支付方式。如果希望访问指定路径下的资源产生的流量、请求次数等费用由请求者支付,请将此选项的值设置为requester

-j,--jobs

多文件操作时的并发任务数,默认值为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系统为例,演示如何在不同目录或不同Bucket之间拷贝文件。您在实际使用中,请根据您的系统和使用环境修改对应参数。示例环境如下:

  • 操作系统:Linux

  • 源Bucket:examplebucket1

  • 源Bucket指定目录1:srcfolder1

  • 源Bucket指定目录2:srcfolder2

  • 目标Bucket:examplebucket2

  • 目标Bucket指定目录:desfolder

是否拷贝源目录

拷贝文件时,如果源路径末尾没有携带正斜线(/),则拷贝与指定前缀匹配的所有文件到目标Bucket。如果源路径末尾携带了正斜线(/),则仅拷贝指定目录下的文件拷到目标Bucket。

假设源存储空间examplebucket1指定目录srcfolder1下包含以下文件:

srcfolder1/exampleobject1.txt
srcfolder1/exampleobject2.png
srcfolder1/dir1/
srcfolder1/dir1/exampleobject3.jpg
srcfolder1/dir2/
srcfolder1/dir2/exampleobject4.jpg
  • 拷贝时指定的源路径不以正斜线(/)结尾

    ./ossutil64 cp oss://examplebucket1/srcfolder1  oss://examplebucket2 -r

    拷贝完成后,目标存储空间examplebucket2下将新增以下文件:

    srcfolder1/exampleobject1.txt
    srcfolder1/exampleobject2.png
    srcfolder1/dir1/
    srcfolder1/dir1/exampleobject3.jpg
    srcfolder1/dir2/
    srcfolder1/dir2/exampleobject4.jpg
  • 拷贝时指定的源路径以正斜线(/)结尾

    ./ossutil64 cp oss://examplebucket1/srcfolder1/  oss://examplebucket2 -r

    拷贝完成后,目标存储空间examplebucket2下将新增以下文件:

    exampleobject1.txt
    exampleobject2.png
    dir1/
    dir1/exampleobject3.jpg
    dir2/
    dir2/exampleobject4.jpg

简单拷贝文件

  • 拷贝单个文件

    ./ossutil64 cp oss://examplebucket1/examplefile.txt oss://examplebucket1/srcfolder2/                                 
  • 拷贝增量文件

    批量拷贝时,如果指定--update选项,只有当目标文件不存在,或源文件的最后修改时间晚于目标文件时,ossutil才会执行拷贝操作。命令如下:

    ./ossutil64 cp oss://examplebucket1/srcfolder1/ oss://examplebucket2/path2/ -r --update

    该选项可用于当批量拷贝失败重传时,跳过已经拷贝成功的文件,实现增量拷贝。

  • 批量拷贝文件

    限定srcfolder1中文件的修改时间,在北京时间2023年10月31日10:09:18至2023年10月31日12:55:58内时,文件才会被拷贝。

    ./ossutil64 cp -r oss://examplebucket1/srcfolder1/ oss://examplebucket2/path2/ --start-time 1698718158 --end-time 1698728158
  • 重命名文件

    ./ossutil64 cp oss://examplebucket1/examplefile.txt oss://examplebucket1/example.txt                        

    通过cp命令重命名文件时,原文件仍存在,您可以在重命名后删除原文件。

  • 仅拷贝当前目录下的文件,忽略子目录

    ./ossutil64 cp oss://examplebucket1/srcfolder1/ oss://examplebucket1/srcfolder2/ --only-current-dir -r
  • 修改文件meta信息

    拷贝文件的同时可以使用--meta选项修改文件的meta信息,其内容格式为 header:value#header:value...

    ./ossutil64 cp oss://examplebucket1/examplefile.txt oss://examplebucket1/ --meta=Cache-Control:no-cache
  • 从开通了请求者付费模式的Bucket拷贝文件到普通Bucket

    ./ossutil64 cp oss://examplebucket1/examplefile.txt oss://examplebucket2/desfolder/  --payer=requester

拷贝符合指定条件的文件

您可以使用--include--exclude参数,在拷贝时选定符合条件的文件。

  • 拷贝所有文件格式不为JPG的文件

    ./ossutil64 cp oss://examplebucket1/srcfolder1/ oss://examplebucket2/desfolder/ --exclude "*.jpg" -r
  • 拷贝所有文件名包含abc且不是JPGTXT格式的文件

    ./ossutil64 cp oss://examplebucket1/srcfolder1/ oss://examplebucket2/desfolder/ --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -r

修改文件存储类型

您可以在覆写 文件时,添加--meta选项来修改文件存储类型。存储类型可选值为:

  • Standard:标准存储

    说明 在OSS ON云盒使用场景中,仅支持Standard类型。
  • IA:低频访问

  • Archive:归档存储

  • ColdArchive:冷归档存储

  • DeepColdArchive:深度冷归档存储

关于存储类型的更多信息,请参见存储类型概述

重要

通过--meta选项修改存储类型时,默认会覆盖已有的自定义文件元数据。如果您希望修改存储类型的同时可以保留已有的自定义文件元数据,则需要携带x-oss-metadata-directive:COPY选项。

覆盖已有自定义文件元数据

  • 将指定文件的存储类型修改为归档存储

    ./ossutil64 cp oss://examplebucket1/srcfolder1/examplefile.txt oss://examplebucket1/srcfolder1/examplefile.txt --meta X-oss-Storage-Class:Archive
  • 将指定文件夹下所有文件的存储类型修改为标准存储

    ./ossutil64 cp oss://examplebucket1/srcfolder1/ oss://examplebucket1/srcfolder1/ --meta X-oss-Storage-Class:Standard -r

保留已有的自定义文件元数据

  • 将指定文件的存储类型修改为低频访问类型,同时保留已有单个文件的文件元数据。

    ./ossutil64 cp oss://examplebucket1/srcfolder1/examplefile.txt oss://examplebucket1/srcfolder1/examplefile.txt --meta X-oss-Storage-Class:IA#x-oss-metadata-directive:COPY
  • 将指定文件夹下所有文件的存储类型修改为标准存储,同时保留已有多个文件的元数据。

    ./ossutil64 cp oss://examplebucket1/srcfolder1/ oss://examplebucket1/srcfolder1/ --meta X-oss-Storage-Class:Standard#x-oss-metadata-directive:COPY -r -f
重要
  • 通过cp命令将归档存储、冷归档存储或者深度冷归档存储类型的Object转换为标准、低频访问类型时,必须先通过restore(解冻文件)命令解冻该Object,然后再使用cp命令转换Object的存储类型。如果开启了归档直读,归档存储类型Object无需解冻,就可以转换存储类型。

  • 如果将Object转换为低频访问、归档存储、冷归档存储或者深度冷归档存储类型,且存储未满指定周期,会产生存储不足规定时长容量费用。更多信息,请参见存储费用

  • 通过cp命令对超过100 MB的文件进行存储类型转换操作时,ossutil默认会根据文件大小自行计算合适的分片大小值。如果自动切片无法满足需求,您可以通过--part-size选项指定分片大小,但需确保分片数不能超过10000。

修改文件对象标签

您可以在覆写文件时,添加--tagging选项修改文件对象标签,多个标签以and(&)符号隔开。命令如下:

./ossutil64 cp oss://examplebucket1/examplefile.txt oss://examplebucket1/ --tagging "abc=1&bcd=2&……"

关于对象标签的更多信息,请参见object-tagging(对象标签)

拷贝并加密文件

您可以在拷贝文件时指定文件的服务器端加密方式,将文件加密后保存在Bucket内,关于服务器端加密功能介绍的更多信息,请参见服务器端加密

  • 拷贝文件并指定加密方式为AES256

    ./ossutil64 cp oss://examplebucket1/examplefile.txt oss://examplebucket1/srcfolder2/ --meta=x-oss-server-side-encryption:AES256
  • 拷贝文件并指定加密方式为KMS

    ./ossutil64 cp oss://examplebucket1/examplefile.txt oss://examplebucket2/desfolder/ --meta=x-oss-server-side-encryption:KMS
    重要

    使用KMS加密时,OSS会在KMS平台上为这个文件创建一个主密钥,会产生少量KMS密钥API调用费用。更多信息,请参见KMS计费标准

  • 拷贝文件并指定加密方式为KMS,指定加密算法为SM4,指定CMK ID

    ./ossutil64 cp oss://examplebucket1/examplefile.txt oss://examplebucket2/desfolder/ --meta=x-oss-server-side-encryption:KMS#x-oss-server-side-data-encryption:SM4#x-oss-server-side-encryption-key-id:7bd6e2fe-cd0e-483e-acb0-f4b9e1******

在已开启版本控制的Bucket内恢复文件

开启Bucket的版本控制后,针对数据的覆盖和删除操作将会以历史版本的形式保存下来。您可以在cp命令中增加--version-id选项,将历史版本覆写为最新版本。示例如下:

./ossutil64 cp oss://examplebucket1/examplefile.txt oss://examplebucket2/ --version-id  CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3MDRk
重要

通用选项

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

例如,您需要将另一个阿里云账号下,华东2(上海)地域下源存储空间examplebucket根目录下的文件srcobject.png拷贝至目标存储空间destbucket,命令如下:

./ossutil64 cp oss://examplebucket/srcobject.png  oss://destbucket  -e oss-cn-shanghai.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA****  -k 67DLVBkH7EamOjy2W5RVAHUY9H****

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

  • 本页导读 (1)
文档反馈