AppendObject

An object created with the AppendObject operation is an appendable object, and an object uploaded with the PutObject operation is a normal object.

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 header

Response header

Association with other operations

• The AppendObject operation is not applicable to a non-appendable object. For example, if the AppendObject operation is performed when a normal object with the same name already exists, a 409 message is returned with the ObjectNotAppendable error code.
• If you perform the PutObject 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.
• After the HeadObject operation is performed, the system returns x-oss-object-type that 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 HeadObject operation is performed, the system returns x-oss-next-append-position and x-oss-hash-crc64ecma.
• In the response XML for a GetBucket (ListObjects) request, the Type of the appendable object is set to Appendable.
• You can neither use CopyObject to copy an appendable object, nor change the server-side encryption of this object. However, you can use CopyObject to modify the custom metadata of an object.

Detail analysis

• The two URL parameters, append and position, are both CanonicalizedResource, and must be included in the signature.
  • URL parameters must also include append, which specifies that the operation is AppendObject.
  • URL query parameters must include position, which specifies the position from where the append of the object 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 operation succeeds, x-oss-next-append-position in the response header specifies the position of the next AppendObject request.
• 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 AppendObject operation is successful. Otherwise, the system determines that the position and object length do not match.
  • If the position value is 0 and an object with the same name does not exist, headers (such as x-oss-server-side-encryption) set in the PutObject request can be set in the AppendObject request. This action is the same as that of InitiateMultipartUpload. 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 AppendObject request also contains the x-oss-server-side-encryption header that indicates the encryption algorithm. Afterwards, if the meta must be modified, you can use the CopyObject request.
• If the position value is different from the current object length, the OSS returns a 409 error with the PositionNotEqualToLength error code. If such an error occurs, you can obtain the position for the next AppendObject request from x-oss-next-append-position in the response header, and send an AppendObject request again.
• However, because of concurrency, even if you set the value of position to x-oss-next-append-position, this request may still fail due to the PositionNotEqualToLength error.
• The length limit of an object generated by AppendObject is the same as that of an object generated by PutObject. Each time after an AppendObject operation is performed, the last modification time of this object is updated.
• If the position value is correct and the content with a length of 0 is appended to an existing appendable object, the status of the object does not change.

CRC64 calculation method

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

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();
}

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

do_crc64 = crcmod.mkCrcFun(0x142F0E1EBA9EA3693L, initCrc=0L, xorOut=0xffffffffffffffffL, rev=True)

print do_crc64(“123456789”)

Example

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+dcGKw5x2PRrk=  
[1717 bytes of object data]

Response example:

HTTP/1.1 200 OK
Date: Wed, 08 Jul 2015 06:57:01 GMT
ETag: "0F7230CAA4BE94CCBDC99C5500000000"
Connection: keep-alive
Content-Length: 0  
Server: AliyunOSS
x-oss-hash-crc64ecma: 14741617095266562575
x-oss-next-append-position: 1717
x-oss-request-id: 559CC9BDC755F95A64485981