tencent cloud

对象存储

复制与移动对象

下载
聚焦模式
字号
最后更新时间: 2025-11-04 15:19:44

简介

本文档提供关于对象的复制、移动操作相关的 API 概览以及 SDK 示例代码。
简单操作
API
操作名
操作描述
设置对象复制(修改对象属性)
复制文件到目标路径
分块操作
API
操作名
操作描述
初始化分块复制
初始化分块复制任务
复制分块
将其他对象复制为一个分块
完成分块复制
完成整个对象的分块复制

简单操作

复制对象

功能说明

PUT Object - Copy 请求创建一个已存在 COS 的对象的副本,即将一个对象从源路径(对象键)复制到目标路径(对象键)。在复制的过程中,对象元数据和访问控制列表(ACL)可以被修改。 用户可以通过该接口创建副本、修改对象元属性(源对象和目标文件的属性相同)、移动或重命名对象(先复制,再单独调用删除接口)。
注意
建议对象大小1MB - 5GB,超过5GB的对象请使用高级接口复制对象 Slice Copy File。

使用示例

复制对象:

/* 把a/1.jpg复制一份到b/1.jpg */
cos.putObjectCopy({
Bucket: 'examplebucket-1250000000', /* 填入您自己的存储桶,必须字段 */
Region: 'COS_REGION', /* 存储桶所在地域,例如ap-beijing,必须字段 */
Key: 'b/1.jpg', /* 存储在桶里的对象键(例如1.jpg,a/b/test.txt),必须字段 */
CopySource: 'examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/a/1.jpg', /* 必须 */
/* CopySource中的Key含中文时,需要自行转义 */
// CopySource: `examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/${encodeURIComponent('a/中文文件名.jpg')}`,
}, function(err, data) {
console.log(err || data);
});

参数说明

参数名
参数描述
类型
是否必填
Bucket
存储桶的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String
是
Region
存储桶所在地域,枚举值请参见 地域和访问域名
String
是
Key
对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述
String
是
CopySource
源对象 URL 路径,可以通过 URL 参数 ?versionId=<versionId> 参数指定历史版本
String
是
ACL
定义对象的访问控制列表(ACL)属性,枚举值请参见 ACL 概述 文档中对象的预设 ACL 部分,例如 default,private,public-read 等
注意:如果您不需要进行对象 ACL 控制,请设置为 default 或者此项不进行设置,默认继承存储桶权限
String
否
GrantRead
赋予被授权者读取对象的权限。格式:id="[OwnerUin]",可使用半角逗号(,)分隔多组被授权者:
当需要给子账户授权时,id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
当需要给主账号授权时,id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
例如'id="qcs::cam::uin/100000000001:uin/100000000001",id="qcs::cam::uin/100000000001:uin/100000000011"'
String
否
GrantWrite
赋予被授权者写入对象的权限。格式:id="[OwnerUin]",可使用半角逗号(,)分隔多组被授权者:
当需要给子账户授权时,id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
当需要给主账号授权时,id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
例如'id="qcs::cam::uin/100000000001:uin/100000000001",id="qcs::cam::uin/100000000001:uin/100000000011"'
String
否
GrantFullControl
赋予被授权者操作对象的所有权限,格式:id="[OwnerUin]",可使用半角逗号(,)分隔多组被授权者:
当需要给子账户授权时,id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
当需要给主账号授权时,id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
例如'id="qcs::cam::uin/100000000001:uin/100000000001",id="qcs::cam::uin/100000000001:uin/100000000011"'
String
否
MetadataDirective
是否拷贝元数据,枚举值:Copy,Replaced,默认值 Copy。假如标记为 Copy,忽略 Header 中的用户元数据信息直接复制;假如标记为 Replaced,按 Header 信息修改元数据。当目标路径和原路径一致,即用户试图修改元数据时,必须为 Replaced
String
否
CopySourceIfModifiedSince
当对象在指定时间后被修改,则执行操作,否则返回412。可与 CopySourceIfNoneMatch 一起使用,与其他条件联合使用返回冲突
String
否
CopySourceIfUnmodifiedSince
当对象在指定时间后未被修改,则执行操作,否则返回412。可与 CopySourceIfMatch 一起使用,与其他条件联合使用返回冲突
String
否
CopySourceIfMatch
当对象的 ETag 和给定一致时,则执行操作,否则返回412。可与CopySourceIfUnmodifiedSince 一起使用,与其他条件联合使用返回冲突
String
否
CopySourceIfNoneMatch
当对象的 ETag 和给定不一致时,则执行操作,否则返回412。可与 CopySourceIfModifiedSince 一起使用,与其他条件联合使用返回冲突
String
否
StorageClass
设置对象的存储类型,枚举值:STANDARD、STANDARD_IA 等,默认值:STANDARD。更多存储类型请参见 存储类型概述
String
否
x-cos-meta-*
其他自定义的文件头部
String
否

