All Products
Search

This Product

    Object Storage Service:AppendObject

    Document Center

    Object Storage Service:AppendObject

    Last Updated:Dec 06, 2025

    You can call the AppendObject operation to upload an object by appending data. Objects created using the AppendObject operation are Appendable objects. Objects uploaded using the PutObject operation are Normal objects.

    Versioning

    When you perform operations on an Appendable object in a bucket that has versioning enabled or suspended, note the following items:

    • You can append data only to the current version of an object if it is an Appendable object. OSS does not create previous versions for this Appendable object.

      If you perform a PutObject or DeleteObject operation on the current version of an Appendable object, OSS saves the Appendable object as a previous version. However, you can no longer append data to this object.

    • You cannot perform an AppendObject operation on non-Appendable objects, such as Normal objects or delete markers.

    • You can create a new Appendable version only if the object does not exist or the latest version is a delete marker. To do this, call AppendObject and set the position parameter to 0.

    Limits

    • The final size of an object created using AppendObject cannot exceed 5 GB.

    • You cannot use the AppendObject operation on objects that are protected by a retention policy.

    • You cannot specify a CMK ID to enable server-side encryption with Key Management Service (KMS) for Appendable objects.

    • The download performance of Appendable objects is much lower than that of Normal or Multipart objects. You must evaluate this based on your business scenario.

    Permissions

    By default, an Alibaba Cloud account has full permissions. RAM users or RAM roles under an Alibaba Cloud account do not have any permissions by default. The Alibaba Cloud account or account administrator must grant operation permissions through RAM Policy or Bucket policies.

    API

    Action

    Definition

    AppendObject

    oss:PutObject

    You can call this operation to upload an object by appending the object to an existing object.

    oss:PutObjectTagging

    When uploading an object by appending the object to an existing object, if you specify object tags through x-oss-tagging, this permission is required.

    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

    Name

    Type

    Required

    Example

    Description

    Cache-control

    string

    No

    no-cache

    Specifies the web page caching behavior for the object. For more information, see RFC2616.

    Default: none

    Content-Disposition

    string

    No

    attachment;filename=oss_download.jpg

    Specifies the name of the object when it is downloaded. For more information, see RFC2616.

    Default: none

    Content-MD5

    string

    No

    ohhnqLBJFiKkPSBO1eNaUA==

    The Content-MD5 header is a value generated by the MD5 algorithm. This header is used to check whether the message content is the same as the content that was sent.

    To obtain the Content-MD5 value, run the MD5 algorithm on the message body (excluding headers) to get a 128-bit number, and then Base64-encode the number.

    Default: none

    Constraints: none

    Expires

    string

    No

    Wed, 08 Jul 2015 16:57:01 GMT

    The expiration time. For more information, see RFC2616.

    Default: none

    x-oss-server-side-encryption

    string

    No

    AES256

    Specifies the server-side encryption method.

    Valid values:

    • AES256: uses keys that are fully managed by OSS for encryption and decryption (SSE-OSS).

    • KMS: uses keys that are managed by KMS for encryption and decryption.

    x-oss-object-acl

    string

    No

    private

    Specifies the access permissions of the object.

    Valid values:

    • default (default): The object inherits the access permissions of the bucket.

    • private: The object is a private resource. Only the object owner and authorized users have read and write permissions on the object. Other users cannot access the object.

    • public-read: The object is a public-read resource. Only the object owner and authorized users have read and write permissions on the object. Other users have only read permissions. Use this permission with caution.

    • public-read-write: The object is a public-read-write resource. All users have read and write permissions on the object. Use this permission with caution.

    For more information about access permissions, see Object ACL.

    x-oss-storage-class

    string

    No

    Standard

    Specifies the storage class of the object.

    For a bucket of any storage class, if you specify this parameter when you upload an object, the uploaded object is stored in the specified storage class. For example, if you set x-oss-storage-class to Standard when you upload an object to an Infrequent Access bucket, the object is stored as Standard.

    Valid values:

    • Standard: Standard

    • IA: Infrequent Access

    • Archive: Archive Storage

    For more information about storage classes, see Storage classes.

    Important

    • This request header takes effect only for the first append operation. It does not take effect for subsequent append operations.

    • Objects of the Appendable type cannot be converted to the Cold Archive or Deep Cold Archive storage class in any way.

    x-oss-meta-*

    string

    No

    x-oss-meta-location

    You can add x-oss-meta-* when you create an Appendable object. You cannot include this parameter in subsequent append operations. If you configure a parameter that starts with the x-oss-meta-* prefix, the parameter is treated as metadata.

    Metadata size limit: An object can have multiple metadata records, but the total size of all metadata cannot exceed 8 KB.

    Metadata naming conventions: Metadata names can contain hyphens (-), digits, and lowercase letters (a-z). Uppercase letters are converted to lowercase letters. Other characters, including underscores (_), are not supported.

    x-oss-tagging

    string

    No

    TagA=A

    Specifies the tags of the object in a key-value format. You can specify multiple tags at the same time, such as TagA=A&TagB=B.

    Important

    • This request header takes effect only for the first append operation. It does not take effect for subsequent append operations.

    • The key and value must be URL-encoded. The key is required, but the value is optional. For example, you can set the object tags to TagA&TagB=B.

    For more information about other common request headers for this operation, see Common request headers.

    Request parameters

    Important

    The append and position parameters are part of the CanonicalizedResource and must be included in the signature.

    Name

    Type

    Required

    Example

    Description

    append

    string

    Yes

    Not applicable

    Specifies the AppendObject operation. Each AppendObject operation updates the last modified time of the object.

    position

    string

    Yes

    0

    Specifies the position from which to start appending data. After each successful operation, the x-oss-next-append-position response header indicates the position for the next append.

    The position for the first append operation must be 0. The position for a subsequent append operation is the current size of the object. For example, if the position for the first AppendObject request is 0 and the content-length is 65536, the position for the second AppendObject request must be 65536.

    • If the position is 0 and no object with the same name exists, the AppendObject request is similar to a PutObject request. This means you can set request headers such as x-oss-server-side-encryption. If you add a valid x-oss-server-side-encryption header, subsequent AppendObject responses also include the x-oss-server-side-encryption header. To modify the metadata later, use the CopyObject operation.

    • If the position is correct, appending content of size 0 to an existing Appendable object does not change the state of the object.

    Response headers

    Response header

    Type

    Example

    Description

    x-oss-next-append-position

    64-bit integer

    1717

    The position for the next request, which is the current size of the object.

    This header is returned when the AppendObject operation is successful or when a 409 error occurs because the position does not match the object size.

    x-oss-hash-crc64ecma

    64-bit integer

    3231342946509354535

    Indicates the 64-bit CRC value of the object. This 64-bit CRC is calculated based on the CRC-64/XZ standard.

    For more information about other common response headers for this operation, see Common response headers.

    CRC-64 calculation methods

    You can use the following methods to perform the calculation:

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

    • Calculation using Python crcmod

      import crcmod
