You can call this operation to upload an object by appending the object to an existing object. Objects created by the AppendObject operation are AES256s, whereas objects uploaded by the PutObject operation are normal objects.

Versioning

The AppendObject operation can be performed only on objects of which the current version is an append object.

  • When you perform the AppendObject operation on an object of which the current version is an append object, OSS does not generate a previous version for the append object.
  • When you perform the PutObject or DeleteObject operation on an object of which the current version is an append object, OSS stores the append object as a previous version and prevents the object from being further appended.
  • You cannot perform the AppendObject operation on objects of which the current version is not an append object such as a normal object or a delete marker.
  • If versioning is enabled or suspended for a bucket, you cannot perform the CopyObject operation on append objects in the bucket.

Limits

  • The maximum size of an object generated by using the AppendObject operation is 5 GB.
  • You cannot perform AppendObject to append an object on an object protected by the retention policy.
  • You cannot use KMS to encrypt append objects on the server by specifying CMK IDs for the objects.

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

Note An AppendObject request must include the append and position parameters, which are both CanonicalizedResource and must be included in the signature.
Header Type Required Description
Append String Yes The request that is sent to perform an AppendObject operation.
Position String Yes The position from which the AppendObject operation starts.

The value of position in the first AppendObject operation must be 0. The value of position in the subsequent operation is the current object length. 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 specified in the second AppendObject request must be set to 65536.

Each time an AppendObject operation succeeds, x-oss-next-append-position in the response header specifies the position of the next AppendObject request.

Note
  • If the value of position is 0 and an object with the same name does not exist, you can set headers, such as x-oss-server-side-encryption in the AppendObject request in the same way as you set in a PutObject request. If you add a correct x-oss-server-side-encryption header in an AppendObject request in which the value of position is 0, the x-oss-server-side-encryption header is also included in the response header. You can initiate a CopyObject request to modify the metadata of the object in subsequent operations.
  • Each time an AppendObject operation is performed, the last modified time of this object is updated.
  • If the position value is correct and the content with a length of 0 is appended to an existing append object, the status of the object does not change.
Cache-Control String No The web page caching behavior for the object. For more information, visit RFC 2616.

Default value: none
Content-Disposition String No

The name of the object when the object is downloaded. For more information, visit RFC 2616.

Default value: none
Content-Encoding String No The object encoding format of the object. For more information, visit RFC 2616.

Default value: none
Content-MD5 String No The Content-MD5 header value is a string 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 byte array based on the message content, rather than the header, and then encode the byte array in Base64.

Default value: none

Limits: none
Expires GMT No The expiration time. For more information, visit RFC 2616.

Default value: none
x-oss-server-side-encryption String No The server-side encryption algorithm.

Valid values: AES256 and KMS

Note You must enable Key Management Service (KMS) on the console before you can use the KMS encryption algorithm. Otherwise, KmsServiceNotEnabled is returned.
x-oss-object-acl String No The ACL for the object.

Valid values: public-read, private, and public-read-write
x-oss-storage-class String No The storage class of the target object.

Values: Standard, IA, and Archive

Supported operations: PutObject, InitMultipartUpload, AppendObject, PutObjectSymlink, and CopyObject

  • If you specify the value of x-oss-storage-class when you upload an object to a bucket, the storage class of the uploaded object is the specified value of x-oss-storage-class regardless of the storage class of the bucket. For example, if you set the value of x-oss-storage-class to Standard when you upload an object to a bucket of the IA storage class, the storage class of the object is Standard.
  • This header takes effect only when you perform the AppendObject operation for the first time.
Note
  • When you call the AppendObject operation, parameters prefixed with x-oss-meta-*, such as x-oss-meta-location, are processed as metadata of the object. An object may have multiple similar parameters, but the total size of the user metadata cannot exceed 8 KB. Metadata supports hyphens (-), digits, and letters. Uppercase letters are converted to lowercase letters, and other characters such as underscores (_) are not supported.
  • You can add parameters prefixed with x-oss-meta-* when creating an append object by performing the AppendObject operation. However, you cannot add these parameters when you append objects to an existing append object.

Response headers

Header Type Description
x-oss-next-append-position 64-bit integer The position that must be provided in the next request, which is the current object length.

This header is returned when a successful 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 The 64-bit CRC value of the object. This value is calculated based on the ECMA-182 standard.

Method for calculating the 64-bit CRC value

The CRC value of an append object is calculated based on the ECMA-182 standard. You can calculate the CRC64 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”)

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 qn6qrrqxo2oawuk53otfjbyc: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: 559CC9BDC755F95A64485981
  • Sample request for a versioning-enabled bucket
    Note If you perform the AppendObject operation on an object in a bucket with versioning enabled or suspended, the x-oss-version-id header is included in the response and its version can only 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 bwo4j5l8d3jou9u: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: 5CAC18A5B7AEADE0170002F7

SDK

The SDKs of the AppendObject operation for various programming languages:

Association with other operations

Operations Relationship
PutObject If you perform a PutObject operation on an existing append object, the append object is overwritten by a new normal object.
HeadObject If you perform a HeadObject operation on an existing append object, x-oss-next-append-position, x-oss-hash-crc64ecma, and x-oss-object-type are returned. The x-oss-object-type of the append object is Appendable. The x-oss-object-type of the append object is Appendable.
GetBucket In the response to a GetBucket request, the x-oss-object-type of the append object is set to Appendable.
CopyObject You can use CopyObject to modify the user metadata of an object.
  • You can neither use CopyObject to copy an append object.
  • nor change the server-side encryption method of this object.

Error codes

Error code HTTP status code Description
ObjectNotAppendable 409 You cannot perform AppendObject operations on a non-append object.
PositionNotEqualToLength 409
  • The value of position does not match the current object length.
    Note You can obtain the position for the next operation from the response header x-oss-next-append-position and initiate a request again. Although multiple requests may be sent concurrently, even if you set the value of x-oss-next-append-position in one 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 append object with the same name is 0 or the append 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 and x-oss-object-acl, are invalid.
FileImmutable 409 The error message returned because you delete or modify the data. During the protection period, data in the bucket is protected.