回调函数说明

function(err, data) { ... }
参数名
参数描述
类型
err
请求发生错误时返回的对象,包括网络错误和业务错误。如果请求成功则为空,更多详情请参见 错误码
Object
- statusCode
请求返回的 HTTP 状态码,例如200、403、404等
Number
- headers
请求返回的头部信息
Object
data
请求成功时返回的对象,如果请求发生错误,则为空
Object
- statusCode
请求返回的 HTTP 状态码,例如200、403、404等
Number
- headers
请求返回的头部信息
Object
- ETag
文件的 MD5 算法校验值,例如"22ca88419e2ed4721c23807c678adbe4c08a7880",注意前后携带双引号
String
- LastModified
返回对象最后被修改时间,例如2017-06-23T12:33:27.000Z
String
- VersionId
在开启过版本控制的存储桶中上传对象返回对象的版本 ID,存储桶从未开启则不返回该参数
String

移动对象

功能说明

移动对象主要包括两个操作:复制源对象到目标位置,删除源对象。
由于 COS 通过存储桶名称(Bucket)和对象键(ObjectKey)来标识对象。移动对象也就意味着修改这个对象的标识,COS目前没有提供修改对象唯一标识名的单独接口,但是可以通过组合复制对象加上删除对象的基本操作,来达到修改对象标识的目的,从而实现移动对象。

使用示例

/* 把a/1.jpg移动到b/1.jpg */
/* 也可替换为高级复制cos.sliceCopyFile实现 */
cos.putObjectCopy({
Bucket: 'examplebucket-1250000000', /* 填入您自己的存储桶,必须字段 */
Region: 'COS_REGION', /* 存储桶所在地域,例如ap-beijing,必须字段 */
Key: 'b/1.jpg', /* 存储在桶里的对象键(例如1.jpg,a/b/test.txt),必须字段 */
CopySource: 'sourcebucket-1250000000.cos.ap-guangzhou.myqcloud.com/a/1.jpg', /* 必须 */
}, function(err, data) {
if (err) return console.log(err);
/* 删除a/1.jpg */
cos.deleteObject({
Bucket: 'examplebucket-1250000000', /* 必须 */
Region: 'COS_REGION', /* 存储桶所在地域,必须字段 */
Key: 'a/1.jpg' /* 必须 */
}, function(err, data) {
console.log(err || data);
});
});

修改对象存储类型

功能说明

修改对象存储类型通过复制对象(源和目的是同一个对象)时设置StorageClass实现。

使用示例

/* 把根目录下的1.jpg设置为归档存储类型 */
/* 也可替换为高级复制cos.sliceCopyFile实现 */
cos.putObjectCopy({
Bucket: 'examplebucket-1250000000', /* 填入您自己的存储桶,必须字段 */
Region: 'COS_REGION', /* 存储桶所在地域,例如ap-beijing,必须字段 */
Key: '1.jpg', /* 存储在桶里的对象键(例如1.jpg,a/b/test.txt),必须字段 */
CopySource: 'sourcebucket-1250000000.cos.ap-guangzhou.myqcloud.com/1.jpg', /* 必须 */
StorageClass: 'ARCHIVE', /* 设置为归档存储 */
}, function(err, data) {
console.log(err || data);
});

分块操作

初始化分块复制

功能说明

Initiate Multipart Upload 请求实现初始化分块复制,成功执行此请求后会返回 Upload ID ,用于后续的 Upload Part - Copy 请求。

使用示例

