MultipartUpload相关接口

MultipartUpload相关接口用于实现BOS的“三步上传”和“三步Copy”功能。

  • 三步上传:请求者将一个Object拆分成多个分块(又称Part),然后分别上传这些分块。当所有分块全部上传完成后,BOS将请求者上传的所有分块组合成完整Object。MultipartUpload常使用于流式上传,大文件上传和断点上传。MultipartUpload上传有InitiateMultipartUpload,UploadPart和CompleteMultipartUpload三个步骤,俗称“三步上传”。 三步上传相关的接口包括:

  • 三步Copy:三步Copy和三步上传实现原理类似,将一个Object分块复制,最后再合并为一个完整的Object。三步Copy通过将大任务切分为小任务,可以并发复制,提高了文件的复制效率和成功率。三步Copy有InitiateMultipartUpload,UploadPartCopy和CompleteMultipartUpload三个步骤,相关接口包括:

InitiateMultipartUpload接口

接口描述

InitiateMultipartUpload是MultipartUpload的第一步,此命令向BOS请求一个全局唯一的UploadId,用于表示此次MultipartUpload,在MultipartUpload后续两个步骤都需要此UploadId,请求者也可以通过UploadId来查询上传的进度或者中断这次上传操作。

请求(Request)

  • 请求语法

    POST /<ObjectKey>?uploads HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    Date: <Date>
    Authorization: <Authorization_String>
    Content-Type: text/plain
    Content-Length: <Content_Length>
    x-bce-storage-class: <Storage_class>
    
  • 请求头域

    名称 类型 描述 是否必需
    x-bce-storage-class String 指定BOS的对象的存储类型,目前支持STANDARDSTANDARD_IACOLD 否,默认为STANDARD
    x-bce-acl String CannedACL支持的header,用户设置Object的权限,取值为private和public-read。
    x-bce-grant-read String CannedACL支持的header,用户设置Object的读权限。支持多个id,以逗号分隔
    x-bce-grant-full-control String CannedACL支持的header,用户设置Object的FULL_CONTROL权限。支持多个id,以逗号分隔
    x-bce-server-side-encryption String 服务端加密算法,当前仅支持AES256。
    Cache-Control String 下载Object的Cache设置,常见的可取值为privateno-cachemax-agemust-revalidate
    Content-Disposition String 设置浏览器是否下载,可取值为inlineattachment; filename="download.txt"
    Content-Type String Object的类型及编码方式
    Expires String 设置下载Object时的缓存失效时间
  • 请求参数

    名称 类型 描述 是否必需
    Uploads String Url的queryString

响应(Response)

  • 响应头域

  • 响应元素

    名称 类型 描述
    bucket String Bucket名称
    key String Object名称
    uploadId String 全局唯一ID,用于标识此次MultiUpload操作

    注意事项

    1. 使用MultipartUpload上传的Object,必须在第一步InitMultipartUpload时指定Content-Type,如不指定,默认为application/octet-stream。随后步骤中的Content-Type为对应Body实际的Type,不设置为最终Object的Content-Type。
    2. InitiateMultipartUpload获取的UploadId将用于MultiUpload的后续2步操作,也可以用此UploadId来查询整个MultiUpload的进度和中断此次MultiUpload操作。

示例

  • 标准存储的请求示例

    POST /object?uploads
    Host: BucketName.bj.bcebos.com
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Authorization: AuthorizationString
    Content-Length: 0
    
  • 低频/冷存储的请求示例

    POST /object?uploads
    Host: BucketName.bj.bcebos.com
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Authorization: AuthorizationString
    Content-Length: 0
    x-bce-storage-class: STANDARD_IA
    
  • 响应示例

    HTTP/1.1 200 OK
    x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
    Date:  Wed, 06 Apr 2016 06:34:40 GMT
    Content-Length: 197
    Connection: keep-alive
    Server: BceBos
    
    {
        "bucket": "BucketName",
        "key":"object",
        "uploadId": "a44cc9bab11cbd156984767aad637851"
    }
    

UploadPart接口

接口描述

在调用InitiateMultipartUpload获取UploadId后,我们需要用UploadPart命令来上传Object拆分后的数据(Part)。为了标识各个Part在Object的相对位置,在UploadPart需要指定一个partNumber参数,partNumber的取值范围是1-10000。BOS Part的大小有一定限制,除最后一个part外,其他part需要大于等于5MB,或者是1MB的整数倍,单个part不能超过5GB,且整个Object的大小不能超过5TB。

