AppendObject
Updated at：2025-11-03
API description
The AppendObject method uploads files in append mode. Objects created through AppendObject are classified as Appendable Objects, allowing additional data to be appended. In contrast, objects uploaded using PutObject are Normal Objects that do not support data append.
Description:
- The size limit for Appendable Objects is 0 - 48.8T.
- The AppendObject API requires the write permission for the object when the append operation is performed.
- Archive objects temporarily do not support the AppendObject method.
- Symlinks are not appendable. Attempting to append will result in an HTTP 403 error with the error code ObjectUnappendable.
- In the current version, multi-version buckets do not support the AppendObject write operation; however, previously written AppendObjects can still be read.
Request
-
Request syntax
Use the following method during the upload of AppendObject for the first time:
Plain Text1POST /<ObjectName>?append HTTP/1.1 2Host: <BucketName>.bj.bcebos.com 3Date: <GMT Date> 4Authorization: <AuthorizationString> 5Content-Type: text/plain 6Content-Length: <ContentLength> 7x-bce-storage-class: <StorageClass>Plain Text1 > **Description:** 2 > 3 > - If the Object does not exist, an Appendable Object will be created. 4 > - If an Object with the same name already exists, the new data will overwrite the old Object. Regardless of whether the original Object was Appendable or not, a new Appendable Object will be created. 5 > - This method allows you to create or overwrite a 0-byte object.If partial AppendObjects have been uploaded and resumable upload is required, the following methods shall be used:
Plain Text1POST /<ObjectName>?append&offset=<OffsetSize> HTTP/1.1 2Host: <BucketName>.bj.bcebos.com 3Date: <GMT Date> 4Authorization: <AuthorizationString> 5Content-Type: text/plain 6Content-Length: <ContentLength>Plain Text1 > **Description:** 2 > 3 > - If the Object to be resumed does not exist, a 404 NoSuchKey error code will be returned. 4 > - If the Object to be resumed is not Appendable, a 403 ObjectUnappendable error code will be returned. 5 > - <OffsetSize>In cases of incorrect values, a 409 OffsetIncorrect error code will be returned. 6 > - If the offset is not specified, it will directly overwrite rather than append at the end by default -
Request headers
| Name | Types | Description | Required or not |
|---|---|---|---|
| Cache-Control | String | A mechanism setting for browser cache | No |
| Content-Disposition | String | Indicate how the browser displays attached files | No |
| Content-MD5 | String | The MD5 digest of the HTTP request content, as defined in RFC 2616, verifies data consistency between the file stored in BOS and the one expected by the user. | No |
| Expires | String | GMT time, cache expiration time | No |
| x-bce-meta-* | String | User-defined meta | No |
| x-bce-content-sha256 | String | This header means that SHA256 value of the transmitted data must match it; otherwise, AppendObject fails. | No |
| x-bce-content-crc32 | String | The CRC value (cyclic redundancy check) of the incremental data uploaded for the object. | No |
| x-bce-storage-class | String | It specifies the storage class of the object: STANDARD_IA indicates infrequent access storage, COLD indicates cold storage, ARCHIVE indicates archive storage. If the storage class is not specified, the default class is standard storage. For multi-AZ buckets, MAZ_STANDARD_IA indicates multi-AZ infrequent access storage. If the storage class is not specified, the default class is MAZ_STANDARD multi-AZ standard storage, rather than other options. |
No |
| x-bce-acl | String | Headers supported by CannedACL enable users to set object permissions, allowing either private or public-read access. | No |
| x-bce-grant-read | String | Headers supported by CannedACL allow users to set read permissions for an object. Multiple IDs can be set and should be separated by commas. | No |
| x-bce-grant-full-control | String | Headers supported by CannedACL allow users to set FULL_CONTROL permissions for an object. Multiple IDs can be set and should be separated by commas. | No |
| x-bce-server-side-encryption | String | Server-Side Encryption (SSE) supports AES256 and SM4 encryption algorithms. | No |
| Name | Types | Parameter location | Description | Required or not |
|---|---|---|---|---|
| append | - | Query | It indicates the append operation on an Appendable Object. | Yes |
| offset | - | Query | It indicates a data breakpoint. In other words, appending is resumed after this point, and the value is the actual uploaded data size. | No |
Response
| Name | Types | Description | Required or not |
|---|---|---|---|
| Content-MD5 | String | MD5 value of the entire object uploaded successfully currently. | Yes |
| x-bce-next-append-offset | Long Int | This specifies the OffsetSize value for the next AppendObject request. If a resumable upload is not initiated (i.e., no offset is provided in the request's starting line), the value will be 0. | Yes |
| x-bce-content-crc32 | String | The CRC (cyclic redundancy check) value of the complete object data. | No |
| ETag | String | The ETag value of the entire object after Append | Yes |
-
Response parameters
None
Usage Details
For Appendable objects:
- Supports AppendObject.
- Supports RenameObject.
- Executing PutObject on an existing appendable object will overwrite it and convert it into a standard object.
- For an existing Appendable Object, appending zero-length content with correct
<OffsetSize>} values will not change the object status. - Concurrent operations on the same object are not recommended, such as one thread executing AppendObject while another executes PutObject, CopyObject, or DeleteObject. This may result in incorrect requests or operation failures.
- When multiple threads or processes concurrently append to the same object, a 409 OffsetIncorrect error may occur due to concurrency conflicts.
Impact on other APIs
For the GetObjectMeta API, when an Object is Appendable, the response result will include the following two additional fields:
| Name | Types | Description | Required or not |
|---|---|---|---|
| x-bce-next-append-offset | String | When the object is created via the AppendObject API, this field is returned, indicating the OffsetSize value to be loaded in the next AppendObject request. If the object size is 5G at this time, the 5G will still be returned for the offset. | Yes |
| x-bce-object-type | String | The object's class value will be "Appendable" if created via AppendObject; otherwise, no value will be temporarily returned. | Yes |
User-defined x-bce-meta-*
- When an AppendableObject (i.e., HTTP request start line without offset parameter) is created for the first time, the
x-bce-meta-*Header will be stored. Thex-bce-meta-*Header will be ignored by default during the subsequent appending of AppendObject (i.e., HTTP request start line with offset parameter). - Since Appendable Object supports CopyObject, you can use CopyObject to self-copy and overwrite to modify the value of the
x-bce-meta-*Header.
Data verification
- Each time AppendObject is called, if you include MD5 or SHA256 values, BOS will verify the uploaded data during the call.
- Upon completing each data append, the MD5 value of the entire uploaded object will be returned.
Example
-
Example I of standard storage request
Plain Text1POST /ObjectName?append HTTP/1.1 2Host: BucketName.bj.bcebos.com 3Date: Wed, 06 Apr 2016 06:34:40 GMT 4Authorization: AuthorizationString 5Content-Type: text/plain 6Content-Length: 1134 7[1134 bytes of object data] -
Example I of infrequent access/cold storage request
Plain Text1POST /ObjectName?append HTTP/1.1 2Host: BucketName.bj.bcebos.com 3Date: Wed, 06 Apr 2016 06:34:40 GMT 4Authorization: AuthorizationString 5Content-Type: text/plain 6Content-Length: 1134 7x-bce-storage-class: STANDARD_IA 8[1134 bytes of object data] -
Response example I
Plain Text1HTTP/1.1 200 OK 2x-bce-request-id: c31b374e-048a-41f0-9a9a-31bc4bc57509 3Date: Wed, 06 Apr 2016 06:34:40 GMT 4ETag: "7c935a3947e3a684333480bd6b58b7c2" 5Content-Length: 0 6Content-MD5: RJBidEhsrgCKeDjvQjrF8A== 7x-bce-next-append-offset: 1134 8Connection: close 9Server: BceBos -
Example II of standard storage request
Plain Text1POST /ObjectName?append&offset=1134 HTTP/1.1 2Host: BucketName.bj.bcebos.com 3Date: Wed, 06 Apr 2016 06:34:40 GMT 4Authorization: AuthorizationString 5Content-Type: text/plain 6Content-Length: 1900 7[1900 bytes of object data] -
Example II of infrequent access/cold storage request
Plain Text1POST /my-object?append&offset=1134 HTTP/1.1 2Host: BucketName.bj.bcebos.com 3Date: Wed, 06 Apr 2016 06:34:40 GMT 4Authorization: AuthorizationString 5Content-Type: text/plain 6Content-Length: 1900 7x-bce-storage-class: STANDARD_IA 8[1900 bytes of object data] -
Response example II
Plain Text1HTTP/1.1 200 OK 2x-bce-request-id: 28a99102-d0a5-4252-a4ed-fa6dc801806b 3Date: Wed, 06 Apr 2016 06:34:40 GMT 4ETag: "11257f81dce31a95f67f6e75018b77e3" 5Content-Length: 0 6Content-MD5: fJNaOUfjpoQzNIC9a1i3wg== 7x-bce-next-append-offset: 3034 8Connection: close 9Server: BceBos