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
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.
|
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:
|
x-oss-object-acl | String | No | private | The access control list (ACL) of the object. Default value: default. Valid values:
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:
For more information about storage classes, see Overview. Important
|
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: Important
|
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 |
If you perform a PutObject operation on an existing appendable object, the appendable object is overwritten by a new normal object. | |
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. | |
In the response to a GetBucket request, the x-oss-object-type value of an appendable object is Appendable. | |
|
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 |
|
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. |