Appending an Object_Object Storage Service

Functions

The AppendObject operation adds data to the end of an object in a specified bucket. If there is no namesake object in the bucket, a new object is created.

The object created using the AppendObject operation is an appendable object, and the object uploaded using the PUT operation is a normal object.

Uploaded objects must be stored in buckets. Only the users who have the write permission to a bucket can upload objects to the bucket. The name of each object in the same bucket must be unique.

To ensure that data is not damaged during transmission, you can add the Content-MD5 parameter to the request header. After receiving the data, OBS performs MD5 verification for the data. If the data is inconsistent, OBS returns an error message.

This operation allows you to specify the x-obs-acl parameter when creating an appendable object and set the permission control policy for the object.

This operation supports server-side encryption.

Relationship with Other Operations

If you perform the PUT operation on an existing appendable object, the appendable object is overwritten by the newly uploaded object and the object type changes to normal. If you perform the other way around, an error occurs.
An appendable object will be changed to a normal object after being copied. An appendable object cannot be copied and saved as an appendable object.

WORM

If a bucket has WORM enabled, an append operation on this bucket will fail, with a 403 error returned.

Constraints

The last modification time of the object is updated each time an appending upload is performed.
If the SSE-C encryption mode is used on the server side, the appending upload is the same as the initialization segment. In this case, the request headers such as x-obs-server-side-encryption must be carried.
For the server-side encryption (SSE-KMS), the request header such as x-obs-server-side-encryption is specified only when the file is uploaded for the first time and no object with the same name exists in the bucket.
The length of each appended upload cannot exceed the upper limit (5 GB) of the object length.
The maximum number of append-only writes for each appendable object is 10,000.
If the object storage class is COLD (Archive) or DEEP_ARCHIVE (Deep Archive), this API cannot be called.
If cross-region replication is configured for a bucket, this API operation cannot be used.
Object appending is not available for parallel file systems.

Request Syntax

POST /ObjectName?append&position=Position HTTP/1.1 
Host: bucketname.obs.region.myhuaweicloud.com 
Content-Type: application/xml 
Content-Length: length
Authorization: authorization
Date: date
<Optional Additional Header> 
<object Content>

Request Parameters

The request needs to specify parameters in the message, indicating that the request is for append upload and the upload location must be specified. For details about the parameters, see Table 1.

**Table 1** Request parameters
Parameter	Type	Mandatory (Yes/No)	Description
append	String	Yes	Explanation: Indicates that the object is uploaded in an append manner. Restrictions: None Value range: None Default value: None
position	Integer	Yes	Explanation: Location for the append upload Restrictions: Max. 5 GB Value range: For an object to be appended, the value of position must be set to 0 when the object is uploaded for the first time. The value of position will be carried in the x-obs-next-append-position header of the response returned by the server when the object is successfully uploaded next time. Default value: None

Request Headers

This request uses common headers. For details, see Table 3.

Table 2 describes the additional message headers that a request can use when position=0.

This request can use the server-side encryption request headers. For details, see Table 3.

