AppendObject - Object Storage Service - Alibaba Cloud Documentation Center

You can call the AppendObject operation to upload an object by appending data. An object created using the AppendObject operation is an Appendable object, whereas an object uploaded using the PutObject operation is a Normal object.

Versioning

If versioning is enabled for or suspended on the destination bucket, the following rules apply when you perform operations on an Appendable object:

You can append data only to the current version of an Appendable object. OSS does not create previous versions for the Appendable object.
If you call the PutObject or DeleteObject operation on the current version of an Appendable object, OSS converts the Appendable object into a previous version. You can no longer append data to this object.
The AppendObject operation is not supported for non-Appendable objects, such as Normal objects and delete markers.

Limits

The final size of an object that is created using AppendObject cannot exceed 5 GB.
The AppendObject operation is not supported for objects that are protected by a data retention policy (WORM).
Appendable objects do not support server-side encryption that uses a Key Management Service (KMS)-managed key with a specified CMK ID.
The download performance of Appendable objects is significantly lower than that of Normal objects or objects that are uploaded in parts. Consider this performance difference for your specific scenario.

Permissions

By default, an Alibaba Cloud account has full permissions. RAM users or RAM roles under an Alibaba Cloud account do not have any permissions by default. The Alibaba Cloud account or account administrator must grant operation permissions through RAM Policy or Bucket Policy.

API

Action

Definition

AppendObject

oss:PutObject

You can call this operation to upload an object by appending the object to an existing object.

oss:PutObjectTagging

When uploading an object by appending the object to an existing object, if you specify object tags through x-oss-tagging, this permission is required.

Request syntax

POST /ObjectName?append&position=Position HTTP/1.1
Content-Length: ContentLength
Content-Type: ContentType
Host: BucketName.oss.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

Request headers

Name	Type	Required	Example	Description
Cache-control	string	No	no-cache	Specifies the web page caching behavior of the object. For more information, see RFC2616. Default value: none
Content-Disposition	string	No	attachment;filename=oss_download.jpg	Specifies the name of the object when it is downloaded. For more information, see RFC2616. Default value: none
Content-MD5	string	No	ohhnqLBJFiKkPSBO1eNaUA==	The Content-MD5 header is a value generated by the MD5 algorithm. This header is used to check whether the message content is the same as the content that was sent. To get the Content-MD5 value, run the MD5 algorithm on the message body (excluding headers) to get a 128-bit number, and then apply Base64 encoding to the number. Default value: none Constraints: none
Expires	string	No	Wed, 08 Jul 2015 16:57:01 GMT	The expiration time. For more information, see RFC2616. Default value: none
x-oss-server-side-encryption	string	No	AES256	Specifies the server-side encryption method. Valid values: AES256: Use keys that are fully managed by OSS for encryption and decryption (SSE-OSS). KMS: Use keys that are managed by KMS for encryption and decryption.
x-oss-object-acl	string	No	private	Specifies the access control list (ACL) of the object. Valid values: default (default): The object inherits the ACL of the bucket. private: The object is a private resource. Only the object owner and authorized users have read and write permissions on the object. Other users do not have permissions to access the object. public-read: The object is a public-read resource. Only the object owner and authorized users have read and write permissions on the object. Other users have only read permissions on the object. Use this permission with caution. public-read-write: The object is a public-read-write resource. All users have read and write permissions on the object. Use this permission with caution. For more information about access permissions, see Object ACL.
x-oss-storage-class	string	No	Standard	Specifies the storage class of the object. For a bucket of any storage class, if you specify this parameter when you upload an object, the uploaded object is stored in the specified storage class. For example, if you set x-oss-storage-class to Standard when you upload an object to an Infrequent Access (IA) bucket, the object is stored as a Standard object. Valid values: Standard: Standard IA: Infrequent Access Archive: Archive Storage For more information about storage classes, see Storage classes. Important This request header takes effect only for the first append operation. It does not take effect for subsequent append operations. Objects created as Appendable objects cannot be converted to the Cold Archive or Deep Cold Archive storage class in any way.
x-oss-meta-*	string	No	x-oss-meta-location	You can add the x-oss-meta-* header when you create an Appendable object. You cannot include this parameter in subsequent append operations. A parameter prefixed with x-oss-meta-* is considered metadata. Metadata size limit: An object can have multiple metadata entries, but the total size of all metadata cannot exceed 8 KB. Metadata naming convention: Dashes (-), digits, and lowercase letters (a-z) are supported. Uppercase letters are converted to lowercase letters. Other characters, including underscores (_), are not supported.
x-oss-tagging	string	No	TagA=A	Specifies the tags of the object in a key-value format. You can specify multiple tags at the same time, such as `TagA=A&TagB=B`. Important This request header takes effect only for the first append operation. It does not take effect for subsequent append operations. The key and value must be URL-encoded. The key is required, but the value is optional. For example, you can set the object tags to `TagA&TagB=B`.

For more information about other common request headers for this operation, see Common request headers.

Request parameters

Important

The append and position parameters are part of the CanonicalizedResource and must be included in the signature.

Name

Type

Required

Example

Description

append

string

Yes

Not applicable

Specifies the AppendObject operation. Each AppendObject operation updates the last modified time of the object.

position

string

Yes

Specifies the position from which to start appending data. After each successful operation, the x-oss-next-append-position response header indicates the position for the next append.

