Function Description

This interface is used to append data to objects. Objects created via the AppendObject interface are of the Appendable Object type, while objects uploaded through PutObject and multipart upload are of the Normal Object type.

Instructions for Use

The object size limitations when using the AppendObject interface are as follows:

The size of the object after appending must not exceed 5GB.

When a PutObject operation is performed on an object created by AppendObject, the object is overwritten and its type changes from Appendable to Normal. In contrast, objects uploaded via PutObject do not support append write operations.

When the bucket is in multi-version enabled state, only append uploads of the current version object are permitted, and no historical versions will be generated for this object. When using the PutObject operation to overwrite an object or the DeleteObject operation to delete an object, a historical version of the object is generated; however, the historical version cannot be further appended to.

The AppendObject interface does not support server-side encryption.

If your object type is Appendable Object, it is recommended that you do not perform Append operations concurrently, as this may result in execution failure.

Request syntax

Request parameters and headers

For the public request message header used by this request, please refer to Common parameters.

Name	Location	Type	Required	Sample value	Description
append	Query	String	Yes		A special identifier representing an AppendObject request.
offset	Query	Integer	Yes	0	Specify where to append. After a successful append, the x-tos-next-append-offset header field in the response message will include the offset for the next append operation.
Content-Length	Header	Integer	Yes	100	The size of the message body.
Content-Type	Header	String	No	text/plain	Object Type. Valid when the offset parameter is 0.
x-tos-acl	Header	String	No	private	Effective permission settings for object access include: private: private; not public. public-read: Public Read. public-read-write: Public read/write access. authenticated-read: Read access for authenticated users. bucket-owner-read: Bucket Owner Read. bucket-owner-full-control: Full control for bucket owner. bucket-owner-entrusted: Controlled by the bucket policy; the bucket owner has full permissions. default: Inherit the bucket ACL, meaning the object's ACL policy is consistent with the bucket ACL policy.
x-tos-grant-full-control	Header	String	No	id=123,id=456	When creating an object, use this header field to grant users permissions for object read (READ), read ACP (READ ACP), and write ACP (WRITE ACP). Format: id=account1,id=account2.
x-tos-grant-read	Header	String	No	id=123,id=456	Permission that allows authorized users to read objects and object metadata. Format: id=account1,id=account2.
x-tos-grant-read-acp	Header	String	No	id=123,id=456	Allow authorized users to read the object ACL. Format: id=account1,id=account2.
x-tos-grant-write-acp	Header	String	No	id=123,id=456	Authorized users are permitted to modify the object ACL. Format: id=account1,id=account2.
x-tos-meta-*	Header	String	No	x-tos-meta-key: value	When creating an object, you can include headers that begin with x-tos-meta- in the HTTP request to add custom metadata, enabling customized management of the object. When a user retrieves this object or queries its metadata, any custom metadata added will appear in the header of the returned message.
x-tos-website-redirect-location	Header	String	No	/anotherObjectName	When a bucket is configured with Website settings, requests to access this object can be redirected to another object within the bucket or to an external URL. TOS extracts this value from the header and stores it in the object's metadata.
x-tos-storage-class	Header	String	No	STANDARD	Set the storage type of the target object. If not specified, the storage type of the target object will be consistent with the default storage type of the bucket in which it resides. The possible values are explained as follows: STANDARD: Standard Storage. tip When uploading objects using the AppendObject interface, you can only set the object to use standard storage. If you do not set this parameter and the default storage type of the bucket is not Standard Storage, append write objects will fail.
x-tos-traffic-limit	Header	String	No	819200	TOS provides single-link speed limiting functionality, enabling traffic control during operations such as file upload and download to ensure network bandwidth for other applications. The explanation of values is as follows: Value range: 245760–838860800, unit: bit/s This parameter must not be present in both Header and Query simultaneously.
x-tos-traffic-limit	Query	String	No	819200	TOS provides single-link speed limiting, enabling traffic control during file upload and download operations to ensure network bandwidth for other applications. The values are explained as follows: Value range: 245760–838860800, unit: bit/s This parameter must not exist simultaneously in Header and Query.
x-tos-object-expires	Header	String	No	3	Set the expiration time for the object. After expiration, TOS will automatically delete the object. The unit is days, and only positive integers are supported. The expiration time is calculated from the object's Last-Modified time. After the expiration time is reached, the deletion task will be executed at midnight. For example, set the value of the x-tos-object-expires parameter to3, if the object's Last-Modified time is 2024-09-26 12:00, the object will expire at 2024-09-30 00:00. tip Only the first append write operation on an object supports setting x-tos-object-expires; setting x-tos-object-expires in subsequent append write operations is invalid. The priority of object expiration time is higher than that of lifecycle deletion rules. For example, if the object expiration time is set to 5 days and the lifecycle rule specifies deletion after 3 days, the object will ultimately be deleted according to the expiration time, that is, after 5 days. TOS supports querying the expiration time of objects via GetObject or HeadObject.
x-tos-object-lock-mode	Header	String	No	COMPLIANCE	The mode of the retention policy can only be COMPLIANCE, which indicates compliance mode. tip To set a retention policy for an object, you must first enable the retention policy feature. For detailed information, see PutBucketObjectLockConfiguration.
x-tos-object-lock-retain-until-date	Header	String	No	2025-01-01T00:00:00Z	The lock expiration date of the object is the date during which the object cannot be deleted or overwritten. Follow the ISO 8601 time format. tip x-tos-object-lock-retain-until-date parameter must be used together with the x-tos-object-lock-mode parameter.

Request body elements

There are no request message elements in this request; the request body contains the data content for the append write object.

Response headers

Please refer to Common parameters for the public response message header returned by this request.

Name	Type	Sample Value	Description
x-tos-next-append-offset	Integer	100	Offset for the next append write to the object.
x-tos-hash-crc64ecma	Integer	6186290338114851376	Represents the 64-bit CRC value of the object. This 64-bit CRC is calculated according to the ECMA-182 standard. tip If objects created by append write uploads were created before the TOS server supports 64-bit CRC validation, this message header will not appear in the response message.
x-tos-qos-delay-time	Integer	10	This header field indicates the duration for which the request is subject to flow control, measured in milliseconds (ms). Upload requests return the exact duration of throttling; copy requests or download requests return an estimated throttling duration based on the degree of throttling and file size.

Response body elements

There is no message element in this request response.

Sample request

Sample response

Torch Object Storage