tencent cloud

文档反馈

复制与移动对象

最后更新时间:2022-01-10 15:01:18

    简介

    本文档提供关于对象的复制、移动操作相关的 API 概览以及 SDK 示例代码。

    简单操作

    API 操作名 操作描述
    PUT Object - Copy 设置对象复制(修改对象属性) 复制文件到目标路径

    分块操作

    API 操作名 操作描述
    Initiate Multipart Upload 初始化分块复制 初始化分块复制任务
    Upload Part - Copy 复制分块 将其他对象复制为一个分块
    Complete Multipart Upload 完成分块复制 完成整个对象的分块复制

    简单操作

    复制对象

    功能说明

    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', /* 必须 */
    }, 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、ARCHIVE 等,更多存储类型请参见 存储类型概述 文档。默认值: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 Uploads 请求实现初始化分块复制,成功执行此请求后会返回 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
    联系我们

    联系我们,为您的业务提供专属服务。

    技术支持

    如果你想寻求进一步的帮助,通过工单与我们进行联络。我们提供7x24的工单服务。

    7x24 电话支持