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

Versioning

When you perform operations on append 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 append object. When you perform this operation, OSS does not generate a previous version for the append object.

    When you perform the PutObject or DeleteObject operation on an object whose current version is an append object, OSS stores the append object as a previous version and prevents the object from being further appended.

  • Append objects cannot be copied.
  • The AppendObject operation cannot be performed on objects that are not created by using AppendObject, 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 policy.
  • Append objects stored on the OSS server cannot be encrypted by using a specified 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

Notice 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 last modified time of this object 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 the AppendObject request is 0 and an object that has the same name as that of the object to append 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 valid 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 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 0 KB in size to an existing append object, the status of the append object is not changed.
Cache-control String No no-cache The web page caching behavior for the object. For more information, visit RFC2616.

Default value: null
Content-Disposition String No attachment;filename=oss_download.jpg

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

Default value: null
Content-Encoding String No utf-8 The encoding format of the object. For more information, visit RFC2616.

Default value: null
Content-MD5 String No ohhnqLBJFiKkPSBO1eNaUA== The value of Content-MD5 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 number based on the message content except for the header, and then encode the number in Base64.

Default value: null

Limits: none
Expires GMT No Wed, 08 Jul 2015 16:57:01 GMT The time when the cache expires. For more information, visit RFC2616.

Default value: null
x-oss-server-side-encryption String No AES256 The method used to encrypt objects on the OSS server.
Valid values:
  • AES256: uses keys managed by OSS for encryption and decryption (SSE-OSS).
  • KMS: uses CMKs managed by KMS for encryption and decryption.
  • SM4: uses the SM4 block cipher algorithm for encryption and decryption.
x-oss-object-acl String No private The ACL of the object.
Valid values:
  • public-read: Only the bucket owner can perform write operations on objects in the bucket. Other users, including anonymous users, can perform only read operations on the objects in the bucket.
  • private: Only the bucket owner can perform read and write operations on objects in the bucket. Other users cannot access the objects in the bucket.
  • public-read-write: All users, including anonymous users can read and write objects in the bucket. Fees incurred by such operations are paid by the owner of the bucket. Configure this ACL only when necessary.
x-oss-storage-class String No Standard The storage class of the object.

If you specify the storage class when you upload the object, the specified storage class applies regardless of the storage class of the bucket that contains the object. 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
Notice This header takes effect only when you perform the AppendObject operation on an object for the first time.

Supported operations: PutObject, InitiateMultipartUpload, AppendObject, PutObjectSymlink, and CopyObject.
x-oss-meta-* String No x-oss-meta-location You can add parameters prefixed with x-oss-meta- when you create an append object by performing the AppendObject operation. These parameters cannot be included in the requests when you append objects to an existing append object. Parameters prefixed with x-oss-meta- are considered user metadata.

You can configure multiple parameters prefixed with x-oss-meta- for an object. However, the total size of user metadata cannot exceed 8 KB.

The name of parameters prefixed with x-oss-meta- can contain hyphens (-), numbers, and letters. Uppercase letters are converted to lowercase letters. Other characters such as underscores (_) are not supported.

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

Response headers

Header Type Examples 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 included in the response to the AppendObject request, see Common response headers.

Methods to calculate the 64-bit CRC value

The CRC value of an append 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")

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:

Association with other operations

Operation 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 value of the append object is Appendable.
GetBucket In the response to a GetBucket request, the x-oss-object-type of an append object is Appendable.
CopyObject
  • You can use CopyObject to modify the user metadata of an append object.
  • Append objects cannot be copied by using CopyObject.
  • The server-side encryption method for an append object cannot be modified by using CopyObject.

Error codes

Error code HTTP status code Description
ObjectNotAppendable 409 The error message returned because you performed the AppendObject operation on a non-append 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 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 error message returned because the values of parameters such as x-oss-storage-class or x-oss-object-acl are invalid.
FileImmutable 409 The error message returned because the data 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.