do_crc64 = crcmod.mkCrcFun(0x142F0E1EBA9EA3693, initCrc=0, xorOut=0xffffffffffffffff, rev=True)
print(do_crc64(b"123456789"))

    Relationship with other operations

    Other operation

    Relationship description

    PutObject

    If you perform a PutObject operation on an existing Appendable object, the Appendable object is overwritten by the new object, and its type is changed to Normal.

    HeadObject

    A HeadObject operation on an Appendable object returns x-oss-next-append-position, x-oss-hash-crc64ecma, and x-oss-object-type. The x-oss-object-type of an Appendable object is Appendable.

    GetBucket (ListObjects)

    In the response to a GetBucket request, the Type of an Appendable object is set to Appendable.

    Examples

    • 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 
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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-disposition;content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e  
[1717 bytes of object data]

      Response example

      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****

    • Versioning request example

      If versioning is enabled for a bucket, the response to an AppendObject request includes the x-oss-version-id response header. This header specifies the version ID of the current object version.

      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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

      Response example

      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****

    SDKs

    SDKs for this operation are available for the following languages:

    ossutil command line interface

    To perform this operation using ossutil, see the append-object command.

    Error codes

    Error code

    HTTP status code

    Description

    ObjectNotAppendable

    409

    An AppendObject operation is performed on a non-Appendable object.

    PositionNotEqualToLength

    409

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

      You can obtain the position for the next request from the x-oss-next-append-position response header and try the request again. Due to concurrency, the request may still fail with the PositionNotEqualToLength error even if you set the position to the value of x-oss-next-append-position.

    • If the position is 0, the request is successful if no Appendable object with the same name exists, or if an Appendable object with the same name has a length of 0. In other cases, the position is considered a mismatch with the object length, and this error code is returned.

    InvalidArgument

    400

    The values of parameters such as x-oss-storage-class and x-oss-object-acl are invalid.

    FileImmutable

    409

    If you try to delete or modify data in a bucket that is in a protected state, this error code is returned.

    KmsServiceNotEnabled

    403

    When you use the KMS encryption algorithm, Key Management Service (KMS) is not enabled in the console.