请求(Request)

  • 请求语法

    PUT /<ObjectKey>?partNumber=PartNumber&uploadId=UploadId HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    Date: <Date>
    Authorization: <Authorization_String>
    Content-Length: <Content_Length>
    
  • 请求头域

    名字 类型 描述
    Content-MD5 String RFC2616定义的HTTP请求内容的MD5摘要,可以通过携带该字段来验证保存在BOS侧的文件和用户预期的文件是否一致。
    x-bce-content-sha256 String 通过携带该字段来验证保存在BOS侧的文件和用户预期的文件是否一致,sha256的校验准确性更高。所传数据的sha256值必须与此匹配,否则UploadPart失败。
    x-bce-content-crc32 String 上传object的CRC值(循环冗余校验码)。
  • 请求参数

    名称 类型 描述 是否必需
    partNumber Int 本次上传的part在object的相对位置
    uploadId String InitiateMultipartUpload获取的UploadId

响应(Response)

  • 响应元素

  • 响应头域

    名称 类型 描述
    ETag String 每个上传分块的ETag
    其他 - 其他RFC2616相关的Header字段

    注意事项

    1. CompleteMultipartUpload的请求Body最大为1MB。
    2. UploadPart会返回本次Part的ETag,在MultipartUpload的第三步中需要此ETag,也建议用户用ETag验证上传数据的正确性。
    3. 一次MultiPart的PartNumber要求必须严格相邻,比如有3个Part,PartNumber可以需要是1,3,5。

示例

  • 请求示例

    PUT /object?partNumber=PartNumber&uploadId=UploadId HTTP/1.1
    Host: BucketName.bj.bcebos.com
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Authorization: AuthorizationString
    Content-length:2794
    Content-Type:text/plain
    
    [2794 bytes of object data]
    
  • 响应示例

    HTTP/1.1 200 OK
    x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    ETag: "b54357faf0632cce46e942fa68356b38"
    Content-Length: 197
    Connection: keep-alive
    Server: BceBos
    
    [197 bytes of object data]
    

UploadPartCopy接口

接口描述

在调用InitiateMultipartUpload获取UploadId后,我们需要用UploadPartCopy命令来复制Object拆分后的数据(Part)。为了标识各个Part在Object的相对位置,在UploadPartCopy需要指定一个partNumber参数,partNumber的取值范围是1-10000,即每次三步复制最多可以有10000个part,最少1个part。

说明:

  • 每次Copy Part最多可以复制5G byte的数据。
  • 三步复制得到的目的Object的Meta信息,不会从源Object复制而来,需要用户在CompleteMultipartUpload时重新上传,或者完成之后,通过CopyObject接口复制自身来更新Meta。
  • UploadPartCopy时,不同的part可能来自不同的Object,系统并不对此进行限制。
  • 目前支持跨区域文件复制,即复制文件所在的源Bucket和目标Bucket可以不在同一region(目前只支持从其它Region向本Region复制数据)。当进行跨区域文件复制时,复制产生的流量会收取跨区域流量费。跨区域收费标准参见产品定价
  • 三步复制不适用于Append Object,Append Object可以使用普通复制方法来完成备份和meta更新。

请求(Request)

  • 请求语法

    PUT /<BucketName>/<ObjectKey>?uploadId=UploadId&partNumber=PartNumber HTTP/1.1
    Host: bj.bcebos.com
    Date: <Date>
    Authorization: <Authorization_String>
    Content-Type: text/plain
    Content-Length: <Content_Length>
    x-bce-copy-source: /srcbucket/srcobject
    x-bce-copy-source-range: bytes=0-9
    
  • 请求头域

    header 是否必填 描述
    x-bce-copy-source 复制源文件,比如/mybucket/myobject
    x-bce-copy-source-range 复制源文件的字节范围,必须使用bytes=first-last的格式,比如bytes=0-9,代表复制前10个字节。如果不提供此header,则复制整个文件,除最后一个part外,其他part需要大于等于5MB,或者是1MB的整数倍,单个part不能超过5GB,但是整个Object的大小不能超过5TB。
    x-bce-copy-source-if-match 如果源文件的etag值与此header提供的相同,则复制,否则不复制
    x-bce-copy-source-if-none-match 如果源文件的etag值与此header提供的相同,则不复制,否则复制
    x-bce-copy-source-if-unmodifed-since 如果源文件在此header提供的时间后未曾修改,则复制,否则不复制
    x-bce-copy-source-if-modifed-since 如果源文件在此header提供的时间后曾修改过,则复制,否则不复制

    说明:

    各字段的格式与CopyObject接口对应字段相同。
    假设Object内容为"0123456789",长度为10。x-bce-copy-source-range举例如下:

    • range: 0-3,拷贝"0123";
    • range: 4-,从下标为4的开始拷贝到文件结束即拷贝"456789";
    • range: -4,拷贝末尾4个即"6789"。
  • 请求参数

    名称 类型 描述 是否必需
    partNumber Int 此part在目的Object中的序号。partNum取值范围 1-10000,一次MultiPart的PartNumber要求必须严格相邻,比如有3个Part,PartNumber可以分别是1,3,5。
    uploadId String InitiateMultipartUpload获取的UploadId