**Table 2** Request headers
Header	Type	Mandatory (Yes/No)	Description
x-obs-acl	String	No	Explanation: When first calling this API, you can use this parameter to set a pre-defined object ACL. Restrictions: Use character strings. Value range: private public-read public-read-write For details about each policy, see the "Configuring an ACL Using Header Fields" section in ACLs. Default value: private
x-obs-grant-read	String	No	Explanation: When first calling this API, you can use this header to grant all users in a domain the permissions to read the object and obtain the object metadata. Example: x-obs-grant-read: id=domainID Restrictions: If multiple tenants are authorized, separate them with commas (,). Value range: None Default value: None
x-obs-grant-read-acp	String	No	Explanation: When first calling this API, you can use this header to grant all users in a domain the permissions to obtain the object ACL. Example: x-obs-grant-read-acp: id=domainID Restrictions: If multiple tenants are authorized, separate them with commas (,). Value range: None Default value: None
x-obs-grant-write-acp	String	No	Explanation: When first calling this API, you can use this header to grant all users in a domain the permissions to write the object ACL. Example: x-obs-grant-write-acp: id=domainID Restrictions: If multiple tenants are authorized, separate them with commas (,). Value range: None Default value: None
x-obs-grant-full-control	String	No	Explanation: When first calling this API, you can use this header to grant all users in a domain the permissions to read the object, obtain the object metadata and ACL, and write the object ACL. Example: x-obs-grant-full-control: id=domainID Restrictions: If multiple tenants are authorized, separate them with commas (,). Value range: None Default value: None
x-obs-storage-class	String	No	Explanation: For the first write, you can use this header field to configure the object storage class. Example: x-obs-storage-class:STANDARD Restrictions: Archive and Deep Archive objects do not support append uploads. The value is case-sensitive. Value range: STANDARD WARM Default value: If you do not use this header, the object storage class is the default storage class of the bucket.
x-obs-meta-*	String	No	Explanation: For the first write, you can use a header starting with x-obs-meta- to define object metadata in an HTTP request. Custom metadata will be returned in the response header when you retrieve or query the metadata of the object. Example: x-obs-meta-test:test metadata Restrictions: This parameter can only be passed in HTTP request headers and cannot exceed 8 KB. Value range: None Default value: None
x-obs-persistent-headers	String	No	Explanation: For the first appending, you can add the x-obs-persistent-headers header in an HTTP request to specify one or more user-defined response headers. User-defined response headers will be returned in the response header when you retrieve the object or query the object metadata. Format: x-obs-persistent-headers: key1:base64_encode(value1),key2:base64_encode(value2)... Note: Items, such as key1 and key2, are user-defined headers. If they contain non-ASCII or unrecognizable characters, they can be encoded using URL or Base64. The server processes these headers as character strings, but does not decode them. Items, such as value1 and value2 are the values of the corresponding headers. base64_encode indicates that the value is encoded using Base64. A user-defined header and its Base64-encoded value are connected using a colon (:) to form a key-value pair. All key-value pairs are separated with a comma (,) and are placed in the x-obs-persistent-headers header. The server then decodes the uploaded value. Example: x-obs-persistent-headers: key1:dmFsdWUx,key2:dmFsdWUy The returned header for downloading the object or obtaining the object metadata is key1:value1 or key2:value2 respectively. Restrictions: Response headers customized in this way cannot be prefixed with x-obs-. For example, you should use key1 instead of x-obs-key1. Standard HTTP headers, such as host, content-md5, origin, range, and Content-Disposition, cannot be specified as user-defined headers. The total length of this header and the custom metadata cannot exceed 8 KB. If multiple values are passed for the same key, they are separated by commas (,) and returned all at once for that key. If the decoded value contains non-US-ASCII or unrecognizable characters, the server processes the value as a string and encapsulates it using ?UTF-8?B?<(str)>?=, but does not decode the value. For instance, value key1:abbc will be returned as key1: =?UTF-8?B?abbc?= in the response. The values cannot contain spaces, equal signs (=), commas (,), semicolons (;), colons (:), or periods (.). If such characters are required, use URL or Base64 encoding. Value range: None Default value: None
x-obs-website-redirect-location	String	No	Explanation: If a bucket is configured with the static website hosting function, it will redirect requests for this object to another object in the same bucket or to an external URL. OBS stores the value of this header in the object metadata. Restrictions: The value must start with a slash (/), http://, or https:// and cannot exceed 2K. Value range: None Default value: None
x-obs-expires	Integer	No	Explanation: Specifies when an object expires. It is measured in days. Once the object expires, it is automatically deleted. (The calculation starts from when the object was last modified). Example: x-obs-expires:3 Restrictions: The value must be greater than the number of days that have passed since the object was created. For example, if the object was uploaded 10 days ago, you must specify a value greater than 10. Value range: The value is an integer greater than 0. Default value: None

