AppendObject - Object Storage Service - Alibaba Cloud Documentation Center

Uploads an object by appending the object to an existing object. Objects created by using the AppendObject operation are appendable objects. Objects uploaded by using the PutObject operation are normal objects.

Versioning

When you perform operations on appendable objects in a bucket for which versioning is enabled or suspended, take note of the following items:

You can perform the AppendObject operation only on an object whose current version is an appendable object. When you perform this operation, Object Storage Service (OSS) does not generate a previous version for the appendable object.
When you perform the PutObject or DeleteObject operation on an object whose current version is an appendable object, OSS stores the appendable object as a previous version. However, the appendable object cannot be further appended.
Appendable objects cannot be copied.
The AppendObject operation cannot be performed on non-appendable objects such as normal objects and delete markers.

Limits

The maximum size of an object generated by using the AppendObject operation is 5 GB.
The AppendObject operation cannot be performed on objects that are protected by a retention policy. For more information, see Retention policies.
Appendable objects stored in the OSS server cannot be encrypted by using a specified customer master key (CMK) ID.

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

Important

The append and position headers are both CanonicalizedResource and must be included in the signature in the AppendObject request.

Header	Type	Required	Example	Description
append	String	Yes	N/A	Specifies that the request is an AppendObject request. Each time an AppendObject operation is performed on an object, the time when the object is last modified is updated.
position	String	Yes	0	The position from which the AppendObject operation starts. Each time an AppendObject operation succeeds, the x-oss-next-append-position header is included in the response to specify the position from which the next AppendObject operation starts. The value of position in the first AppendObject operation performed on an object must be 0. The value of position in subsequent AppendObject operations performed on the object is the current length of the object. For example, if the value of position specified in the first AppendObject request is 0 and the value of Content-Length is 65536, the value of position in the second AppendObject request must be set to 65536. If the value of position in an AppendObject request is 0 and an object that has the same name as the appended object does not exist, you can set headers such as x-oss-server-side-encryption in the AppendObject request in the same way as you do in a PutObject request. If you add a valid x-oss-server-side-encryption header to an AppendObject request in which the value of position is 0, the x-oss-server-side-encryption header is included in the response to the request. To modify the metadata specified by the headers, you can initiate a CopyObject request. If you initiate an AppendObject request in which the value of position is valid to append an object that is 0 KB in size to an existing appendable object, the status of the appendable object is not changed.
Cache-control	String	No	no-cache	The caching behavior of the web page for the object. For more information, see RFC 2616. This parameter is empty by default.
Content-Disposition	String	No	attachment;filename=oss_download.jpg	The name of the object when the object is downloaded. For more information, see RFC 2616. This parameter is empty by default.
Content-Encoding	String	No	utf-8	The encoding format for the content of the object. For more information, see RFC 2616. This parameter is empty by default.
Content-MD5	String	No	ohhnqLBJFiKkPSBO1eNaUA==	The value of Content-MD5 is a string calculated based on the MD5 algorithm. This header is used to check whether the content of the received message is the same as the content of the sent message. To obtain the value of the Content-MD5 header, calculate a 128-bit number based on the message content except for the header, and then encode the number in Base64. This parameter is empty by default. Limits: none
Expires	GMT	No	Wed, 08 Jul 2015 16:57:01 GMT	The time when the cached data expires. For more information, see RFC 2616. This parameter is empty by default.
x-oss-server-side-encryption	String	No	AES256	The method used to encrypt objects on the OSS server. Valid values: AES256: Keys managed by OSS are used for encryption and decryption (SSE-OSS). KMS: CMKs managed by Key Management Service (KMS) are used for encryption and decryption.
x-oss-object-acl	String	No	private	The access control list (ACL) of the object. Default value: default. Valid values: default: The ACL of the object is the same as the ACL of the bucket in which the object is stored. private: The ACL of the object is private. Only the owner of the object and authorized users can read and write this object. public-read: The ACL of the object is public read. Only the owner of the object and authorized users can read and write this object. Other users can only read the object. Exercise caution when you set the object ACL to this value. public-read-write: The ACL of the object is public read/write. All users can read and write this object. Exercise caution when you set the object ACL to this value. For more information about object ACLs, see Object ACL.
x-oss-storage-class	String	No	Standard	The storage class of the object. If you specify the header when you upload an object, the storage class of the uploaded object is the specified header value regardless of the storage class of the bucket to which the object is uploaded. For example, if you set x-oss-storage-class to Standard when you upload an object to an IA bucket, the object is stored as a Standard object. Valid values: Standard IA Archive For more information about storage classes, see Overview. Important This header takes effect only when you perform the AppendObject operation on an object for the first time. The storage class of appendable objects cannot be converted to Cold Archive or Deep Cold Archive.
x-oss-meta-*	String	No	x-oss-meta-location	You can add parameters prefixed with x-oss-meta- when you create an appendable object by performing the AppendObject operation. These parameters cannot be included in the requests when you append objects to an existing appendable object. Parameters prefixed with x-oss-meta-* are considered the user metadata of the object. You can configure multiple parameters prefixed with x-oss-meta- for an object. However, the total size of the metadata cannot exceed 8 KB. The name of parameters prefixed with x-oss-meta- can contain hyphens (-), digits, and letters. Uppercase letters are converted to lowercase letters. Other characters such as underscores (_) are not supported.
x-oss-tagging	String	No	TagA=A	The tags that you want to add to the object. A tag is a key-value pair. You can specify multiple tags for the object at a time. Example: `TagA=A&TagB=B`. Important This header takes effect only when you perform the AppendObject operation on an object for the first time. The tag key and value must be URL-encoded. The key is required and the value is optional. For example, you can set the tags to `TagA&TagB=B`.