cos.multipartInit({
Bucket: 'examplebucket-1250000000', /* 填入您自己的存储桶,必须字段 */
Region: 'COS_REGION', /* 存储桶所在地域,例如ap-beijing,必须字段 */
Key: '1.jpg', /* 存储在桶里的对象键(例如1.jpg,a/b/test.txt),必须字段 */
}, function(err, data) {
console.log(err || data);
if (data) {
uploadId = data.UploadId;
}
});

参数说明

参数名
参数描述
类型
是否必填
Bucket
存储桶的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String
是
Region
存储桶所在地域,枚举值请参见 地域和访问域名
String
是
Key
对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述
String
是
CacheControl
RFC 2616 中定义的缓存策略,将作为对象的元数据保存
String
否
ContentDisposition
RFC 2616 中定义的文件名称,将作为对象的元数据保存
String
否
ContentEncoding
RFC 2616 中定义的编码格式,将作为对象的元数据保存
String
否
ContentType
RFC 2616 中定义的内容类型(MIME),将作为对象的元数据保存
String
否
Expires
RFC 2616 中定义的过期时间,将作为对象的元数据保存
String
否
ACL
定义对象的访问控制列表(ACL)属性,枚举值请参见 ACL 概述 文档中对象的预设 ACL 部分,如 default,private,public-read 等
注意:如果您不需要进行对象 ACL 控制,请设置为 default 或者此项不进行设置,默认继承存储桶权限
String
否
GrantRead
赋予被授权者读取对象的权限,格式:id="[OwnerUin]",可使用半角逗号(,)分隔多组被授权者:
当需要给子账号授权时,id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
当需要给主账号授权时,id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
例如'id="qcs::cam::uin/100000000001:uin/100000000001",id="qcs::cam::uin/100000000001:uin/100000000011"'
String
否
GrantFullControl
赋予被授权者操作对象的所有权限,格式:id="[OwnerUin]",可使用半角逗号(,)分隔多组被授权者:
当需要给子账号授权时,id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
当需要给主账号授权时,id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
例如'id="qcs::cam::uin/100000000001:uin/100000000001",id="qcs::cam::uin/100000000001:uin/100000000011"'
String
否
StorageClass
设置对象的存储类型,枚举值:STANDARD、STANDARD_IA、ARCHIVE 等,更多存储类型请参见 存储类型概述 文档。默认值:STANDARD
String
否
x-cos-meta-*
允许用户自定义的头部信息,将作为对象的元数据返回。大小限制2KB
String
否

回调函数说明

function(err, data) { ... }
参数名
参数描述
类型
err
请求发生错误时返回的对象,包括网络错误和业务错误,如果请求成功则为空,更多详情请参见 错误码 文档
Object
data
请求成功时返回的对象,如果请求发生错误,则为空
Object
Bucket
分块上传的目标存储桶,格式为 BucketName-APPID,例如 examplebucket-1250000000
String
Key
对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述
String
UploadId
在后续上传中使用的 ID
String

复制分块

功能说明

Upload Part - Copy 接口请求实现将一个对象的分块内容从源路径复制到目标路径。
注意
使用上传分块对象,必须先初始化分块上传。在初始化分块上传的响应中,会返回一个唯一的描述符(upload ID),您需要在分块上传请求中携带此 ID。

使用示例

cos.uploadPartCopy({
Bucket: 'examplebucket-1250000000', /* 填入您自己的存储桶,必须字段 */
Region: 'COS_REGION', /* 存储桶所在地域,例如ap-beijing,必须字段 */
Key: '1.jpg', /* 存储在桶里的对象键(例如1.jpg,a/b/test.txt),必须字段 */
CopySource: 'sourcebucket-1250000000.cos.ap-guangzhou.myqcloud.com/sourceObject', /* 必须 */
UploadId: 'exampleUploadId', /* 必须 */
PartNumber: '1', /* 必须 */
}, function(err, data) {
console.log(err || data);
if (data) {
eTag = data.ETag;
}
});

参数说明

