tencent cloud

PrevNext

文档反馈

请输入关键字

Recent Pages

文档
对象存储
    文档
    Download PDF

    复制与移动对象

    最后更新时间：2024-01-22 11:23:32
    下载PDF

      简介

      本文档提供关于对象的复制、移动操作相关的 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、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 电话支持
      Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
      隐私条款服务条款缓存条款