对象存储BOS

    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 /<ObjectName>?uploads HTTP/1.1
      Host: <BucketName>.bj.bcebos.com
      Date: <Date>
      Authorization: <AuthorizationString>
      Content-Type: text/plain
      Content-Length: <ContentLength>
      x-bce-storage-class: <StorageClass>
    • 请求头域

      名称 类型 描述 是否必需
      x-bce-storage-class String 指定BOS的对象的存储类型,目前支持STANDARDSTANDARD_IACOLDARCHIVE 否,默认为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"
      Expires String 设置下载Object时的缓存失效时间
    • 请求参数

      名称 类型 参数位置 描述 是否必需
      uploads String Query参数 分块上传的请求

    响应(Response)

    • 响应头域

    • 响应元素

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

      注意事项

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

    示例

    • 标准存储的请求示例

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

      POST /ObjectName?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":"ObjectName",
          "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 /<ObjectName>?partNumber=PartNumber&uploadId=UploadId HTTP/1.1
      Host: <BucketName>.bj.bcebos.com
      Date: <Date>
      Authorization: <AuthorizationString>
      Content-Length: <ContentLength>
    • 请求头域

      名字 类型 描述
      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 Query参数 本次上传的part在object的相对位置
      uploadId String Query参数 InitiateMultipartUpload获取的UploadId

    响应(Response)

    • 响应元素

    • 响应头域

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

      注意事项

      UploadPart会返回本次Part的eTag,在MultipartUpload的第三步中需要此eTag,也建议用户用eTag验证上传数据的正确性。

    示例

    • 请求示例

      PUT /ObjectName?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: 0
      Connection: keep-alive
      Server: BceBos

    UploadPartCopy接口

    接口描述

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

    说明:

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

    请求(Request)

    • 请求语法

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

      header 是否必填 描述
      x-bce-copy-source 复制源文件,比如/SrcBucket/SrcObject
      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 Query参数 此part在目的Object中的序号。partNum取值范围 1-10000,一次MultiPart的PartNumber要求必须严格有序,比如有3个Part,PartNumber可以是1,3,5。
      uploadId String Query参数 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 /ObjectName?uploadId=a44cc9bab11cbd156984767aad637851&partNumber=1 HTTP/1.1
      Host: BucketName.bj.bcebos.com
      Date: <Date>
      Authorization: <AuthorizationString>
      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"
      }

      拷贝失败, 需要根据返回的json判断

      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
      {
          "code":"InternalError",
          "message":"We encountered an internal error. Please try again.",
          "requestId":"52454655-5345-4420-4259-204e47494e58"
      }

    CompleteMultipartUpload接口

    接口描述

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

    请求(Request)

    • 请求语法

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

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

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

    响应(Response)

    • 响应头域

      无特殊头域

    • 响应元素

      名称 类型 描述
      bucket String 此Object所属的Bucket
      eTag String Object的HTTP协议实体标签
      key String Object名称
      location String 此Object的url

      注意事项

      1. CompleteMultipartUpload的请求Body最大为1MB。
      2. 一次MultiPart的PartNumber可以是不连续的,比如1, 3, 5。

    示例

    • 请求示例

      POST /ObjectName?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/ObjectName",
      	"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: <AuthorizationString>
      Content-Length: <ContentLength>
    • 请求头域

      无特殊要求头域

    • 请求参数

      名称 类型 参数位置 描述 是否必需
      uploadId String Query参数 此次MultipartUpload的ID

    响应(Response)

    • 响应头域

      无特殊头域

    • 响应元素

      注意事项

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

    示例

    • 请求示例

      DELETE /ObjectName?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 /<ObjectName>?uploadId=UploadId&maxParts=MaxParts&partNumberMarker=PartNumberMarker HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    Date: <Date>
    Authorization: <AuthorizationString>
    • 请求头域

      无特殊头域

    • 请求参数

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

    响应(Response)

    • 响应头域

      无特殊头域

    • 响应元素

      名称 类型 描述
      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,归档存储返回ARCHIVE
      partNumberMarker Int 请求指定的本次part Number起始位置
      nextPartNumberMarker Int 本次请求返回的最后一条记录的partNumber,可以作为下一次请求的PartNumberMarker
      maxParts Int 请求指定的本次最多返回的part数量
      isTruncated Bool 标明是否本次返回的List Part结果列表被截断。 true表示本次没有返回全部结果; false表示本次已经返回了全部结果
      parts Container 一个part的容器
      +partNumber Int 该part的标识
      +lastModified DATE 该part的上传时间
      +ETag String 每个上传分块的ETag
      +size Int 该part大小

    注意事项

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

    示例

    • 请求示例

      GET /ObjectName?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 Query参数 分隔符; 主要应此项实现list文件夹的逻辑
      keyMarker String Query参数 Object按照字典序排序后,本次从keyMarker的后面的一条开始返回
      maxUploads Int Query参数 本次请求返回Multipart Uploads的最大数目,默认1000,最大1000
      prefix String Query参数 key前缀,限定返回的object key必须以此为前缀
      uploads String Query参数 标明请求是 ListMultipartUploads

    响应(Response)

    • 响应头域

      无特殊头域

    • 响应元素

      名称 类型 描述
      bucket String 所属Bucket名称
      commonPrefixes - 如果在请求的时候指定了delimiter,将返回此项。BOS把匹配到的Object名称
      按照一定规则(从preifx到第一个delimiter)截取,截取的字符串去重作为CommonPrefixes的数据返回
      delimiter String 返回请求中的delimiter值
      prefix String object前缀
      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
      +initiated Date 本次MultipartUpload开始时间
      +storageClass String Object的存储类型,低频存储返回STANDARD_IA,冷存储返回COLD,标准存储返回STANDARD,归档类型返回ARCHIVE

      注意事项:此处的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",
            }
        ]
      }
    上一篇
    Object相关接口
    下一篇
    图像审核服务接口