参数名
参数描述
类型
是否必填
Bucket
存储桶的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String
是
Region
存储桶所在地域,枚举值请参见 地域和访问域名
String
是
Key
对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述
String
是
CopySource
源对象 URL 路径,可以通过 URL 参数 ?versionId=<versionId> 参数指定历史版本
String
是
PartNumber
分块拷贝的块号
String
是
UploadId
使用上传分块文件,必须先初始化分块上传。在初始化分块上传的响应中,会返回一个唯一的描述符(upload ID),您需要在分块上传请求中携带此 ID
String
是
CopySourceRange
源对象的字节范围,范围值必须使用 bytes=first-last 格式,first 和 last 都是基于0开始的偏移量。例如 bytes=0-9 表示您希望拷贝源对象的开头10个字节的数据 ,如果不指定,则表示拷贝整个对象
String
否
CopySourceIfMatch
当对象的 ETag 和给定一致时,则执行操作,否则返回412,可与 x-cos-copy-source-If-Unmodified-Since 一起使用,与其他条件联合使用返回冲突
String
否
CopySourceIfNoneMatch
当对象的 ETag 和给定不一致时,则执行操作,否则返回412,可与 x-cos-copy-source-If-Modified-Since 一起使用,与其他条件联合使用返回冲突
String
否
CopySourceIfUnmodifiedSince
当对象在指定时间后未被修改,则执行操作,否则返回412,可与 x-cos-copy-source-If-Match 一起使用,与其他条件联合使用返回冲突
String
否
CopySourceIfModifiedSince
当对象在指定时间后被修改,则执行操作,否则返回412,可与 x-cos-copy-source-If-None-Match 一起使用,与其他条件联合使用返回冲突
String
否

回调函数说明

function(err, data) { ... }
参数名
参数描述
类型
err
请求发生错误时返回的对象,包括网络错误和业务错误。如果请求成功则为空,更多详情请参见 错误码 文档
Object
- statusCode
请求返回的 HTTP 状态码,例如200、403、404等
Number
- headers
请求返回的头部信息
Object
data
请求成功时返回的对象,如果请求发生错误,则为空
Object
- statusCode
请求返回的 HTTP 状态码,例如200、403、404等
Number
- headers
请求返回的头部信息
Object
- ETag
文件的 MD5 算法校验值,例如"22ca88419e2ed4721c23807c678adbe4c08a7880",注意前后携带双引号
String
- LastModified
返回对象最后修改时间,GMT 格式
String

完成分块复制

功能说明

Complete Multipart Upload 接口请求用来实现完成整个分块复制。当使用 Copy Parts 复制完所有块以后,必须调用该 API 来完成整个文件的分块复制。在使用该 API 时,您必须在请求 Body 中给出每一个块的 PartNumber 和 ETag,用来校验块的准确性。 由于分块复制完后需要合并,而合并需要数分钟时间,因而当合并分块开始的时候,COS 就立即返回200的状态码,在合并的过程中,COS 会周期性的返回空格信息来保持连接活跃,直到合并完成,COS 会在 Body 中返回合并后块的内容。
当上传块小于1MB ,在调用该 API 时,会返回400 EntityTooSmall。
当上传块编号不连续,在调用该 API 时,会返回400 InvalidPart。
当请求 Body 中的块信息未按序号从小到大排列,在调用该 API 时,会返回400 InvalidPartOrder。
当 UploadId 不存在,在调用该 API 时,会返回404 NoSuchUpload。
注意
建议您及时完成分块上传或者舍弃分块上传,因为已上传但是未终止的块会占用存储空间进而产生存储费用。

使用示例

cos.multipartComplete({
Bucket: 'examplebucket-1250000000', /* 填入您自己的存储桶,必须字段 */
Region: 'COS_REGION', /* 存储桶所在地域,例如ap-beijing,必须字段 */
Key: '1.jpg', /* 存储在桶里的对象键(例如1.jpg,a/b/test.txt),必须字段 */
UploadId: 'exampleUploadId', /* 初始化分块任务时拿到,必须 */
Parts: [
{PartNumber: '1', ETag: 'exampleETag'},
]
}, function(err, data) {
console.log(err || data);
});

参数说明

参数名
参数描述
类型
是否必填
Bucket
存储桶的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String
是
Region
存储桶所在地域,枚举值请参见 地域和访问域名
String
是
Key
对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述
String
是
UploadId
上传任务编号
String
是
Parts
用来说明本次分块上传中块的信息列表
ObjectArray
是
- PartNumber
分块的编号
String
是
- ETag
每个块文件的 MD5 算法校验值
例如"22ca88419e2ed4721c23807c678adbe4c08a7880",注意前后携带双引号
String
是

