有奖征文:轻量对象存储LighthouseCOS用户实践> HOT

简介

本文档提供关于对象的复制、移动操作相关的 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、DEEP_ARCHIVE 等,默认值:STANDARD。更多存储类型请参见 存储类型概述
String
x-cos-meta-*
允许用户自定义的头部信息,将作为对象的元数据返回。大小限制2KB
String
UploadAddMetaMd5
当复制时,给对象的元数据信息增加 x-cos-meta-md5 赋值为对象内容的 MD5 值,格式为 32 位小写字符串。例如:4d00d79b6733c9cc066584a02ed03410
String

回调函数说明

function(err, data) { ... }
参数名
参数描述
类型
err
请求发生错误时返回的对象,包括网络错误和业务错误。如果请求成功则为空,更多详情请参见 错误码
Object
data
请求成功时返回的对象,如果请求发生错误,则为空
Object
Bucket
目标存储桶,由用户自定义字符串和系统生成 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