The position for the first append operation must be 0. The position for a subsequent append operation is the current size of the object. For example, if the position for the first AppendObject request is 0 and the content-length is 65536, the position for the second AppendObject request must be 65536.

If the position is 0 and no object with the same name exists, the AppendObject request is similar to a PutObject request. This means you can set request headers such as x-oss-server-side-encryption. If you add a valid x-oss-server-side-encryption header, subsequent AppendObject responses also include the x-oss-server-side-encryption header. To change the metadata later, use the CopyObject operation.
If the position value is correct, appending content of size 0 to an existing Appendable object does not change the state of the object.

Response headers

Response header

Type

Example

Description

x-oss-next-append-position

64-bit integer

1717

The position to provide for the next request, which is the current size of the object.

This header is returned when the AppendObject operation is successful or when a 409 error occurs because the position does not match the object size.

x-oss-hash-crc64ecma

64-bit integer

3231342946509354535

Indicates the 64-bit CRC-64 value of the object. The 64-bit CRC-64 is calculated based on the CRC-64/XZ standard.

For more information about other common response headers for this operation, see Common response headers.

CRC-64 calculation method

You can use the following calculation methods:

Calculate using the Boost CRC module

typedef boost::crc_optimal<64, 0x42F0E1EBA9EA3693ULL, 0xffffffffffffffffULL, 0xffffffffffffffffULL, true, true> boost_ecma;
uint64_t do_boost_crc(const char* buffer, int length)
{
    boost_ecma crc;
    crc.process_bytes(buffer, length);
    return crc.checksum();
}

Calculate using Python crcmod

import crcmod
do_crc64 = crcmod.mkCrcFun(0x142F0E1EBA9EA3693, initCrc=0, xorOut=0xffffffffffffffff, rev=True)
print(do_crc64(b"123456789"))

Relationship with other operations

Other operation	Relationship description
PutObject	If you call the PutObject operation on an existing Appendable object, the Appendable object is overwritten by the new object, and its type is changed to Normal.
HeadObject	Calling the HeadObject operation on an Appendable object returns x-oss-next-append-position, x-oss-hash-crc64ecma, and x-oss-object-type. The x-oss-object-type of an Appendable object is Appendable.
GetBucket (ListObjects)	In the response to a GetBucket request, the Type of an Appendable object is set to Appendable.

Examples

Request example

POST /oss.jpg?append&position=0 HTTP/1.1 
Host: oss-example.oss.aliyuncs.com 
Cache-control: no-cache 
Expires: Wed, 08 Jul 2015 16:57:01 GMT 
x-oss-storage-class: Archive
Content-Disposition: attachment;filename=oss_download.jpg 
Date: Wed, 08 Jul 2015 06:57:01 GMT 
Content-Type: image/jpg 
Content-Length: 1717 
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-disposition;content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e  
[1717 bytes of object data]

Response example

HTTP/1.1 200 OK
Date: Wed, 08 Jul 2015 06:57:01 GMT
ETag: "0F7230CAA4BE94CCBDC99C550000****"
Connection: keep-alive
Content-Length: 0  
Server: AliyunOSS
x-oss-hash-crc64ecma: 14741617095266562575
x-oss-next-append-position: 1717
x-oss-request-id: 559CC9BDC755F95A6448****

Versioning request example

If versioning is enabled for a bucket, the response to an AppendObject request includes the x-oss-version-id header. The value of this header is the version ID of the current version of the object.

POST /example?append&position=0 HTTP/1.1 
Host: versioning-append.oss.aliyuncs.com 
Date: Tue, 09 Apr 2019 03:59:33 GMT
Content-Length: 3
Content-Type: application/octet-stream
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Response example

HTTP/1.1 200 OK
Date: Tue, 09 Apr 2019 03:59:33 GMT
ETag: "2776271A4A09D82CA518AC5C0000****"
Connection: keep-alive
Content-Length: 0  
Server: AliyunOSS
x-oss-version-id: CAEQGhiBgIC_k6aV5RgiIGI3YTY2ZmMzYWJlMzQ3YjM4YTljOTk5YjUyZGF****
x-oss-hash-crc64ecma: 3231342946509354535
x-oss-next-append-position: 47
x-oss-request-id: 5CAC18A5B7AEADE01700****

SDK

The SDKs for this operation are provided for the following languages:

ossutil command line interface

For information about the ossutil command for the AppendObject operation, see append-object.

Error codes

Error code	HTTP status code	Description
ObjectNotAppendable	409	An AppendObject operation was performed on a non-Appendable object.
PositionNotEqualToLength	409	The value of position does not match the current length of the object. You can get the position for the next request from the x-oss-next-append-position response header and try the request again. Due to concurrency, the request may still fail with the PositionNotEqualToLength error even if you set the position value to x-oss-next-append-position. If the position is 0, the request is successful if no Appendable object with the same name exists, or if the Appendable object with the same name has a length of 0. In other cases, the position is considered not to match the object length, and this error code is returned.
InvalidArgument	400	The values of headers such as x-oss-storage-class and x-oss-object-acl are invalid.
FileImmutable	409	If you try to delete or modify data in a bucket that is in a protected state, this error code is returned.
KmsServiceNotEnabled	403	Key Management Service (KMS) is not enabled in the console when you use the KMS encryption algorithm.