AppendObject - Object Storage Service - Alibaba Cloud Documentation Center

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

Versioning

When you call the AppendObject operation on an appendable object in a bucket for which versioning is enabled or suspended, take note of the following items:

You can call the AppendObject operation only on an object whose current version is an appendable object. When you call this operation, Object Storage Service (OSS) does not generate a previous version for the appendable object.
When you call 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, you cannot append any content to the appendable object.
You can call the AppendObject operation on only appendable objects. You cannot call the AppendObject operation on objects of other types, such as normal objects and delete markers.

Limits

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

Request structure

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

Header	Type	Required	Example	Description
Cache-control	String	No	no-cache	The web page caching behavior of the object. For more information, visit RFC 2616. By default, this parameter is left empty.
Content-Disposition	String	No	attachment;filename=oss_download.jpg	The name of the object when the object is downloaded. For more information, visit RFC 2616. By default, this parameter is left empty.
Content-Encoding	String	No	utf-8	The encoding format of the object. For more information, visit RFC 2616. By default, this parameter is left empty.
Content-MD5	String	No	ohhnqLBJFiKkPSBO1eNaUA==	The MD5 hash calculated by using the MD5 algorithm. This header is used to check whether the content of the received message is the same as that 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 Base64-encode the number. By default, this parameter is left empty. Limits: none.
Expires	GMT	No	Wed, 08 Jul 2015 16:57:01 GMT	The expiration time. For more information, visit RFC 2616. By default, this parameter is left empty.
x-oss-server-side-encryption	String	No	AES256	The method that is 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. Valid values: default (default): The ACL of the object is the same as that 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 have the read and write permissions on the object. public-read: The ACL of the object is public-read. Only the owner of the object and authorized users have the read and write permissions on the object. Other users have only the read permissions on the object. Exercise caution when you set the ACL of the object to this value. public-read-write: The ACL of the object is public-read-write. All users have the read and write permissions on the object. Exercise caution when you set the ACL of the object to this value. For more information, see Object ACLs.
x-oss-storage-class	String	No	Standard	The storage class of the object. If you specify the x-oss-storage-class header when you upload an object, the storage class of the uploaded object is the specified value regardless of the storage class of the bucket to which the object is uploaded. For example, if you set the x-oss-storage-class header to Standard when you upload an object to an Infrequent Access (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 the first time you call the AppendObject operation on an object. 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	The parameters that can be added to an AppendObject request when you create an appendable object. The parameters must contain the x-oss-meta- prefix. These parameters cannot be included in the requests when you append objects to an existing appendable object. Parameters that contain the x-oss-meta-* prefix are considered the metadata of the object. You can specify multiple parameters that contain the x-oss-meta- prefix for an object. The total size of the metadata cannot exceed 8 KB. The names of the parameters that contain the x-oss-meta- prefix 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 are specified for the object in key-value pair. You can specify multiple tags for an object. Example: `TagA=A&TagB=B`. Important This header takes effect only the first time you call the AppendObject operation on an object. The tag key and tag value must be URL-encoded. When you specify a tag for an object, only the tag key is required and the tag value is optional. Example: `TagA&TagB=B`.

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

Parameters in the request

Important

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

Parameter

Type

Required

Example

Description

append

String

Yes

N/A

Specifies that the request is an AppendObject request. Each time an AppendObject operation is called on an object, the time when the object is last modified is updated.

position

String

Yes

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 the position header in the first AppendObject operation called on an object must be 0. The value of the position header in subsequent AppendObject operations called on the object is the current length of the object. For example, if the value of the position header specified in the first AppendObject request is 0 and the value of Content-Length is 65536, the value of the position header in the second AppendObject request must be set to 65536.

If the value of the position header in an AppendObject request is 0 and no object that has the same name as the appendable object exists, you can specify headers, such as x-oss-server-side-encryption, in the AppendObject request in the same manner as that in a PutObject request. If you specify a valid value for the x-oss-server-side-encryption header in an AppendObject request, the x-oss-server-side-encryption header is included in the response to the request. If you want to modify metadata, you can call the CopyObject operation.
If you call an AppendObject request in which the value of the position header is valid to append an object whose size is 0 KB to an existing appendable object, the status of the appendable object remains unchanged.

Response headers

Header

Type

Example

Description

x-oss-next-append-position

64-bit integer

1717

The position from which the next append operation starts, which is the length of the object.

This header is returned when an AppendObject request is successful, or when HTTP status code 409 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 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 one of 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")

Relationship with other operations

Operation	Relationship
PutObject	If you call the PutObject operation on an existing appendable object, the appendable object is converted to a normal object.
HeadObject	If you call the HeadObject operation on an existing appendable object, the x-oss-next-append-position, x-oss-hash-crc64ecma, and x-oss-object-type headers 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.

Examples

Sample request

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 qn6q**************:77Dv****************  
[1717 bytes of object data]

Sample success response

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 request for a versioned bucket

If you call the AppendObject operation on an object in a bucket for which versioning is enabled, the x-oss-version-id header is included in the response and its value is the current version ID 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: OSS qn6q**************:77Dv****************

Sample success response

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

You can use OSS SDKs for the following programming languages to call ListBuckets (GetService):

Error codes

Error code	HTTP status code	Description
ObjectNotAppendable	409	You called the AppendObject operation on a non-appendable object.
PositionNotEqualToLength	409	The value of the position header does not match the current object length. You can obtain the position from which the next AppendObject operation starts based on the value of 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 the x-oss-next-append-position header to the value of the position header in a request, the request may still fail because the value is not updated immediately. The request is successful when the value of the position header 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 value of a parameter, such as x-oss-storage-class or x-oss-object-acl, is invalid.
FileImmutable	409	The data that you want to delete or modify is protected by a retention policy.
KmsServiceNotEnabled	403	KMS is specified as the server-side encryption method but KMS is not activated in the console.