AppendObject-Object Storage Service(OSS)-阿里云帮助中心

Versioning

When versioning is enabled or suspended for a bucket, note the following behavior for Appendable objects:

You can append data only to the current version of an Appendable object. OSS does not create previous versions for this object.

A PutObject or DeleteObject operation on the current version saves the Appendable object as a previous version. The object can no longer be appended to.
AppendObject cannot be performed on non-Appendable objects, such as Normal objects or delete markers.
A new Appendable version can be created only when the object does not exist or the latest version is a delete marker. Set position to 0.

Limits

The maximum size of an Appendable object is 5 GB.
You cannot use the AppendObject operation on objects that are protected by a retention policy.
Appendable objects do not support server-side encryption with a CMK ID through KMS.
Download performance of Appendable objects is significantly lower than Normal or Multipart objects. Evaluate whether this meets your requirements.

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 policies or Bucket Policy.

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

当您在OSS ON云盒中调用该接口时，您需要将Host替换为云盒Endpoint。更多信息，请参见云盒Endpoint。

Request headers

Name	Type	Required	Example	Description
Cache-control	string	No	no-cache	The web page caching behavior for the object. Defined in RFC2616. Default: none
Content-Disposition	string	No	attachment;filename=oss_download.jpg	The name of the object when downloaded. Defined in RFC2616. Default: none
Content-MD5	string	No	ohhnqLBJFiKkPSBO1eNaUA==	A Base64-encoded MD5 hash used to verify message body integrity. Compute the MD5 hash of the message body (excluding headers) to produce a 128-bit value, then Base64-encode it. Default: none Constraints: none
Expires	string	No	Wed, 08 Jul 2015 16:57:01 GMT	The expiration time. Defined in RFC2616. Default: none
x-oss-server-side-encryption	string	No	AES256	The server-side encryption method. Valid values: AES256: uses keys that are fully managed by OSS for encryption and decryption (SSE-OSS). KMS: uses keys that are managed by KMS for encryption and decryption. SM4: the SM4 algorithm. Note In OSS on CloudBox scenarios, only AES256 encryption is supported.
x-oss-object-acl	string	No	private	The ACL of the object. Valid values: default (default): The object inherits the bucket ACL. private: Only the owner and authorized users have read and write permissions on the object. Other users cannot access the object. public-read: Only the owner and authorized users can read and write the object. Other users have read-only access. Use with caution. public-read-write: All users have read and write access. Use with caution. Access permissions are described in Object ACL.
x-oss-storage-class	string	No	Standard	The storage class of the object. When specified, the object is stored in this class regardless of the bucket storage class. For example, setting x-oss-storage-class to Standard in an IA bucket stores the object as Standard. Valid values: Standard: Standard IA: Infrequent Access Archive: Archive Storage Details are available in Storage classes. Important This request header takes effect only for the first append operation. It does not take effect for subsequent append operations. Objects of the Appendable type cannot be converted to the Cold Archive or Deep Cold Archive storage class in any way. In OSS on CloudBox scenarios, only the Standard storage class is supported.
x-oss-meta-*	string	No	x-oss-meta-location	Custom metadata headers. Applies only to the first append operation. Parameters prefixed with x-oss-meta-* are stored as object metadata. Size limit: Total metadata cannot exceed 8 KB. Naming rules: Only hyphens (-), digits, and lowercase letters (a-z) are allowed. Uppercase letters are converted to lowercase. Underscores (_) are not supported.
x-oss-tagging	string	No	TagA=A	Object tags in key-value format. Multiple tags are separated by ampersands, 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`.

This operation also supports 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

Indicates an AppendObject operation. Each call updates the object's last modified time.

position

string

Yes

0

The byte offset from which to start appending. After each successful operation, x-oss-next-append-position indicates the next position.

The first append must set position to 0. Subsequent appends must set position to the current object size. For example, if the first append has content-length 65536, the second must set position to 65536.

When position is 0 and no same-name object exists, the request behaves like PutObject. You can set headers such as x-oss-server-side-encryption, which is then included in subsequent AppendObject responses. To modify metadata later, use CopyObject.
Appending zero-length content at the correct position does not change the object state.

Response headers

Response header

Type

Example

Description

x-oss-next-append-position

64-bit integer

1717

The position for the next append, equal to the current object size.

Returned on success or when a 409 error occurs due to a position mismatch.

x-oss-hash-crc64ecma

64-bit integer

3231342946509354535

The 64-bit CRC value of the object, calculated per the CRC-64/XZ standard.

This operation also supports Common response headers.

CRC-64 calculation

Supported calculation methods:

Calculation 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();
}

Calculation using Python crcmod

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

Related operations

Other operation	Relationship description
PutObject	PutObject on an existing Appendable object overwrites it and changes its type to Normal.
HeadObject	HeadObject on an Appendable object returns x-oss-next-append-position, x-oss-hash-crc64ecma, and x-oss-object-type (set to Appendable).
GetBucket (ListObjects)	GetBucket lists Appendable objects with Type 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

When versioning is enabled, the AppendObject response includes x-oss-version-id, which specifies the version ID of the current 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****

SDKs

SDKs for this operation:

ossutil command line interface

Use the append-object command in ossutil.

Error codes

Error code	HTTP status code	Description
ObjectNotAppendable	409	AppendObject was called on a non-Appendable object.
PositionNotEqualToLength	409	The value of position does not match the current length of the object. Use the x-oss-next-append-position response header to retry. Concurrent requests may still fail with this error. When position is 0, the request succeeds only if no same-name Appendable object exists or the existing one has length 0. Otherwise, this error is returned.
InvalidArgument	400	The values of parameters such as x-oss-storage-class and x-oss-object-acl are invalid.
FileImmutable	409	The bucket is in a protected state and does not allow deletion or modification.
KmsServiceNotEnabled	403	KMS encryption was specified but Key Management Service (KMS) is not enabled in the console.