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. 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 using AppendObject, such as normal objects and delete markers.
Usage notes
- 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 in 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
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.
|
Cache-control | String | No | no-cache | The web page caching behavior for the object. For more information, visit RFC 2616.
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, see RFC 2616. Default value: null |
Content-Encoding | String | No | utf-8 | The encoding format of the object. For more information, visit RFC 2616.
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, see RFC 2616.
Default value: null |
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 ACL of the object.
Valid values:
|
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:
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 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 included in the response to the AppendObject request, see Common response headers.
Methods used 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")
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 (ListObjects) | In the response to a GetBucket request, the x-oss-object-type of an append object is Appendable. |
CopyObject |
|
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 responsesHTTP/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 responsesHTTP/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-append object. |
PositionNotEqualToLength | 409 |
|
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. |