For more information about the common request headers included in an AppendObject request, see Common request headers.

Response headers

Header

Type

Example

Description

x-oss-next-append-position

64-bit integer

1717

The position that must be provided in the next request, which is the current length of the object.

This header is returned when a success message is returned for an AppendObject request, or when the 409 HTTP status code is returned because the position and the object length do not match.

x-oss-hash-crc64ecma

64-bit integer

3231342946509354535

The 64-bit CRC value of the object. This value is calculated based on the ECMA-182 standard.

For more information about the common response headers that are contained in the response to an AppendObject request, see Common response headers.

Methods used to calculate the 64-bit CRC value

The CRC value of an appendable object is calculated based on the ECMA-182 standard. You can calculate the 64-bit CRC value of an object by using the following methods:

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

Use the crcmod function in Python:

do_crc64 = crcmod.mkCrcFun(0x142F0E1EBA9EA3693L, initCrc=0L, xorOut=0xffffffffffffffffL, rev=True)
print do_crc64("123456789")

Association with other operations

Operation	Relationship
PutObject	If you perform a PutObject operation on an existing appendable object, the appendable object is overwritten by a new normal object.
HeadObject	If you perform a HeadObject operation on an existing appendable object, x-oss-next-append-position, x-oss-hash-crc64ecma, and x-oss-object-type are returned. The x-oss-object-type value of the appendable object is Appendable.
GetBucket (ListObjects)	In the response to a GetBucket request, the x-oss-object-type value of an appendable object is Appendable.
CopyObject	You can use CopyObject to modify the user metadata of an appendable object. Appendable objects cannot be copied by using CopyObject. The server-side encryption method for an appendable object cannot be modified by using CopyObject.

Examples

Sample requests

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 
Content-Encoding: utf-8 
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: OSS qn6qrrqxo2oawuk53otf****:kZoYNv66bsmc10+dcGKw5x2P****  
[1717 bytes of object data]

Sample responses

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****

Sample requests for a versioned bucket

If you perform the AppendObject operation on an object in a bucket for which versioning is enabled or suspended, the x-oss-version-id header is included in the response and its value must be null.

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: OSS bwo4j5l8d3j****:MCY5nnfgfJU/f3Xe0odqBtG5****

Sample responses

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: null
x-oss-hash-crc64ecma: 3231342946509354535
x-oss-next-append-position: 3
x-oss-request-id: 5CAC18A5B7AEADE01700****

SDK

You can use OSS SDKs for the following programming languages to call the AppendObject operation:

Error codes

Error code	HTTP status code	Description
ObjectNotAppendable	409	The error message returned because you performed the AppendObject operation on a non-appendable object.
PositionNotEqualToLength	409	The error message returned because the value of position does not match the current object length. You can obtain the position for the next AppendObject operation from the x-oss-next-append-position header in the response to the current request. Multiple requests may be sent concurrently. Therefore, even if you set the value of x-oss-next-append-position in a request, the request may still fail because the value is not updated immediately. The request is successful when the value of position is 0 and the length of an appendable object with the same name is 0 or an appendable object with the same name does not exist. In other cases, this error code is returned because the position and the length of the object do not match.
InvalidArgument	400	The error message returned because the value of a parameter such as x-oss-storage-class or x-oss-object-acl is invalid.
FileImmutable	409	The error message returned because the data that you want to delete or modify is protected by a retention policy.
KmsServiceNotEnabled	403	The error message returned because KMS is specified as the server-side encryption method but KMS is not activated in the console.