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.
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.
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, this API operation cannot be used.
- If cross-region replication is configured for a bucket, this API operation cannot be used.
Request Syntax
POST /ObjectName?append&position=Position HTTP/1.1 Host: bucketname.obs.cn-north-4.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 appending upload and the upload location must be specified. For details about the parameters, see Table 1.
|
Parameter |
Description |
Mandatory |
|---|---|---|
|
append |
Indicates that the file is uploaded in appending mode. Type: string |
Yes |
|
position |
Location for the appending upload 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. Type: integer |
Yes |
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.
This request can use the server-side encryption request header. For details, see Table 3.
|
Header |
Description |
Mandatory |
|---|---|---|
|
x-obs-acl |
For the first appending, the message header can be added to set the permission control policy of the object. The predefined common policies are used, including: private, public-read, public-read-write. For details about each policy, see the ACL configuration using head fields in ACL. Type: string Note: This header is a predefined policy expressed in a character string. |
No |
|
x-obs-grant-read |
For the first write, you can use this header field to authorize all users in the account the permission to read objects and obtain object metadata. Type: string |
No |
|
x-obs-grant-read-acp |
For the first write, you can use this header field to authorize all users in the account the permission to obtain object ACL information. Type: string |
No |
|
x-obs-grant-write-acp |
For the first write, you can use this header field to authorize all users in the account the permission to write object ACL. Type: string |
No |
|
x-obs-grant-full-control |
For the first write, you can use this header field to authorize all users in the account the permission to read objects, obtain object metadata, obtain object ACL information, and write object ACL. Type: string |
No |
|
x-obs-storage-class |
For the first write, you can use this header field to configure the object storage class. If you do not use this header, the object storage class is the default storage class of the bucket. Type: string Note: OBS provides three storage classes: Standard (STANDARD), Infrequent Access (WARM), and Archive (COLD). However, cold objects do not support appending upload. The configurable values are as follows: STANDARD and WARM, case sensitive. Example: x-obs-storage-class:STANDARD |
No |
|
x-obs-meta-* |
For the first write, you can use a header starting with x-obs-meta- to define object metadata in an HTTP request. User-defined metadata will be returned in the response header when you retrieve or query the metadata of the object. The size of the HTTP request excluding the request body must be equal to or smaller than 8 KB. Type: string Example: x-obs-meta-test:test metadata |
No |
|
x-obs-website-redirect-location |
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. Type: string There is no default value. Constraint: The value must be prefixed by a slash (/), http://, or https://. The length of the value cannot exceed 2 KB. |
No |
|
x-obs-expires |
Indicates the expiration time of an object, in days. An object will be automatically deleted once it expires (calculated from the last modification time of the object). Type: integer Example: x-obs-expires:3 |
No |
|
Header |
Description |
Mandatory |
|---|---|---|
|
x-obs-server-side-encryption |
Indicates that SSE-KMS is used. Type: string Example: x-obs-server-side-encryption:kms |
No. This header is required when SSE-KMS is used. |
|
x-obs-server-side-encryption-kms-key-id |
Indicates the master key ID. This header is used in SSE-KMS mode. If the customer does not provide the master key, the default master key will be used. Type: string The following two formats are supported: 1. regionID:domainID:key/key_id 2. key_id regionID is the ID of the region to which the key belongs. domainID is the account ID of the tenant to which the key belongs. key_id is the key ID created in DEW. Example: 1. x-obs-server-side-encryption-kms-key-id:cn-north-4:domainiddomainiddomainiddoma0001:key/4f1cd4de-ab64-4807-920a-47fc42e7f0d0 2. x-obs-server-side-encryption-kms-key-id:4f1cd4de-ab64-4807-920a-47fc42e7f0d0 |
No |
|
x-obs-server-side-encryption-customer-algorithm |
Indicates an encryption algorithm. The header is used in SSE-C mode. Type: string Example: x-obs-server-side-encryption-customer-algorithm:AES256 Constraints: This header must be used together with x-obs-server-side-encryption-customer-key and x-obs-server-side-encryption-customer-key-MD5. |
No. This header is required when SSE-C is used. |
|
x-obs-server-side-encryption-customer-key |
The key used to encrypt objects. The header is used in SSE-C mode. This key is used to encrypt objects. Type: string Example: x-obs-server-side-encryption-customer-key:K7QkYpBkM5+hcs27fsNkUnNVaobncnLht/rCB2o/9Cw= Constraints: 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. |
No. This header is required when SSE-C is used. |
|
x-obs-server-side-encryption-customer-key-MD5 |
Indicates the MD5 value of a key used to encrypt objects. The header is used in SSE-C mode. The MD5 value is used to check whether any error occurs during the transmission of the key. Type: string Example: x-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ== Constraints: This header is a 128-bit Base64-encoded string and must be used together with x-obs-server-side-encryption-customer-algorithm and x-obs-server-side-encryption-customer-key. |
No. This header is required when SSE-C is used. |
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.
|
Header |
Description |
|---|---|
|
x-obs-version-id |
Object version ID. If versioning is enabled for the bucket, the object version ID will be returned. Type: string |
|
x-obs-server-side-encryption |
This header is included in a response if SSE-KMS is used. Type: string Example: x-obs-server-side-encryption:kms |
|
x-obs-server-side-encryption-kms-key-id |
Indicates the master key ID. This header is included in a response if SSE-KMS is used. Type: string Format: regionID:domainID:key/key_id regionID is the ID of the region to which the key belongs. domainID is the account ID of the tenant to which the key belongs. key_id is the key ID used in this encryption. Example: x-obs-server-side-encryption-kms-key-id:cn-north-4:domainiddomainiddomainiddoma0001:key/4f1cd4de-ab64-4807-920a-47fc42e7f0d0 |
|
x-obs-server-side-encryption-customer-algorithm |
Indicates an encryption algorithm. This header is included in a response if SSE-C is used. Type: string Example: x-obs-server-side-encryption-customer-algorithm:AES256 |
|
x-obs-server-side-encryption-customer-key-MD5 |
Indicates the MD5 value of a key used to encrypt objects. This header is included in a response if SSE-C is used. Type: string Example: x-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ== |
|
x-obs-next-append-position |
Indicates the position to be provided for the next request. Type: Integer |
Response Elements
This response involves 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, this API operation cannot be used. Otherwise, OBS returns 409 Conflict and the error code is 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 1
Common append
POST /object?append&position=0 HTTP/1.1 Host: examplebucket.obs.cn-north-4.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 1
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 2
Append an object with the redirection and user-defined header fields.
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.cn-north-4.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 2
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
|
Last Article: Restoring Archive Objects
Next Article: Configuring Object ACL
Did this article solve your problem?
Thank you for your score！Your feedback would help us improve the website.