接口描述

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

说明：

• Appendable Object大小限制为0~48.8T
• 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和SM4加密。	否

• 请求参数

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

响应（Response）

• 响应头域

  名称	类型	描述	是否必须
  Content-MD5	String	当前已成功上传的整个object的MD5值	是
  x-bce-next-append-offset	Long Int	指明下次AppendObject请求时传入的OffsetSize的值。如果不使用续传方式，即请求起始行没有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时请求传入的OffsetSize的值。如果此时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