**Table 3** Server encryption request headers
Header	Type	Mandatory (Yes/No)	Description
x-obs-server-side-encryption	String	No. This header is required when SSE-KMS is used.	Explanation: Indicates that SSE-KMS is used. Example: x-obs-server-side-encryption:kms Restrictions: None Value range: kms AES256 Default value: None
x-obs-server-side-encryption-kms-key-id	String	No	Explanation: ID of a specified key used for SSE-KMS encryption. For details about how to obtain a key ID, see Viewing a Key. Restrictions: This header can only be used when you specify kms for the x-obs-server-side-encryption header. Default value: If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.
x-obs-server-side-encryption-customer-algorithm	String	No. This header is required when SSE-C is used.	Explanation: Indicates the encryption algorithm used when SSE-C is used. Example: x-obs-server-side-encryption-customer-algorithm:AES256 Restrictions: This header must be used together with x-obs-server-side-encryption-customer-key and x-obs-server-side-encryption-customer-key-MD5. Value range: AES256 Default value: None
x-obs-server-side-encryption-customer-key	String	No. This header is required when SSE-C is used.	Explanation: Indicates the encryption key used when SSE-C is used. Example: x-obs-server-side-encryption-customer-key:K7QkYpBkM5+hca27fsNkUnNVaobncnLht/rCB2o/9Cw= Restrictions: This header is a Base64-encoded 256-bit key and must be used together with x-obs-server-side-encryption-customer-algorithm and x-obs-server-side-encryption-customer-key-MD5. Value range: None Default value: None
x-obs-server-side-encryption-customer-key-MD5	String	No. This header is required when SSE-C is used.	Explanation: Indicates the MD5 value of the encryption key when SSE-C is used. The MD5 value is used to check whether any error occurs during the transmission of the key. Example: x-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ== Restrictions: This header is a Base64-encoded 128-bit MD5 value and must be used together with x-obs-server-side-encryption-customer-algorithm and x-obs-server-side-encryption-customer-key. Value range: Base64-encoded MD5 value of the key ID. Default value: None

Request Elements

This request involves no elements.

Response Syntax

    
         HTTP/1.1 status_code
Date: date
ETag: etag
Content-Length: length

Response Headers

The response to the request uses common headers. For details, see Table 1.

The ETag returns the hash value of the data to be uploaded, not the hash value of the entire object.

**Table 4** Additional response headers
Header	Type	Description
x-obs-version-id	String	Explanation: Version ID of the object. If versioning is enabled for the bucket, the object version ID will be returned. Restrictions: None Value range: None Default value: None
x-obs-server-side-encryption	String	Explanation: The encryption method used by the server. Example: x-obs-server-side-encryption:kms Restrictions: This header is included in a response if SSE-KMS is used. Value range: kms AES256 Default value: None
x-obs-server-side-encryption-kms-key-id	String	Explanation: ID of a specified key used for SSE-KMS encryption. For details about how to obtain a key ID, see Viewing a Key. Restrictions: This header can only be used when you specify kms for the x-obs-server-side-encryption header. Default value: If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.
x-obs-server-side-encryption-customer-algorithm	String	Explanation: Indicates the encryption algorithm. This header is included in a response when SSE-C is used. Example: x-obs-server-side-encryption-customer-algorithm:AES256 Restrictions: None Value range: AES256 Default value: None
x-obs-server-side-encryption-customer-key-MD5	String	Explanation: Indicates the MD5 value of the key for encrypting objects. This header is included in a response when SSE-C is used. Example: x-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ== Restrictions: None Value range: Base64-encoded MD5 value of the key ID. Default value: None
x-obs-next-append-position	Integer	Explanation: Indicates the position to be provided for the next request. Restrictions: This header is returned when the object is an Appendable object. Value range: None Default value: None

Response Elements

This response contains no elements.

Error Responses