响应(Response)

  • 响应元素

  • 响应头域

    名称 描述
    ETag 复制目的Object的ETag
    lastModified 目的Object的修改时间

    注意事项

    1. UploadPartCopy会返回本次Part的ETag,在MultipartUpload的第三步中需要此ETag,也建议用户用ETag验证上传数据的正确性。
    2. 为了保持复制过程中的http连接,UploadPartCopy接口的http结果可能使用Transfer-Encoded: Chunked编码方式。
    3. UploadPartCopy过程中,如果发生服务器端错误,http status code可能返回2XX但是复制失败,复制结果请根据http body中的json判定。

示例

  • 请求示例

    PUT /bucket/object?uploadId=a44cc9bab11cbd156984767aad637851&partNumber=1 HTTP/1.1
    Host: bj.bcebos.com
    Date: <Date>
    Authorization: <Authorization_String>
    Content-Type: text/plain
    Content-Length: 0
    x-bce-copy-source: /srcbucket/srcobject
    x-bce-copy-source-range: bytes=0-9
    
  • 响应示例

    HTTP/1.1 200 OK
    Date: Thu, 12 May 2016 09:14:32 GMT
    Content-Type: application/json; charset=utf-8
    Connection: keep-alive
    Server: BceBos
    x-bce-debug-id: MTAuNjMuMTIzLjI3OlRodSwgMTIgTWF5IDIwMTYgMTc6MTQ6MzIgQ1NUOjg3MjkzODMwMA==
    x-bce-request-id: bb90cc9c-2b80-462c-87a4-095e610c9a2f
    Transfer-Encoding: chunked
        {"lastModified":"2016-05-12T09:14:32Z","eTag":"67b92a7c2a9b9c1809a6ae3295dcc127"}
    

CompleteMultipartUpload接口

接口描述

当请求者用UploadPart将所有的Part都上传完成后,需要用此CompleteMultipartUpload命令完成整个MultipartUpload操作。此命令需要请求提供有效的Part列表,包含part的PartNumber和eTag。BOS收到此命令后会检查数据,然后把所有的Part组合成一个Object。

请求(Request)

  • 请求语法

    POST /<ObjectKey>?uploadId=UploadId HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    Date: <Date>
    Authorization: <Authorization_String>
    Content-Length: <Content_Length>
    Content-Type: text/plain
    
  • 请求参数

    名称 类型 描述 是否必需
    partNumber Int 此part在目的Object中的序号。partNum取值范围 1-10000,一次MultiPart的PartNumber要求必须严格相邻,比如有3个Part,PartNumber可以分别是1,3,5。
    eTag String Object的HTTP协议实体标签
  • 请求头域

    名称 类型 描述 是否必需
    Content-Length Long Int 头域JSON数据的长度
    x-bce-meta-* String 用户自定义的meta

响应(Response)

  • 响应头域

    无特殊头域

  • 响应元素

    名称 类型 描述
    bucket String 此Object所属的Bucket
    completeMultipartUploadResult Container 保存Complete Multipart Upload的容器
    eTag String Object的HTTP协议实体标签
    key String Object名称
    location String 此Object的url

    注意事项

    1. UploadPart会返回本次Part的eTag,在MultipartUpload的第三步中需要此eTag,也建议用户用eTag验证上传数据的正确性。
    2. 返回的eTag值之前都会增加-,例如:"eTag":"-3858f62230ac3c915f300c664312c11f"

示例

  • 请求示例

    POST /object?uploadId=UploadId HTTP/1.1
    Host: BucketName.bj.bcebos.com
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Authorization: AuthorizationString
    Content-Length: 11434
    Content-Type: text/plain
    
    {
        "parts":[
            {
                "partNumber":1,
                "eTag":"a54357aff0632cce46d942af68356b38"
            },
            {
                "partNumber":2,
                "eTag":"0c78aef83f66abc1fa1e8477f296d394"
            },
            {
                "partNumber":3,
                "eTag":"acbd18db4cc2f85cedef654fccc4a4d8"
            }
        ]
    }
    
  • 响应示例

    HTTP/1.1 200 OK
    x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Connection: close
    Server: BceBos
    
    {
        "location":"http://bj.bcebos.com/BucketName/object",
        "bucket":"BucketName",
        "key":"object",
        "eTag":"3858f62230ac3c915f300c664312c11f"
    }
    

