所有文档

          对象存储 BOS

          AppendObject

          接口描述

          AppendObject以追加写的方式上传文件。通过AppendObject操作创建的Object类型为Appendable Object,可以对该Object追加数据;而通过PutObject上传的Object是Normal Object,不可进行数据追加写。

          说明:

          • Appendable Object大小限制为0~5G
          • AppendObject接口在进行追加写时要求对该Object有写权限
          • 归档类型对象暂时不支持AppendObject。
          • 软链接不是可追加类型,会返回HTTP 403,ObjectUnappendable错误。

          请求(Request)

          • 请求语法

            首次上传AppendObject 时,使用如下方法:

            POST /<ObjectName>?append HTTP/1.1
            Host: <BucketName>.bj.bcebos.com 
            Date: <GMT Date> 
            Authorization: <AuthorizationString>
            Content-Type: text/plain 
            Content-Length: <ContentLength>
            x-bce-storage-class: <StorageClass>

            说明:

            • 如该Object不存在,则创建一个Appendable的Object。
            • 如已存在同名的Object,则上传的数据会覆盖原有的Object,无论原有Object是否为Appendable,均创建新的Appendable Object。
            • 允许创建或者覆盖一个长度为0的Object。

            如已上传了部分AppendObject,需要进行断点续传时,使用如下方法:

            POST /<ObjectName>?append&offset=<OffsetSize> HTTP/1.1   
            Host: <BucketName>.bj.bcebos.com 
            Date: <GMT Date> 
            Authorization: <AuthorizationString>
            Content-Type: text/plain 
            Content-Length: <ContentLength>

            说明:

            • 如要续传的Object不存在时,会返回错误码404 NoSuchKey。
            • 如要续传的Object并不是Appendable的,则会返回403 ObjectUnappendable。
            • 值错误,则返回409 OffsetIncorrect。
            • 如果不指定offset会直接覆盖而不是默认追加在末尾
          • 请求头域

            名称 类型 描述 是否必须
            Cache-Control String 浏览器cache的一种机制设置
            Content-Disposition String 指示浏览器如何显示附加的文件
            Content-MD5 String RFC2616定义的HTTP请求内容的MD5摘要,可以通过携带该字段来验证保存在BOS侧的文件和用户预期的文件是否一致。
            Expires String GMT时间,缓存失效时间
            x-bce-meta-* String 用户自定义的meta
            x-bce-content-sha256 String 指本次所传数据的sha256值,必须与此匹配,否则AppendObject失败
            x-bce-content-crc32 String 本次上传object增量数据的CRC值(循环冗余校验码)。
            x-bce-storage-class String 指定Object的存储类型,STANDARD_IA代表低频存储,COLD代表冷存储,ARCHIVE代表归档存储,不指定时默认是标准存储类型;如果是多AZ类型bucket,MAZ_STANDARD_IA代表多AZ低频存储,不指定时默认是MAZ_STANDARD多AZ标准存储类型,不能是其它取值
            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。
          • 请求参数

            名称 类型 参数位置 描述 是否必须
            append - Query参数 代表对Appendable Object进行追加操作
            offset - Query参数 代表数据断点,即从该点后继续追加,取值为已实际上传的数据大小

          响应(Response)

          • 响应头域

            名称 类型 描述 是否必须
            Content-MD5 String 当前已成功上传的整个object的MD5值
            x-bce-next-append-offset Long Int 指明下次AppendObject请求时传入的的值。如果不使用续传方式,即请求起始行没有offset,则这个值是0
            x-bce-content-crc32 String 整个object数据的CRC值(循环冗余校验码)。
            ETag String Append后整个Object的ETag值
          • 响应参数

            使用细节说明

            对于Appendable的Object:

            • 支持AppendObject。
            • 支持RenameObject。
            • 对一个已存在的Appendable的Object执行PutObject,则Appendable的Object会被覆盖变成普通Object。
            • 对一个已存在的Appendable的Object,在<OffsetSize>值正确的情况下,追加一个长度为0的内容,不会改变Object的任何状态。
            • 不建议并发操作同一个Object,如一个线程执行AppendObject,另一线程执行PutObject/CopyObjcect/DeleteObject等操作,可能会导致操作结果错误或操作失败。
            • 如果对同一个Object做多线程或者多进程的并发追加,有可能因为并发过程的不确定性,返回409 OffsetIncorrect失败。

          对其他接口的影响

          对于GetObjectMeta接口,当一个Object是Appendable时,返回的结果中会多如下两个字段:

          名称 类型 描述 是否必须
          x-bce-next-append-offset String 当Object是由AppendObject接口创建的,会返回该字段,指明下次AppendObject时请求传入的的值。如果此时Object的大小是5G,offset依然返回5G
          x-bce-object-type String 当Object的类型值。当object是由AppendObject创建的,返回的值为Appendable,其他情况暂不返回

          关于用户自定义的x-bce-meta-*

          • 在首次创建AppendableObject(即Http请求起始行不带offset参数)时,携带的x-bce-meta-*Header会被存储,后续追加AppendObject(即Http请求起始行携带offset参数)时的x-bce-meta-*Header则默认被忽略。
          • 由于Appendable Object支持CopyObject,因此可以使用CopyObject自我拷贝以覆盖的形式来修改x-bce-meta-* Header的值。

          数据校验

          • 每次调用AppendObject的时候,如您上传MD5或者Sha256值,BOS会对该次调用上传的数据进行校验。
          • 每次数据追加结束,会返回已上传的整个Object的MD5值。

          示例

          • 标准存储的请求示例一

            POST /ObjectName?append  HTTP/1.1
            Host: BucketName.bj.bcebos.com
            Date: Wed, 06 Apr 2016 06:34:40 GMT
            Authorization: AuthorizationString
            Content-Type: text/plain
            Content-Length: 1134
            
            [1134 bytes of object data]  
          • 低频/冷存储的请求示例一

            POST /ObjectName?append  HTTP/1.1
            Host: BucketName.bj.bcebos.com
            Date: Wed, 06 Apr 2016 06:34:40 GMT
            Authorization: AuthorizationString
            Content-Type: text/plain
            Content-Length: 1134
            x-bce-storage-class: STANDARD_IA 
            
            [1134 bytes of object data]  
          • 响应示例一

            HTTP/1.1 200 OK
            x-bce-request-id: c31b374e-048a-41f0-9a9a-31bc4bc57509
            Date: Wed, 06 Apr 2016 06:34:40 GMT
            ETag: "7c935a3947e3a684333480bd6b58b7c2"
            Content-Length: 0
            Content-MD5: RJBidEhsrgCKeDjvQjrF8A==
            x-bce-next-append-offset: 1134
            Connection: close
            Server: BceBos
          • 标准存储的请求示例二

            POST /ObjectName?append&offset=1134 HTTP/1.1
            Host: BucketName.bj.bcebos.com
            Date: Wed, 06 Apr 2016 06:34:40 GMT
            Authorization: AuthorizationString
            Content-Type: text/plain
            Content-Length: 1900
            
            [1900 bytes of object data]
          • 低频/冷存储的请求示例二

            POST /my-object?append&offset=1134 HTTP/1.1
            Host: BucketName.bj.bcebos.com
            Date: Wed, 06 Apr 2016 06:34:40 GMT
            Authorization: AuthorizationString
            Content-Type: text/plain
            Content-Length: 1900
            x-bce-storage-class: STANDARD_IA 
            
            [1900 bytes of object data]
          • 响应示例二

            HTTP/1.1 200 OK
            x-bce-request-id: 28a99102-d0a5-4252-a4ed-fa6dc801806b
            Date: Wed, 06 Apr 2016 06:34:40 GMT
            ETag: "11257f81dce31a95f67f6e75018b77e3"
            Content-Length: 0
            Content-MD5: fJNaOUfjpoQzNIC9a1i3wg==
            x-bce-next-append-offset: 3034
            Connection: close
            Server: BceBos  
          上一篇
          DeleteMultipleObjects
          下一篇
          权限控制