If the object length exceeds the limit due to the appending upload, OBS returns 400 Bad Request and the error code is AppendTooLarge.
If the value of position is different from the original length of the current object, OBS returns 409 Conflict and the error code is PositionNotEqualToLength.
If an object with the same object name exists in a bucket and the object type is not Appendable, OBS returns 409 Conflict and the error code is ObjectNotAppendable.
If the number of write times of an object exceeds 10000, OBS returns 409 Conflict and the error code is ObjectNotAppendable.
If the object storage class is COLD (Archive) or DEEP_ARCHIVE (Deep Archive), this API cannot be called. If you still call this API, OBS returns 409 Conflict with the error code of ObjectNotAppendable.
If cross-region replication is configured for a bucket, this API operation cannot be used. Otherwise, OBS returns 400 Bad Request and the error code is OperationNotSupported.

Other errors are included in Table 2.

Sample Request: Append Upload

POST /object?append&position=0 HTTP/1.1
Host: examplebucket.obs.region.myhuaweicloud.com
Expires: Wed, 27 Jun 2015 13:45:50 GMT
Date: Wed, 08 Jul 2015 06:57:01 GMT
Content-Type: image/jpg
Content-Length: 1458
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:kZoYNv66bsmc10+dcGKw5x2PRrk=

[1458 bytes of object data]

Sample Response: Append Upload

    
         HTTP/1.1 200 OK
Date: Wed, 27 Jun 2015 13:45:50 GMT
ETag: "d41d8cd98f00b204e9800998ecf8427e"
Content-Length: 0  
Server: OBS
x-obs-request-id: 8DF400000163D3F0FD2A03D2D30B0542
x-obs-id-2: 32AAAUgAIAABAAAQAAEAABAAAQAAEAABCTjCqTmsA1XRpIrmrJdvcEWvZyjbztdd 
x-obs-next-append-position: 1458

Sample Request: Append Upload (with redirect and a User-Defined Header Used)

The bucket examplebucket exists but the object obj001 does not exist. Create an object by making the API call for the append operation. Set the redirection header field as follows: "x-obs-website-redirect-location":"http://www.example.com/", and set the user-defined header field to: "x-obs-meta-redirect":"redirect". The request is as follows:

POST /obj001?append&position=0 HTTP/1.1
Host: examplebucket.obs.region.myhuaweicloud.com
Expires: Wed, 27 Jun 2015 13:45:50 GMT
Date: Wed, 08 Jul 2015 06:57:01 GMT
x-obs-website-redirect-location: http://www.example.com/
x-obs-meta-redirect: redirect
Content-Length: 6
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:kZoYNv66bsmc10+dcGKw5x2PRrk=

[6 bytes of object data]

Sample Response: Append Upload (with redirect and a User-Defined Header Used)

    
         HTTP/1.1 200 OK
Date: Wed, 27 Jun 2015 13:45:50 GMT
ETag: "9516dfb15f51c7ee19a4d46b8c0dbe1d"
Content-Length: 0  
Server: OBS
x-obs-request-id: 5DEB00000164A3150AC36F8F0C120D50
x-obs-id-2: 32AAAUgAIAABAAAQAAEAABAAAQAAEAABCSrVlTYwsA4p9GEW+LYqotSl5BYDxHfT 
x-obs-next-append-position: 6

Sample Request: Appending Data to an Object in a Versioning-enabled Bucket

POST /object01?append&position=0 HTTP/1.1
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:iqSPeUBl66PwXDApxjRKk6hlcN4=
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.myhuaweicloud.com
Date: WED, 01 Jul 2015 02:37:22 GMT
Content-Type: application/octet-stream
 
[1458 bytes of object data]

Sample Response: Appending Data to an Object in a Versioning-enabled Bucket

x-obs-id-2: 32AAAQAAEAABSAAgAAEAABAAAQAAEAABCSZbDadL1f7fYU44bvRLvc0l6D10+wzG
x-obs-request-id: 0000018A2BCBB3ABD3046B99E3ED2E30
Server: OBS
Content-Length: 0
Date: WED, 01 Jul 2015 02:37:22 GMT
x-obs-next-append-position: 4
ETag: "56468d5607a5aaf1604ff5e15593b003"
x-obs-version-id: G001118A6803675AFFFFD3043F7F91D0

Appending an Object