Interface Description

AppendObject uploads files by appending data. The object created through AppendObject is Appendable Object. The data can be appended to this object. The object uploaded through PutObject is Normal Object, and the data cannot be appended.

Descriptions:

• The size of Appendable Object is limited to 0-5 GB.
• The AppendObject API must have the write permission of this object when it appends the data.
• AppendObject is temporarily not supported for archive objects.
• The soft link is not appendable. It returns “HTTP 403: ObjectUnappendable”.

Request

• Request Syntax

  The following method is used to upload AppendObject for the first time:

  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>

  Descriptions:

  • If this object does not exist, an appendable object is created.
  • If an object with the same name already exists, the uploaded data overwrites the original object, and an appendable object is created regardless of whether the original object is appendable.
  • Creating or overwriting an object with a length of 0 is allowed.

  If a part of AppendObjects have been uploaded and it is necessary to perform the resumeable upload, the following method is used:

  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>

  Descriptions:

  • If the object whose upload needs to resume does not exist, it returns “Error 404: NoSuchKey”.
  • If the object to resume is not appendable, it returns “Error 403: ObjectUnappendable”.
  • If the value is incorrect, it returns “Error 409: OffsetIncorrect”.
  • If the offset is not specified, it is directly overwritten instead of being appended at the end by default.

• Request Header Field

  Name	Type	Description	Required?
  Cache-Control	String	A mechanism setup for the browser cache	No
  Content-Disposition	String	It indicates how the browser displays attached files.	No
  Content-MD5	String	The MD5 digest of the HTTP request content defined in RFC2616 can be contained to verify whether the file saved in BOS is consistent with the user expected file.	No
  Expires	String	GMT time, cache expiration date	No
  x-bce-meta-*	String	User-defined meta	No
  x-bce-content-sha256	String	It means that the Sha256 value of the data transferred this time must match this value. Otherwise, AppendObject fails.	No
  x-bce-content-crc32	String	CRC (cyclic redundancy check) value of the object incremental data uploaded this time.	No
  x-bce-storage-class	String	It specifies the storage type of the object. STANDARD_IA represents the infrequent access, COLD represents the cold storage, and ARCHIVE represents the archive storage. If it is not specified, it is the standard storage type by default. If it is a Multi-AZ bucket, MAZ_STANDARD_IArepresents the Multi-AZ infrequent access. If it is not specified, it is a MAZ_STANDARDstorage by default and cannot be other values.	No
  x-bce-acl	String	Header supported by CannedACL, in which the user sets the permission of the object, whose value is private or public-read.	No
  x-bce-grant-read	String	Header supported by CannedACL, in which the user sets the read permission of the object. It supports multiple IDs, separated by commas	No
  x-bce-grant-full-control	String	Header supported by CannedACL, in which the user sets the FULL_CONTROL permission of the object. It supports multiple IDs, separated by commas	No
  x-bce-server-side-encryption	String	Server encryption algorithm, only AES256 is supported currently.	No

• Request parameters

  Name	Type	Parameter position	Description	Required?
  append	-	Query parameter	It represents the Append operation of the appendable object.	Yes
  offset	-	Query parameter	It represents the data breakpoint, that is, continue to append from this point. The value is the size of the actual uploaded data.	No

Response

• Response Header Field

  Name	Type	Description	Required?
  Content-MD5	String	MD5 value of the entire object uploaded successfully	Yes
  x-bce-next-append-offset	Long Int	It indicates the value passed when it is requested by AppendObject next time. If the resumeable mode is not used, that is, there is no offset in the request start line, this value is 0.	Yes
  x-bce-content-crc32	String	CRC (cyclic redundancy check) value of the entire object data.	No
  ETag	String	ETag value of the entire object after appending	Yes

• Response Parameter

  No

  Detailed instructions for use

  For appendable objects:

  • Support AppendObject.
  • Support RenameObject.
  • If you execute PutObject for an existing appendable object, the appendable object is overwritten and become a normal object.
  • If you append the content with a length of 0 for an existing appendable object when the <OffsetSize> value is correct, it does not change any state of object.
  • It is not recommended to operate the same object concurrently. For example, if one thread executes AppendObject and another thread executes PutObject/CopyObjcect/DeleteObject, it may cause the incorrect operation results or operation failure.
  • If you concurrently append multiple threads or processes for the same object, it may return “Error 409: OffsetIncorrect” due to the uncertainty of concurrent process.

Impact on Other Interfaces

When an object is appendable for the GetObjectMeta API, there are two additional fields in the return results as follows:

For the user-defined x-bce-meta-*

• When an AppendableObject is created for the first time (i.e., HTTP request start line without offset parameter) the header carriedx-bce-meta-* is stored. When an AppendObject is appended subsequently (i.e., HTTP request start line with offset parameter), the header is ignored by x-bce-meta-*default.
• For the appendable object supports CopyObject, you can use CopyObject to modify the x-bce-meta-* header value in the overwritten form.

Data Check

• When you call AppendObject every time, BOS checks the data uploaded by this call if you upload MD5 or Sha256 value.
• After the data is appended every time, it returns the MD5 value of entire object uploaded.

Example

• Request example of standard storage 一

  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]  

• Request Example 1 of Infrequent Access/Cold Storage

  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]  

• Response Example 1

  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

• Request example of standard storage II

  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]

• Request Example 2 of Infrequent Access/Cold Storage

  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]

• Response example II

  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