Appending an Object

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.

Relationship with Other Operations

1. 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.
2. 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.

Constraints

1. The last modification time of the object is updated each time an appending upload is performed.
2. The length of each appended upload cannot exceed the upper limit (5 GB) of the object length.
3. The maximum number of append-only writes for each appendable object is 10,000.
4. If cross-region replication is configured for a bucket, this API operation cannot be used.
5. Object appending is not available for parallel file systems.

Request Syntax

POST /ObjectName?append&position=Position HTTP/1.1 
Host: bucketname.obs.region.example.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 appending upload and the upload location must be specified. For details about the parameters, see Table 1.

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 the position=0 parameter is requested.

Request Elements

This request involves no elements.

Response Syntax

1
2
3
4

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.

Response Elements

This response contains no elements.

Error Responses

1. If the object length exceeds the limit due to the appending upload, OBS returns 400 Bad Request and the error code is AppendTooLarge.
2. 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.
3. 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.
4. If the number of write times of an object exceeds 10000, OBS returns 409 Conflict and the error code is ObjectNotAppendable.
5. 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.example.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

1
2
3
4
5
6
7
8

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.example.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)

1
2
3
4
5
6
7
8

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