AbortMultipartUpload接口

接口描述

用户可以使用此接口来中断某个MultipartUpload请求,BOS收到此命令后,将会清除已上传的数据。

请求(Request)

  • 请求语法:

    DELETE /<ObjectKey>?uploadId=UploadId HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    Date: <Date>
    Authorization: <Authorization_String>
    Content-Length: <Content_Length>
    
  • 请求头域

    无特殊要求头域

  • 请求参数

    名称 类型 描述 是否必需
    uploadId String 此次MultipartUpload的ID

响应(Response)

  • 响应头域

    无特殊头域

  • 响应元素

    名称 类型 描述
    completeMultipartUploadResult Container 保存Complete Multipart Upload的容器

    注意事项

    中止一个Multipart Upload事件时,如果其所属的某些Part仍然在上传,那么这次中止操作将无法删除这些Part。所以如果存在并发访问的情况,为了彻底释放BOS上的空间,需要调用几次Abort Multipart Upload接口。

示例

  • 请求示例

    DELETE /object?uploadId=a44cc9bab11cbd156984767aad637851 HTTP/1.1
    Host: BucketName.bj.bcebos.com
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Authorization: AuthorizationString
    
  • 响应示例

    HTTP/1.1 204 No Content
    x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
    Date:  Wed, 06 Apr 2016 06:34:40 GMT
    Content-Length: 0
    Connection: keep-alive
    Server: BceBos
    

ListParts接口

接口描述

此命令用于列出用户指定UploadId所属的所有已经上传成功的Part,用户可以通过此命令查看当前的进度。

请求(Request)

  • 请求语法

    GET /<ObjectKey>?uploadId=a44cc9bab11cbd156984767aad637851&maxParts=2&partNumberMarker=1 HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    Date: <Date>
    Authorization: <Authorization_String>
    
  • 请求头域

    无特殊头域

  • 请求参数

    名称 类型 描述 是否必需
    maxParts Int BOS一次最多返回的part数目,默认1000,最大1000
    partNumberMarker Int 按照partNumber排序,本次请求的起始part从此partNumber的下一个开始返回
    uploadId String 此次MultipartUpload的ID

响应(Response)

  • 响应头域

    无特殊头域

  • 响应元素

    名称 类型 描述
    listPartsResult Container 返回的所有part的容器
    bucket String 所属Bucket名称
    key String Object名称
    uploadId String 请求指定的UploadId
    initiated String multipartUpload的创建时间
    owner Container 此object所属的用户信息
    +id String 用户ID
    +displayName String 用户名
    storageClass String Object的存储类型,低频存储返回STANDARD_IA,冷存储返回COLD,标准存储返回STANDARD
    partNumberMarker Int 请求指定的本次part Number
    nextPartNumberMarker Int 本次请求返回的最后一条记录的partNumber,可以作为下一次请求的PartNumberMarker
    maxParts Int 请求指定的本次最多返回的part数量
    isTruncated Bool 标明是否本次返回的List Part结果列表被截断。 true表示本次没有返回全部结果; false表示本次已经返回了全部结果
    part Container 一个part的容器
    +partNumber Int 该part的标识
    +lastModified DATE 该part的上传时间
    +ETag String 每个上传分块的ETag
    +size Int 该part大小

注意事项

  1. BOS按照PartNumber升序排序。
  2. 由于网络传输可能出错,所以不推荐用ListParts出来的结果生成最后CompleteMultipartUpload的Part列表。

示例

  • 请求示例

    GET /object?uploadId=a44cc9bab11cbd156984767aad637851&maxParts=2&partNumberMarker=1
    Host: BucketName.bj.bcebos.com
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Authorization: AuthorizationString
    
  • 响应示例

    HTTP/1.1 200 OK
    x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Content-Length: 985
    Connection: keep-alive
    Server: BceBos
    
    {
        "bucket":"BucketName",
        "key":"object",
        "uploadId":"a44cc9bab11cbd156984767aad637851",
        "initiated":"2010-11-10T20:48:33Z",
        "owner":{
            "id":"75aa570f8e7faeebf76c078efc7c6caea54ba06a",
            "displayName":"someName"
        },
        "storageClass":"STANDARD",
        "partNumberMarker":1,
        "nextPartNumberMarker":3,
        "maxParts":2,
        "isTruncated":true,
        "parts":[
            {
                "partNumber":2,
                "lastModified":"2010-11-10T20:48:34Z",
                "ETag":"7778aef83f66abc1fa1e8477f296d394",
                "size":10485760
            },
            {
                "partNumber":3,
                "lastModified":"2010-11-10T20:48:33Z",
                "ETag":"aaaa18db4cc2f85cedef654fccc4a4x8",
                "size":10485760
            }
        ]
    }
    

