Append Object

Last Updated: May 09, 2017

Append Object is used to upload files in appending mode. The type of the objects created with the Append Object operation is Appendable Object, and the type of the objects uploaded with the Put Object operation is Normal Object.

Request syntax

  1. POST /ObjectName?append&position=Position HTTP/1.1
  2. Content-LengthContentLength
  3. Content-Type: ContentType
  4. Host: BucketName.oss.aliyuncs.com
  5. Date: GMT Date
  6. Authorization: SignatureValue

Request header

Name Description
Cache-Control Specifies the cache action of the web page when the object is downloaded. Refer to RFC2616 for details.
Type: string
Default value: None
Content-Disposition Specifies the name of the object downloaded. Refer to RFC2616.
Type: string
Default value: None
Content-Encoding Specifies the content encoding format when the object is downloaded. Refer to RFC2616 for details.
Type: string
Default value: None
Content-MD5 As defined in RFC 1864, the message content (excluding the header) is computed to obtain an MD5 value, which is a 128-bit number. Then, this number is Base64-encoded into a Content-MD5 value. This request header can be used for checking the validity of a message, that is, whether the message content is consistent with the sent content. Although this request header is optional, OSS recommends that you use this request header for end-to-end check.
Type: string
Default value: None
Restrictions: None
Expires Indicates the expiration time. Refer to RFC2616 for details.
Type: Integer
Default value: None
x-oss-server-side-encryption Specifies the server-side encryption algorithm when the OSS creates an object.
Type: string
Valid value: AES256
x-oss-object-acl Specifies the access permission when the OSS creates an object.
Type: string
Valid values: public-read, private, and public-read-write

Response header

Name Description
x-oss-next-append-position Specifies the position that should be provided in the next request. It is in fact the current object length. This header is contained when a successful message is returned for Append Object, or when a 409 error occurs due to mismatching of the position and the object length.
Type: 64-digit integer
x-oss-hash-crc64ecma Specifies the 64-bit CRC value of the object. The 64-bit CRC value is calculated according to ECMA-182 Standard
Type: 64-digit integer

Association with other operations

  1. Append Object is not applicable to a non-appendable object. For example, if a normal object with the same name already exists and the Append Object operation is still performed, the system returns the 409 message and the error code ObjectNotAppendable.
  2. If you perform the Put Object operation on an existing appendable object, this appendable object is overwritten by the new object, and the type of this object is changed to Normal Object.
  3. After the Head Object operation is performed, the system returns x-oss-object-type, which indicates the type of the object. If the object is an appendable object, the value of x-oss-object-type is Appendable. For an appendable object, after the Head Object operation is performed, the system also returns x-oss-next-append-position and x-oss-hash-crc64ecma.
  4. In the response XML of the Get Bucket (List Objects) request, the type of an appendable object is set to Appendable.
  5. You can neither use Copy Object to copy an appendable object, nor change the server-side encryption attribute of this object. You can use Copy Object to modify the custom metadata.

Detail analysis:

  1. The two URL parameters, append and position, are both CanonicalizedResource, and must be contained in the signature.
  2. URL parameters must also contain append, which specifies that the operation is an Append Object operation.
  3. URL query parameters must contain position, which specifies the position from where appending starts. The value of position in the first Append Object 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 Append Object request is 0, and the value of content-length is 65536, the value of position specified in the second Append Object request must be set to 65536. After each operation succeeds, x-oss-next-append-position in the response header will also specify the position of the next Appendix Object request.
  4. If the position value is different from the current object length, the OSS returns the 409 message and the error code PositionNotEqualToLength. If such an error occurs, you can obtain the position for the next Append Object request from x-oss-next-append-position in the response header, and send an Append Object request again.
  5. If the position value is 0 and an appendable object with the same name does not exist, or if the length of an appendable object with the same name is 0, the Append Object operation is successful; otherwise, the system regards that the position and object length are mismatched.
  6. If the position value is 0 and an object with the same name does not exist, headers (such as x-oss-server-side-encryption) can be set in the Append Object request like the Put Object request. This is the same as the case of Initiate Multipart Upload. If the position value is 0, and the correct x-oss-server-side-encryption header is added to the request, the header of the response to the subsequent Append Object request will also contain x-oss-server-side-encryption, which indicates the encryption algorithm. Later, if meta needs to be modified, you can use the Copy Object request.
  7. Due to the concurrency, even if you set the value of position to x-oss-next-append-position, this request can still fails due to PositionNotEqualToLength.
  8. The length limit of an object generated by Append Object is the same as that of an object generated by Put Object.
  9. After each Append Object operation, the last modification time of this object will be updated.
  10. If the position value is correct and the content with the length of 0 is appended to an existing appendable object, this operation does not change the status of the object.
  11. If the bucket type is Archive, you cannot call this interface; otherwise, the system returns Error 400 with the error code “OperationNotSupported”.

CRC64 computing method

The CRC value of an appendable object is computed according to ECMA-182 Standard. Its computing method is the same as that of XZ. CRC64 can be computed as follows using the boost CRC module:

  1. typedef boost::crc_optimal<64, 0x42F0E1EBA9EA3693ULL, 0xffffffffffffffffULL, 0xffffffffffffffffULL, true, true> boost_ecma;
  2. uint64_t do_boost_crc(const char* buffer, int length)
  3. {
  4. boost_ecma crc;
  5. crc.process_bytes(buffer, length);
  6. return crc.checksum();
  7. }

Alternatively, CRC64 can be computed as follows using the Python crcmod:

  1. do_crc64 = crcmod.mkCrcFun(0x142F0E1EBA9EA3693L, initCrc=0L, xorOut=0xffffffffffffffffL, rev=True)
  2. print do_crc64(“123456789”)

Example

Request example:

  1. POST /oss.jpg?append&position=0 HTTP/1.1
  2. Host: oss-example.oss.aliyuncs.com
  3. Cache-control: no-cache
  4. Expires: Wed, 08 Jul 2015 16:57:01 GMT
  5. Content-Encoding: utf-8
  6. Content-Disposition: attachment;filename=oss_download.jpg
  7. Date: Wed, 08 Jul 2015 06:57:01 GMT
  8. Content-Type: image/jpg
  9. Content-Length: 1717
  10. Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:kZoYNv66bsmc10+dcGKw5x2PRrk=
  11. [1717 bytes of object data]

Return example:

  1. HTTP/1.1 200 OK
  2. Date: Wed, 08 Jul 2015 06:57:01 GMT
  3. ETag: "0F7230CAA4BE94CCBDC99C5500000000"
  4. Connection: keep-alive
  5. Content-Length: 0
  6. Server: AliyunOSS
  7. x-oss-hash-crc64ecma: 14741617095266562575
  8. x-oss-next-append-position: 1717
  9. x-oss-request-id: 559CC9BDC755F95A64485981
Thank you! We've received your feedback.