Uploads a file by appending the file to an existing object. An object created by the AppendObject operation is an appendable object, and an object uploaded by the PutObject operation is a normal object.

Versioning

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

Note
  • When you perform the AppendObject operation on an object of which the current version is an appendable object, OSS does not generate historical version for the appendable object.
  • When you perform the PutObject or DeleteObject operation on an object of which the current version is an appendable object, OSS stores the appendable object as a historical 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 appendable 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 appendable objects in the bucket.

Limits

  • The maximum size of an object generated by the AppendObject operation is 5 GB.
  • You cannot use AppendObject to upload a file to an object protected by the compliant retention strategy.
  • You cannot use KMS to encrypt appendable 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 Indicates that the request is sent to perform an AppendObject operation.
Position String Yes

Specifies the position from where the AppendObject operation starts.

The value of position in the first AppendObject operation must be 0, and 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 after 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 do 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 after an AppendObject operation is performed, the last modification time of this object is updated.
  • If the position value is correct and content with a length of 0 is appended to an existing appendable object, the status of the object does not change.
Cache-Control String No Specifies the Web page caching behavior for the object. For more information, see RFC2616.

Default value: none
Content-Disposition String Specifies the name of the object when the object is downloaded. For more information, see RFC2616.

Default value: none
Content-Encoding String Specifies the content encoding format of the object. For more information, see RFC2616.

Default value: none
Content-MD5 String Content-MD5 is a string calculated by the MD5 algorithm. This header is used to check whether the message content is consistent with the sent content.

The value of Content-MD5 can be obtained as follows: Calculate a 128-bit number based on the message content, rather than the header, and then base64-encode the number.

Default value: none

Restriction: none
Expires Integer Specifies the expiration time. For more information, see RFC2616.

Default value: none
x-oss-server-side-encryption String Specifies the server-side encryption algorithm.

Valid values: AES256 or KMS

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

Valid values: public-read, private, and public-read-write
x-oss-storage-class String Specifies the storage class of the object.
Values:
  • Standard
  • IA
  • Archive

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

Note
  • If you specify the value of x-oss-storage-class when uploading 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 specify the value of x-oss-storage-class to Standard when uploading an object to a bucket of the IA storage class, the storage class of the object is Standard.
  • This header takes effect only if you specify it when you perform the AppendObject operation for the first time.
Note
  • When you call AppendObject, parameters prefixed by x-oss-meta-*, such as x-oss-meta-location, are processed as metadata of the object. An object can have multiple metadata parameters. However, the total size of the metadata cannot exceed 8 KB. The name of a metadata parameter supports dashes (-), numbers, and letters (uppercase letters are converted to lowercase letters) but does not support underscores (_).
  • You can add parameters prefixed with x-oss-meta-* when creating a new appendable object by performing the AppendObject operation. However, you cannot add these parameters when appending files to an existing appendable object.

Response headers

Header Type Description
x-oss-next-append-position 64-bit integer

Specifies the position that must be provided in the next request, that is, the current object length.

This header is returned when a successful message is returned for an AppendObject request, or when a 409 error occurs because the position and the object length do not match.

x-oss-hash-crc64ecma 64-bit integer Specifies the 64-bit CRC value of the object. This value is calculated according to the ECMA-182.

CRC64 calculation method

The CRC value of an appendable object is calculated according to ECMA-182. You can calculate the CRC64 in the following methods:

  • Calculate using 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 the crcmod function in Python: 
    do_crc64 = crcmod.mkCrcFun(0x142F0E1EBA9EA3693L, initCrc=0L, xorOut=0xffffffffffffffffL, rev=True)

print do_crc64(“123456789”)

Examples

  • Normal 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 
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]

    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: 559CC9BDC755F95A64485981

  • Example of a request initiated to append a file to an existing object in a bucket with versioning enabled or suspended: 

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

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

SDK

The SDKs of this API are as follows:

Association with other operations

Operations 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, then x-oss-next-append-position, x-oss-hash-crc64ecma, and x-oss-object-type are returned. The x-oss-object-type of the appendable object is Appendable.
GetBucket In the response to a GetBucket request, the x-oss-object-type of the appendable object is set to Appendable.
CopyObject You can neither use CopyObject to copy an appendable object, nor change the server-side encryption method of this object. However, you can use CopyObject to modify the custom metadata of an object.

Error codes

Error code HTTP status code Description
ObjectNotAppendable 409 You cannot perform AppendObject operations on a non-appendable 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 appendable object with the same name is 0. or the 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, is invalid.