回调函数说明

function(err, data) { ... }
参数名
参数描述
类型
err
请求发生错误时返回的对象,包括网络错误和业务错误,如果请求成功则为空,更多详情请参见 错误码 文档
Object
- statusCode
请求返回的 HTTP 状态码,例如200、403、404等
Number
- headers
请求返回的头部信息
Object
data
请求成功时返回的对象,如果请求发生错误,则为空
Object
- statusCode
请求返回的 HTTP 状态码,例如200、403、404等
Number
- headers
请求返回的头部信息
Object
- Location
创建对象的外网访问域名
String
- Bucket
分块上传的目标存储桶
String
- Key
对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述
String
- ETag
合并后文件的唯一 ID,格式:"uuid-<分块数>"
例如"22ca88419e2ed4721c23807c678adbe4c08a7880-3",注意前后携带双引号
String

高级接口(推荐)

强烈建议您使用高级接口,该类方法是对上面原生方法的封装,实现了分块复制的全过程。

分块复制对象

功能说明

Slice Copy File 可用于实现通过分块复制将一个文件从源路径复制到目标路径。在拷贝的过程中,对象元属性和 ACL 可以被修改。用户可以通过该接口实现文件移动,文件重命名,修改文件属性和创建副本。

方法原型

调用 Slice Copy File 操作:
/* 把a/1.jpg复制到b/1.jpg */
cos.sliceCopyFile({
Bucket: 'examplebucket-1250000000', /* 填入您自己的存储桶,必须字段 */
Region: 'COS_REGION', /* 存储桶所在地域,例如ap-beijing,必须字段 */
Key: 'b/1.jpg', /* 存储在桶里的对象键(例如1.jpg,a/b/test.txt),必须字段 */
CopySource: 'sourcebucket-1250000000.cos.ap-guangzhou.myqcloud.com/a/1.jpg', /* 必须 */
onProgress:function (progressData) { /* 非必须 */
console.log(JSON.stringify(progressData));
}
},function (err,data) {
console.log(err || data);
});

参数说明

参数名
参数描述
类型
是否必填
Bucket
存储桶的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String
是
Region
存储桶所在地域,枚举值请参见 地域和访问域名
String
是
Key
对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述
String
是
CopySource
源对象 URL 路径,可以通过 URL 参数 ?versionId=<versionId> 参数指定历史版本
String
是
ChunkSize
分块复制时,每片的大小字节数,默认值 1048576(1MB)
Number
否
SliceSize
表示文件大小超出一个数值时使用分块复制,单位 Byte,默认值5G。小于等于该数值会使用 putObjectCopy 上传,大于该数值会使用 sliceCopyFile 上传
Number
否
onProgress
上传文件的进度回调函数,回调参数为进度对象 progressData
Function
否
- progressData.loaded
已经上传的文件部分大小,以字节(Bytes)为单位
Number
否
- progressData.total
整个文件的大小,以字节(Bytes)为单位
Number
否
- progressData.speed
文件的上传速度,以字节/秒(Bytes/s)为单位
Number
否
- progressData.percent
文件的上传百分比,以小数形式呈现,例如:上传50%即为0.5
Number
否

回调函数说明

function(err, data) { ... }
参数名
参数描述
类型
err
请求发生错误时返回的对象,包括网络错误和业务错误,如果请求成功则为空,更多详情请参见 错误码 文档
Object
- statusCode
请求返回的 HTTP 状态码,例如200、403、404等
Number
- headers
请求返回的头部信息
Object
data
请求成功时返回的对象,如果请求发生错误,则为空
Object
- statusCode
请求返回的 HTTP 状态码,例如200、403、404等
Number
- headers
请求返回的头部信息
Object
- Location
创建对象的外网访问域名
String
- Bucket
分块上传的目标存储桶
String
- Key
对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述
String
- ETag
合并后文件的 MD5 算法校验值
例如"22ca88419e2ed4721c23807c678adbe4c08a7880",注意前后携带双引号
String
- VersionId
在开启过版本控制的存储桶中上传对象返回对象的版本 ID,存储桶从未开启则不返回该参数
String

帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