tencent cloud

PrevNext

文档反馈

请输入关键字

Recent Pages

文档
对象存储
    文档
    Download PDF

    Complete Multipart Upload

    最后更新时间：2024-09-26 16:50:11
    下载PDF

      功能描述

      Complete Multipart Upload 接口请求用来实现完成整个分块上传。当使用 Upload Part 上传所有分块完成后，必须调用该 API 来完成整个文件的分块上传。在使用该 API 时，您必须在请求体中给出每一个块的 PartNumber 和 ETag，用来校验块的准确性。
      由于分块上传完成后需要合并，而合并需要数分钟时间，因而当合并分块开始时，COS 会立即返回200的状态码并指定 Transfer-Encoding: chunked 响应头部，在合并的过程中，COS 会周期性的使用 chunked 方式返回空格信息来保持连接活跃，直到合并完成，COS 会在最后一个 chunk 中返回合并完成后整个对象的信息。
      当上传的分块小于1MB的时候，在调用该 API 时，会返回400 EntityTooSmall。
      当上传块编号不连续的时候，在调用该 API 时，会返回400 InvalidPart。
      当请求 Body 中的块信息没有按序号从小到大排列的时候，在调用该 API 时，会返回400 InvalidPartOrder。
      当 UploadId 不存在的时候，在调用该 API 时，会返回404 NoSuchUpload。
      说明
      只有主账号或者被授权 Complete Multipart Upload 接口权限的子账号可以调用该接口。
      注意
      建议您及时完成分块上传或者舍弃分块上传，因为已上传但是未终止的块会占用存储空间进而产生存储费用。
      

      版本控制

      如果对存储桶启用版本控制，对象存储将自动为要添加的对象生成唯一的版本 ID。对象存储使用 x-cos-version-id 响应头部在响应中返回此标识。
      如果暂停存储桶的版本控制，则对象存储始终将 null 用作存储在存储桶中的对象的版本 ID，并返回 x-cos-version-id: null 响应头部。

      请求

      请求示例

      POST /<ObjectKey>?uploadId=UploadId HTTP/1.1
      Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
      Date: GMT Date
      Content-Type: application/xml
      Content-Length: Content Length
      Content-MD5: MD5
      Authorization: Auth String
      
      [Request Body]
      说明
      Host: <BucketName-APPID>.cos.<Region>.myqcloud.com，其中 <BucketName-APPID> 为带 APPID 后缀的存储桶名字，例如 examplebucket-1250000000，可参阅 存储桶概览 > 基本信息 和 存储桶概述 > 存储桶命名规范 文档；<Region> 为 COS 的可用地域，可参阅 地域和访问域名 文档。
      Authorization: Auth String（详情请参见 请求签名 文档）。

      请求参数

      名称
      描述
      类型
      是否必选
      uploadId
      标识本次分块上传的 ID，使用 Initiate Multipart Upload 接口初始化分块上传时得到的 UploadId。
      string
      是

      请求头

      此接口除使用公共请求头部外，还支持以下请求头部，了解公共请求头部详情请参见 公共请求头部 文档。
      名称
      描述
      类型
      是否必选
      x-cos-forbid-overwrite
      针对未开启版本控制的存储桶，上传文件时，用于指定上传操作时是否禁止覆盖同名对象：
      不携带 x-cos-forbid-overwrite 头部或指定为 false 时，默认覆盖同名 Object；
      指定 x-cos-forbid-overwrite 为true时，表示禁止覆盖同名 Object。
      注意：
      当存储桶处于已开启或已暂停的版本控制状态时，x-cos-forbid-overwrite 设置无效，即允许覆盖同名对象。
      String
      否

      请求体

      提交 application/xml 请求数据，包含所有分块信息。
      <CompleteMultipartUpload>
          <Part>
              <PartNumber>integer</PartNumber>
              <ETag>string</ETag>
          </Part>
          <Part>
              <PartNumber>integer</PartNumber>
              <ETag>string</ETag>
          </Part>
      </CompleteMultipartUpload>
      具体的节点描述如下：
      节点名称（关键字）
      父节点
      描述
      类型
      是否必选
      CompleteMultipartUpload
      无
      包含 Complete Multipart Upload 操作的所有请求信息
      Container
      否
      Container 节点 CompleteMultipartUpload 的内容：
      节点名称（关键字）
      父节点
      描述
      类型
      是否必选
      Part
      CompleteMultipartUpload
      用来说明本次分块上传中每个块的信息
      Container
      是
      Container 节点 Part 的内容：
      节点名称（关键字）
      父节点
      描述
      类型
      是否必选
      PartNumber
      CompleteMultipartUpload.Part
      块编号
      integer
      是
      ETag
      CompleteMultipartUpload.Part
      使用 Upload Part 请求上传分块成功后返回的 ETag 响应头部的值
      string
      是

      响应

      响应头

      此接口除返回公共响应头部外，还返回以下响应头部，了解公共响应头部详情请参见 公共响应头部 文档。
      版本控制相关头部
      在启用版本控制的存储桶中上传对象，将返回下列响应头部：
      名称
      描述
      类型
      x-cos-version-id
      对象的版本 ID
      string
      服务端加密（SSE）相关头部
      如果在上传对象时使用了服务端加密，则此接口将返回服务端加密专用头部，请参见 服务端加密专用头部。

      响应体

      请求成功，返回 application/xml 数据，包含合并完成后的整个对象信息。
      <?xml version="1.0" encoding="UTF-8"?>
      <CompleteMultipartUploadResult xmlns="http://www.qcloud.com/document/product/436/7751">
          <Location>string</Location>
          <Bucket>string</Bucket>
          <Key>string</Key>
          <ETag>string</ETag>
      </CompleteMultipartUploadResult>
      具体的节点描述如下：
      节点名称（关键字）
      父节点
      描述
      类型
      CompleteMultipartUploadResult
      无
      保存 Complete Multipart Upload 结果的所有信息
      Container
      Container 节点 CompleteMultipartUploadResult 的内容：
      节点名称（关键字）
      父节点
      描述
      类型
      Location
      CompleteMultipartUploadResult
      分块上传完成的对象位置，格式为http://<BucketName-APPID>.cos.<Region>.myqcloud.com/<ObjectKey>，例如http://examplebucket-1250000000.cos.ap-beijing.myqcloud.com/exampleobject
      string
      Bucket
      CompleteMultipartUploadResult
      分块上传的目标存储桶，格式为<BucketName-APPID>，例如examplebucket-1250000000
      string
      Key
      CompleteMultipartUploadResult
      对象键
      string
      ETag
      CompleteMultipartUploadResult
      分块合并后的对象 ETag 值
      string

      错误码

      此接口遵循统一的错误响应和错误码，详情请参见 错误码 文档。

      实际案例

      此接口响应默认为 Transfer-Encoding: chunked 编码方式，为了方便阅读，本文档实际案例均采用无 Transfer-Encoding 的方式展示，在使用过程中，不同语言和库可以自动处理这种编码形式，请开发者注意识别和处理，更多信息请查阅语言和库的相关文档。

      案例一：简单案例（未启用版本控制）

      请求

      POST /exampleobject?uploadId=1585130821cbb7df1d11846c073ad648e8f33b087cec2381df437acdc833cf654b9ecc6361 HTTP/1.1
      Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
      Date: Wed, 25 Mar 2020 10:07:26 GMT
      Content-Type: application/xml
      Content-Length: 353
      Content-MD5: Me/0Gvtc2x4VPIOhoIRllw==
      Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1585130846;1585138046&q-key-time=1585130846;1585138046&q-header-list=content-length;content-md5;content-type;date;host&q-url-param-list=uploadid&q-signature=45dae7b1a54930587f8123954664b1b5148b****
      Connection: close
      
      <CompleteMultipartUpload>
          <Part>
              <PartNumber>1</PartNumber>
              <ETag>"39270a968a357d24207e9911162507eb"</ETag>
          </Part>
          <Part>
              <PartNumber>2</PartNumber>
              <ETag>"d899fbd1e06109ea2e4550f5751c88d6"</ETag>
          </Part>
          <Part>
              <PartNumber>3</PartNumber>
              <ETag>"762890d6c9a871b7bd136037cb2260cd"</ETag>
          </Part>
      </CompleteMultipartUpload>

      响应

      HTTP/1.1 200 OK
      Content-Type: application/xml
      Content-Length: 378
      Connection: close
      Date: Wed, 25 Mar 2020 10:07:26 GMT
      Server: tencent-cos
      x-cos-hash-crc64ecma: 2290339086971918696
      x-cos-request-id: NWU3YjJkNWVfZDFjODJhMDlfMTk2ODJfMmEyNTA0****
      
      <?xml version="1.0" encoding="UTF-8"?>
      <CompleteMultipartUploadResult xmlns="http://www.qcloud.com/document/product/436/7751">
          <Location>http://examplebucket-1250000000.cos.ap-beijing.myqcloud.com/exampleobject</Location>
          <Bucket>examplebucket-1250000000</Bucket>
          <Key>exampleobject</Key>
          <ETag>&quot;aa259a62513358f69e98e72e59856d88-3&quot;</ETag>
      </CompleteMultipartUploadResult>

      案例二：使用服务端加密 SSE-COS

      请求

      POST /exampleobject?uploadId=1590862540251355295a5c736513d70d42b92bbde4f0fafb5e0ecb314b55aa0018cc9fa76f HTTP/1.1
      Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
      Date: Sat, 30 May 2020 18:16:08 GMT
      Content-Type: application/xml
      Content-Length: 153
      Content-MD5: wmpyfdr9s/A+VCBwDdC1bA==
      Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1590862568;1590869768&q-key-time=1590862568;1590869768&q-header-list=content-length;content-md5;content-type;date;host&q-url-param-list=uploadid&q-signature=abe1fd2d2c057c8f3e4d331a0448b06ecf5b****
      Connection: close
      
      <CompleteMultipartUpload>
          <Part>
              <PartNumber>1</PartNumber>
              <ETag>"108f528eb63b65e734f27ae331f5ffaa"</ETag>
          </Part>
      </CompleteMultipartUpload>

      响应

      HTTP/1.1 200 OK
      Content-Type: application/xml
      Content-Length: 378
      Connection: close
      Date: Sat, 30 May 2020 18:16:08 GMT
      Server: tencent-cos
      x-cos-hash-crc64ecma: 4510578591875220731
      x-cos-request-id: NWVkMmEyZThfYTJjMjJhMDlfMmQzOV8zYTM5****
      x-cos-server-side-encryption: AES256
      
      <?xml version="1.0" encoding="UTF-8"?>
      <CompleteMultipartUploadResult xmlns="http://www.qcloud.com/document/product/436/7751">
          <Location>http://examplebucket-1250000000.cos.ap-beijing.myqcloud.com/exampleobject</Location>
          <Bucket>examplebucket-1250000000</Bucket>
          <Key>exampleobject</Key>
          <ETag>&quot;915fca1c3b2737c262458b3a1a43c683-1&quot;</ETag>
      </CompleteMultipartUploadResult>

      案例三：使用服务端加密 SSE-KMS

      请求

      POST /exampleobject?uploadId=15908625793957d71176fa878282d266a95b79dc2aec159b4a73d1d79c80d4f931cda6ad65 HTTP/1.1
      Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
      Date: Sat, 30 May 2020 18:16:40 GMT
      Content-Type: application/xml
      Content-Length: 153
      Content-MD5: jUFgTSZThmPT3qseea0mRQ==
      Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1590862600;1590869800&q-key-time=1590862600;1590869800&q-header-list=content-length;content-md5;content-type;date;host&q-url-param-list=uploadid&q-signature=68aaf036efac07ef8d6ef101f81a1589849a****
      Connection: close
      
      <CompleteMultipartUpload>
          <Part>
              <PartNumber>1</PartNumber>
              <ETag>"1d3e8ae9da423b440341b09f1616f074"</ETag>
          </Part>
      </CompleteMultipartUpload>

      响应

      HTTP/1.1 200 OK
      Content-Type: application/xml
      Content-Length: 378
      Connection: close
      Date: Sat, 30 May 2020 18:16:40 GMT
      Server: tencent-cos
      x-cos-hash-crc64ecma: 4510578591875220731
      x-cos-request-id: NWVkMmEzMDhfYzhjODJhMDlfMjNhYTBfMjdmNjNl****
      x-cos-server-side-encryption: cos/kms
      x-cos-server-side-encryption-cos-kms-key-id: 48ba38aa-26c5-11ea-855c-52540085****
      
      <?xml version="1.0" encoding="UTF-8"?>
      <CompleteMultipartUploadResult xmlns="http://www.qcloud.com/document/product/436/7751">
          <Location>http://examplebucket-1250000000.cos.ap-beijing.myqcloud.com/exampleobject</Location>
          <Bucket>examplebucket-1250000000</Bucket>
          <Key>exampleobject</Key>
          <ETag>&quot;8093dc3e18f7070444e6ca21789eb8d4-1&quot;</ETag>
      </CompleteMultipartUploadResult>
      

      案例四：使用服务端加密 SSE-C

      请求

      POST /exampleobject?uploadId=1590862610acd643927bad05cd3947bf98b56b04b0b0b2a45a49969f87cc95b7fd5fcc065a HTTP/1.1
      Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
      Date: Sat, 30 May 2020 18:17:11 GMT
      Content-Type: application/xml
      Content-Length: 153
      Content-MD5: MnXmb3yvrbwMfBlUwUE1Hg==
      Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1590862631;1590869831&q-key-time=1590862631;1590869831&q-header-list=content-length;content-md5;content-type;date;host&q-url-param-list=uploadid&q-signature=5ce15a35c591eb797e8abaf210313e58ac03****
      Connection: close
      
      <CompleteMultipartUpload>
          <Part>
              <PartNumber>1</PartNumber>
              <ETag>"ff14981a35a58eb97bca838b055c573b"</ETag>
          </Part>
      </CompleteMultipartUpload>

      响应

      HTTP/1.1 200 OK
      Content-Type: application/xml
      Content-Length: 378
      Connection: close
      Date: Sat, 30 May 2020 18:17:11 GMT
      Server: tencent-cos
      x-cos-hash-crc64ecma: 4510578591875220731
      x-cos-request-id: NWVkMmEzMjdfODljOTJhMDlfMzQ2ZDNfMWMwZWYy****
      x-cos-server-side-encryption-customer-algorithm: AES256
      x-cos-server-side-encryption-customer-key-MD5: U5L61r7jcwdNvT7frmUG8g==
      
      <?xml version="1.0" encoding="UTF-8"?>
      <CompleteMultipartUploadResult xmlns="http://www.qcloud.com/document/product/436/7751">
          <Location>http://examplebucket-1250000000.cos.ap-beijing.myqcloud.com/exampleobject</Location>
          <Bucket>examplebucket-1250000000</Bucket>
          <Key>exampleobject</Key>
          <ETag>&quot;55973f71e8e892273053617e6b83d1c7-1&quot;</ETag>
      </CompleteMultipartUploadResult>

      案例五：启用版本控制

      请求

      POST /exampleobject?uploadId=15908626631e1995018f81a5e563837d6d7f1b51d7c97dff09989296403e32366e52f2877b HTTP/1.1
      Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
      Date: Sat, 30 May 2020 18:18:04 GMT
      Content-Type: application/xml
      Content-Length: 153
      Content-MD5: wmpyfdr9s/A+VCBwDdC1bA==
      Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1590862684;1590869884&q-key-time=1590862684;1590869884&q-header-list=content-length;content-md5;content-type;date;host&q-url-param-list=uploadid&q-signature=5409509944602014d1b61cb4bbe1e39003b4****
      Connection: close
      
      <CompleteMultipartUpload>
          <Part>
              <PartNumber>1</PartNumber>
              <ETag>"108f528eb63b65e734f27ae331f5ffaa"</ETag>
          </Part>
      </CompleteMultipartUpload>

      响应

      HTTP/1.1 200 OK
      Content-Type: application/xml
      Content-Length: 378
      Connection: close
      Date: Sat, 30 May 2020 18:18:04 GMT
      Server: tencent-cos
      x-cos-hash-crc64ecma: 4510578591875220731
      x-cos-request-id: NWVkMmEzNWNfOGNjOTJhMDlfMWQ4NjJfMWM0NGUw****
      x-cos-version-id: MTg0NDUxNTMyMTEwNDU1NDc3OTc
      
      <?xml version="1.0" encoding="UTF-8"?>
      <CompleteMultipartUploadResult xmlns="http://www.qcloud.com/document/product/436/7751">
          <Location>http://examplebucket-1250000000.cos.ap-beijing.myqcloud.com/exampleobject</Location>
          <Bucket>examplebucket-1250000000</Bucket>
          <Key>exampleobject</Key>
          <ETag>&quot;42318fc0ec58952b0d9ab4d7a006f595-1&quot;</ETag>
      </CompleteMultipartUploadResult>

      案例六：暂停版本控制

      请求

      POST /exampleobject?uploadId=1590862705b4349d597c0db1281e1c666bc431eb468b3a64076be7093c91a963bc5ead2ea4 HTTP/1.1
      Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
      Date: Sat, 30 May 2020 18:18:45 GMT
      Content-Type: application/xml
      Content-Length: 153
      Content-MD5: wmpyfdr9s/A+VCBwDdC1bA==
      Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1590862725;1590869925&q-key-time=1590862725;1590869925&q-header-list=content-length;content-md5;content-type;date;host&q-url-param-list=uploadid&q-signature=b212e42daaeabcd2b8e9f6722b62fe8d618b****
      Connection: close
      
      <CompleteMultipartUpload>
          <Part>
              <PartNumber>1</PartNumber>
              <ETag>"108f528eb63b65e734f27ae331f5ffaa"</ETag>
          </Part>
      </CompleteMultipartUpload>

      响应

      HTTP/1.1 200 OK
      Content-Type: application/xml
      Content-Length: 378
      Connection: close
      Date: Sat, 30 May 2020 18:18:45 GMT
      Server: tencent-cos
      x-cos-hash-crc64ecma: 4510578591875220731
      x-cos-request-id: NWVkMmEzODVfZjZjMjBiMDlfNGYzZV8zODc4****
      x-cos-version-id: null
      
      <?xml version="1.0" encoding="UTF-8"?>
      <CompleteMultipartUploadResult xmlns="http://www.qcloud.com/document/product/436/7751">
          <Location>http://examplebucket-1250000000.cos.ap-beijing.myqcloud.com/exampleobject</Location>
          <Bucket>examplebucket-1250000000</Bucket>
          <Key>exampleobject</Key>
          <ETag>&quot;491509b1fdf8e13d1f51d323c4a6d0e8-1&quot;</ETag>
      </CompleteMultipartUploadResult>
      
      联系我们

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

      联系我们
      技术支持

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

      提交工单
      7x24 电话支持
      Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
      隐私条款服务条款缓存条款