All Products
Search
Document Center

Object Storage Service:AppendObject

Last Updated:Aug 01, 2024

Uploads an object by appending the object to an existing object. Objects created by calling the AppendObject operation are appendable objects. Objects uploaded by calling the PutObject operation are normal objects.

Versioning

When you call the AppendObject operation on an appendable object in a bucket for which versioning is enabled or suspended, take note of the following items:

  • You can call the AppendObject operation only on an object whose current version is an appendable object. When you call this operation, Object Storage Service (OSS) does not generate a previous version for the appendable object.

    When you call 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, you cannot append any content to the appendable object.

  • You can call the AppendObject operation on only appendable objects. You cannot call the AppendObject operation on objects of other types, such as normal objects and delete markers.

Limits

  • The maximum size of an object generated by using the AppendObject operation is 5 GB.

  • You cannot call the AppendObject operation on an object protected by a retention policy. For more information, see Retention policies.

  • Appendable objects stored on the OSS server cannot be encrypted by using a specific customer master key (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

Important

The append and position headers are both CanonicalizedResource and must be included in the signature of 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 called 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 the position header in the first AppendObject operation called on an object must be 0. The value of the position header in subsequent AppendObject operations called on the object is the current length of the object. For example, if the value of the position header specified in the first AppendObject request is 0 and the value of Content-Length is 65536, the value of the position header in the second AppendObject request must be set to 65536.

  • If the value of the position header in an AppendObject request is 0 and no object that has the same name as the appendable object exists, you can specify headers, such as x-oss-server-side-encryption, in the AppendObject request in the same manner as that in a PutObject request. If you specify a valid value for the x-oss-server-side-encryption header in an AppendObject request, the x-oss-server-side-encryption header is included in the response to the request. If you want to modify metadata, you can call the CopyObject operation.

  • If you call an AppendObject request in which the value of the position header is valid to append an object whose size is 0 KB to an existing appendable object, the status of the appendable object remains unchanged.

Cache-control

String

No

no-cache

The web page caching behavior of the object. For more information, visit RFC 2616.

By default, this parameter is left empty.

Content-Disposition

String

No

attachment;filename=oss_download.jpg

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

By default, this parameter is left empty.

Content-Encoding

String

No

utf-8

The encoding format of the object. For more information, visit RFC 2616.

By default, this parameter is left empty.

Content-MD5

String

No

ohhnqLBJFiKkPSBO1eNaUA==

The MD5 hash 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 Base64-encode the number.

By default, this parameter is left empty.

Limits: none.

Expires

GMT

No

Wed, 08 Jul 2015 16:57:01 GMT

The expiration time. For more information, visit RFC 2616.

By default, this parameter is left empty.

x-oss-server-side-encryption

String

No

AES256

The method that is used to encrypt objects on the OSS server.

Valid values:

  • AES256: Keys managed by OSS are used for encryption and decryption (SSE-OSS).

  • KMS: CMKs managed by Key Management Service (KMS) are used for encryption and decryption.

x-oss-object-acl

String

No

private

The access control list (ACL) of the object.

Valid values:

  • default (default): The ACL of the object is the same as that of the bucket in which the object is stored.

  • private: The ACL of the object is private. Only the owner of the object and authorized users have the read and write permissions on the object.

  • public-read: The ACL of the object is public-read. Only the owner of the object and authorized users have the read and write permissions on the object. Other users have only the read permissions on the object. Exercise caution when you set the ACL of the object to this value.

  • public-read-write: The ACL of the object is public-read-write. All users have the read and write permissions on the object. Exercise caution when you set the ACL of the object to this value.

For more information, see Object ACLs.

x-oss-storage-class

String

No

Standard

The storage class of the object.

If you specify the x-oss-storage-class header when you upload an object, the storage class of the uploaded object is the specified value regardless of the storage class of the bucket to which the object is uploaded. For example, if you set the x-oss-storage-class header to Standard when you upload an object to an Infrequent Access (IA) bucket, the object is stored as a Standard object.

Valid values:

  • Standard

  • IA

  • Archive

For more information about storage classes, see Overview.

Important
  • This header takes effect only the first time you call the AppendObject operation on an object.

  • The storage class of appendable objects cannot be converted to Cold Archive or Deep Cold Archive.

x-oss-meta-*

String

No

x-oss-meta-location

The parameters that can be added to an AppendObject request when you create an appendable object. The parameters must contain the x-oss-meta- prefix. These parameters cannot be included in the requests when you append objects to an existing appendable object. Parameters that contain the x-oss-meta-* prefix are considered the metadata of the object.

You can specify multiple parameters that contain the x-oss-meta- prefix for an object. The total size of the metadata cannot exceed 8 KB.

The names of the parameters that contain the x-oss-meta- prefix 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 are specified for the object in key-value pair. You can specify multiple tags for an object. Example: TagA=A&TagB=B.

Important
  • This header takes effect only the first time you call the AppendObject operation on an object.

  • The tag key and tag value must be URL-encoded. When you specify a tag for an object, only the tag key is required and the tag value is optional. Example: TagA&TagB=B.

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 from which the next append operation starts, which is the length of the object.

This header is returned when an AppendObject request is successful, or when HTTP status code 409 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 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 one of 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")

Relationship with other operations

Operation

Relationship

PutObject

If you call the PutObject operation on an existing appendable object, the appendable object is converted to a normal object.

HeadObject

If you call the HeadObject operation on an existing appendable object, the x-oss-next-append-position, x-oss-hash-crc64ecma, and x-oss-object-type headers are returned. The x-oss-object-type value of the appendable object is Appendable.

GetBucket (ListObjects)

In the response to a GetBucket request, the x-oss-object-type value of an appendable object is Appendable.

Examples

  • Sample request

    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 qn6q**************:77Dv****************  
    [1717 bytes of object data]

    Sample success response

    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 request for a versioned bucket

    If you call the AppendObject operation on an object in a bucket for which versioning is enabled, the x-oss-version-id header is included in the response and its value is the current version ID of the object.

    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 qn6q**************:77Dv****************

    Sample success response

    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: CAEQGhiBgIC_k6aV5RgiIGI3YTY2ZmMzYWJlMzQ3YjM4YTljOTk5YjUyZGF****
    x-oss-hash-crc64ecma: 3231342946509354535
    x-oss-next-append-position: 47
    x-oss-request-id: 5CAC18A5B7AEADE01700****

SDK

You can use OSS SDKs for the following programming languages to call ListBuckets (GetService):

Error codes

Error code

HTTP status code

Description

ObjectNotAppendable

409

You called the AppendObject operation on a non-appendable object.

PositionNotEqualToLength

409

  • The value of the position header does not match the current object length.

    You can obtain the position from which the next AppendObject operation starts based on the value of 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 the x-oss-next-append-position header to the value of the position header in a request, the request may still fail because the value is not updated immediately.

  • The request is successful when the value of the position header is 0 and the length of an appendable object with the same name is 0 or an appendable 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 value of a parameter, such as x-oss-storage-class or x-oss-object-acl, is invalid.

FileImmutable

409

The data that you want to delete or modify is protected by a retention policy.

KmsServiceNotEnabled

403

KMS is specified as the server-side encryption method but KMS is not activated in the console.