ListMultipartUploads接口

接口描述

此命令用于列出指定Bucket下面的所有未执行完成的Multipart Upload。“未执行完”是指完成了InitMultipartUpload,但是还没有调用CompleteMultipartUpload和AbortMultipartUpload的Multipart Upload。每次BOS最多返回1000个Multipart Upload,BOS支持prefix和delimiter过滤。

请求(Request)

  • 请求语法
    GET /?uploads HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    Date: <Date>
    Authorization: <Authorization_String>
    
  • 请求头域

    无特殊要求头域

  • 请求参数

    名称 类型 描述 是否必需
    delimiter String 分隔符; 主要应此项实现list文件夹的逻辑
    keyMarker String Object按照字典序排序后,本次从keyMarker的后面的一条开始返回
    maxUploads Int 本次请求返回Multipart Uploads的最大数目,默认1000,最大1000
    prefix String key前缀,限定返回的object key必须以此为前缀
    uploads String 标明请求是5.4.7 ListMultipartUploads

响应(Response)

  • 响应头域

    无特殊头域

  • 响应元素

    名称 类型 描述
    listMultipartUploadsResult Object 返回的所有MultipartUpload的容器
    bucket String 所属Bucket名称
    commonPrefixes - 如果在请求的时候指定了delimiter,将返回此项。BOS把匹配到的Object名称
    按照一定规则(从preifx到第一个delimiter)截取,截取的字符串去重作为CommonPrefixes的数据返回
    delimiter String 返回请求中的delimiter值
    prefix String 匹配到的数据
    initiated DATE 本次MultipartUpload开始时间
    storageClass String Object的存储类型,低频存储返回STANDARD_IA,冷存储返回COLD,标准存储返回STANDARD
    isTruncated Bool 标明是否本次是否没有返回所有的数据。
    true表示本次没有返回全部结果; false表示本次已经返回了全部结果
    keyMarker String 请求指定的本次返回的MultipartUpload的起始位置
    maxUploads Int 请求指定的本次返回的Multipart Uploads的最大数目
    nextKeyMarker String 本次返回的最后一条MultipartUpload,可以作为下一次请求的KeyMarker
    uploads Container 保存一个MultipartUpload的容器
    +key String Object名称
    +uploadId String MultipartUpload的ID
    +owner Container Object所属的用户信息
    ++displayName String 用户名
    ++id String 用户ID

    注意事项:此处的Delimiter跟ListObjects的类似,可以参考ListObjects的接口说明。

示例

  • 请求示例

    GET /?uploads HTTP/1.1
    Host: BucketName.bj.bcebos.com
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Authorization: AuthorizationString
    
  • 响应示例(JSON)

    HTTP/1.1 200 OK
    x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Content-Length: 1330
    Connection: keep-alive
    Server: BceBos
    
    {
      "bucket":"bucket",
      "keyMarker":"",
      "nextKeyMarker":"my-movie.m2ts",
      "maxUploads":3,
      "isTruncated":true,
      "uploads": [
          {
              "key":"my-divisor",
              "uploadId":"a44cc9bab11bdc157676984aad851637",
              "owner":{
                  "id":"75aa57f09aa0c8caeab4aeebf76c078efc7c6caea54ba06a",
                  "displayName":"OwnerDisplayName"
              },
              "initiated":"2010-11-10T20:48:33Z"
              "storageClass" : "STANDARD_IA",
          },
          {
              "key":"my-movie",
              "uploadId":"b44cc9bab11cbd156984767aad637851",
              "owner":{
                  "id":"b1d16700c70b0b05597d7acd6a3f92be",
                  "displayName":"OwnerDisplayName"
              },
              "initiated":"2010-11-10T20:48:33Z"
              "storageClass" : "STANDARD",
          },
          {
              "key":"my-movie.m2ts",
              "uploadId":"c41cc9aad11cbd637851767bab156984",
              "owner":{
                  "id":"b1d16700c70b0b05597d7acd6a3f92be",
                  "displayName":"OwnerDisplayName"
              },
              "initiated":"2010-11-10T20:49:33Z"
              "storageClass" : "STANDARD_IA",
          }
      ]
    }