Uploading an Object - Append (SDK for Java)

Function

This API uploads a file or folder to an existing OBS bucket. These files can be texts, images, videos, or any other type of files.
The appendObject operation adds data to the end of an object in a specified bucket. If there is no object with the same names in the bucket, a new object is created. The latest modification time of the object is updated each time an upload is appended.
After an appendable upload is successful, you can call AppendObjectResult.getNextPosition or use the ObsClient.getObjectMetadata API to get the start position for next appending.

If you have any questions during development, post them on the Issues page of GitHub.

Restrictions

To upload an object, you must be the bucket owner or have the required permission (obs:object:PutObject in IAM or PutObject in a bucket policy). For details, see Introduction to OBS Access Control, IAM Custom Policies, and Configuring an Object Policy.
The mapping between OBS regions and endpoints must comply with what is listed in Regions and Endpoints.
The size of each append upload cannot exceed 5 GB.
A maximum of 10,000 appendable uploads can be performed on a single object. If you attempt to append more than 10,000 uploads to an object, OBS returns 409 Conflict with an error code ObjectNotAppendable.
If the object storage class is COLD (Archive), this API cannot be called.
If cross-region replication is configured for a bucket, this API cannot be called.
Objects cannot be appended in parallel file systems.
Objects uploaded using ObsClient.putObject, referred to as common objects, can overwrite objects uploaded using ObsClient.appendObject, referred to as appendable objects. Data cannot be appended to an appendable object anymore once the object has been overwritten by a common object.
You can append data to an existing object only if it is appendable. Otherwise, an exception will be reported (HTTP status code 409). To check whether an object is appendable, see Obtaining Object Metadata (SDK for Java).

Method

obsClient.appendObject(AppendObjectRequest request)

Request Parameters

**Table 1** List of request parameters
Parameter	Type	Mandatory (Yes/No)	Description
request	AppendObjectRequest	Yes	Explanation: Request parameters for an append upload. For details, see Table 2.

**Table 2** AppendObjectRequest
Parameter	Type	Mandatory (Yes/No)	Description
bucketName	String	Yes	Explanation: Bucket name. Restrictions: A bucket name must be unique across all accounts and regions. A bucket name: Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed. Cannot be formatted as an IP address. Cannot start or end with a hyphen (-) or period (.). Cannot contain two consecutive periods (..), for example, my..bucket. Cannot contain periods (.) and hyphens (-) adjacent to each other, for example, my-.bucket or my.-bucket. If you repeatedly create buckets of the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request. Default value: None
objectKey	String	Yes	Explanation: Object name. An object is uniquely identified by an object name in a bucket. An object name is a complete path that does not contain the bucket name. For example, if the address for accessing the object is examplebucket.obs.ap-southeast-1.myhuaweicloud.com/folder/test.txt, the object name is folder/test.txt. Value range: The value must contain 1 to 1,024 characters. Default value: None
metadata	ObjectMetadata	No	Explanation: Object metadata. For details, see Table 14. Default value: None
acl	AccessControlList	No	Explanation: An ACL that can be specified at bucket creation. You can use either a pre-defined or a user-defined ACL. For more information about ACLs, see ACLs. Value range: To use a pre-defined ACL, see Table 3 for the available policies. To use a user-defined ACL, see Table 15 to configure the required parameters. Default value: AccessControlList.REST_CANNED_PRIVATE
sseKmsHeader	SseKmsHeader	No	Explanation: Server-side encryption header. For details, see Table 9. Restrictions: If you use SSE-KMS encryption, the encryption header you configure, such as x-obs-server-side-encryption, only needs to be carried when the object is uploaded for the first time and no object with the same name exists in the bucket. Default value: None
sseCHeader	SseCHeader	No	Explanation: Server-side encryption header. For details, see Table 8. Restrictions: If you use SSE-C encryption, the encryption header you configure, such as x-obs-server-side-encryption, must be carried in each append upload. Default value: None
input	java.io.InputStream	No	Explanation: Data stream of the object to be uploaded. Default value: None
file	java.io.File	No	Explanation: File stream of the object to be uploaded. Default value: None
extensionPermissionMap	Map<ExtensionObjectPermissionEnum, Set<String>>	No	Explanation: A permission map for granting bucket ACL permissions to one or more accounts. ExtensionObjectPermissionEnum specifies the permissions to grant, and Set<String> describes the list of account IDs (indicated by domain_id) the granted permissions apply to. Value range: For details about the available permissions, see Table 7. To obtain the account ID, see How Do I Get My Account ID and User ID? Default value: None
expires	int	No	Explanation: Expiration time of the object. The calculation starts from the time when the object was last modified. Once the object expires, it is automatically deleted. Restrictions: This parameter can be configured when uploading an object or using the x-obs-expires header in a metadata API call. Value range: An integer greater than 0, in days. Default value: None
progressListener	ProgressListener	No	Explanation: Upload progress. For details, see Table 4.
position	long	Yes	Explanation: Position where the object data is appended. Restrictions: 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
encodeHeaders	boolean	No	Explanation: Whether to enable OBS to automatically encode request headers. Due to HTTP coding restrictions, only ASCII characters can be sent. If your request headers contain full-width characters, the SDK will URL encode these characters before sending the request. When you use a browser to access the object metadata, the browser automatically decodes the data. Value range: true: Encoding with SDK is enabled. false: Encoding with SDK is disabled. Default value: true

**Table 3** ACL
Constant	Description
AccessControlList.REST_CANNED_PRIVATE	Private read/write. A bucket or object can only be accessed by its owner.
AccessControlList.REST_CANNED_PUBLIC_READ	Public read. If this permission is granted on a bucket, anyone can read the object list, multipart uploads, bucket metadata, and object versions in the bucket. If this permission is granted on an object, anyone can read the content and metadata of the object.
AccessControlList.REST_CANNED_PUBLIC_READ_WRITE	Public read/write. If this permission is granted on a bucket, anyone can read the object list, multipart uploads, and bucket metadata, and can upload or delete objects, initiate multipart uploads, upload parts, assemble parts, copy parts, and abort multipart upload tasks. If this permission is granted on an object, anyone can read the content and metadata of the object.
AccessControlList.REST_CANNED_PUBLIC_READ_DELIVERED	Public read on a bucket as well as objects in the bucket. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, and bucket metadata, and can also read the content and metadata of the objects in the bucket. This permission cannot be granted on objects.
AccessControlList.REST_CANNED_PUBLIC_READ_WRITE_DELIVERED	Public read/write on a bucket as well as objects in the bucket. If this permission is granted on a bucket, anyone can read the object list, multipart uploads, and bucket metadata, and can upload or delete objects, initiate multipart upload tasks, upload parts, assemble parts, copy parts, and abort multipart uploads. They can also read the content and metadata of the objects in the bucket. This permission cannot be granted on objects.

**Table 4** ProgressListener
Method	Return Value Type	Mandatory (Yes/No)	Description
progressChanged	void	Yes	Explanation: Used for obtaining the upload progress. For details, see Table 5. Default value: None

**Table 5** progressChanged
Parameter	Type	Mandatory (Yes/No)	Description
status	ProgressStatus	Yes	Explanation: Progress data. For details, see Table 6. Default value: None

**Table 6** ProgressStatus
Method	Return Value Type	Description
getAverageSpeed()	double	Average transmission rate.
getInstantaneousSpeed()	double	Instantaneous transmission rate.
getTransferPercentage()	int	Transmission progress, in percentage.
getNewlyTransferredBytes()	long	Number of the newly transmitted bytes.
getTransferredBytes()	long	Number of bytes that have been transmitted.
getTotalBytes()	long	Number of the bytes to be transmitted.

**Table 7** ExtensionObjectPermissionEnum
Constant	Description
GRANT_READ	Grants a specific tenant the permissions to read the object and object metadata.
GRANT_READ_ACP	Grants a specific tenant the permissions to obtain the object ACL.
GRANT_WRITE_ACP	Grants a specific tenant the permissions to write the object ACL.
GRANT_FULL_CONTROL	Grants a specific tenant the permissions to read the content, metadata, and ACL of the object and write the object ACL.

**Table 8** SseCHeader
Parameter	Type	Mandatory (Yes/No)	Description
algorithm	ServerAlgorithm	Yes	Explanation: SSE-C is used for encrypting objects on the server side. Value range: AES256, indicating AES is used to encrypt the object in SSE-C. For details, see Table 10. Default value: None
sseAlgorithm	SSEAlgorithmEnum	No	Explanation: Encryption algorithm. Restrictions: Only AES256 is supported. Value range: See Table 12. Default value: None
sseCKey	byte[]	Yes	Explanation: Key used for encrypting the object when SSE-C is used, in byte[] format. Default value: None
sseCKeyBase64	String	No	Explanation: Base64-encoded key used for encrypting the object when SSE-C is used. Default value: None

**Table 9** SseKmsHeader
Parameter	Type	Mandatory (Yes/No)	Description
encryption	ServerEncryption	Yes	Explanation: SSE-KMS is used for server-side encryption. Objects are encrypted using SSE-KMS on the server side. Value range: kms. For details, see Table 11. Default value: None
sseAlgorithm	SSEAlgorithmEnum	No	Explanation: Encryption algorithm. Restrictions: Only KMS is supported. Value range: See Table 12. Default value: None
kmsKeyId	String	No	Explanation: ID of the KMS master key when SSE-KMS is used. Value range: Valid value formats are as follows: regionID:domainID:key/key_id key_id In the preceding formats: regionID indicates the ID of the region where the key is used. You can obtain it from Regions and Endpoints. domainID indicates the ID of the account that the key is for. To obtain it, see How Do I Get My Account ID and User ID? key_id indicates the ID of the key created on Data Encryption Workshop (DEW). To obtain it, see Viewing a CMK. Default value: If this parameter is not specified, the default master key will be used. If there is no such a default master key, OBS will create one and use it by default.

**Table 10** ServerAlgorithm
Constant	Default Value
AES256	AES256

**Table 11** ServerEncryption
Constant	Default Value
OBS_KMS	kms

**Table 12** SSEAlgorithmEnum
Constant	Default Value
KMS	kms
AES256	AES256

**Table 13** StorageClassEnum
Constant	Default Value	Description
STANDARD	STANDARD	Standard storage class
WARM	WARM	Infrequent Access storage class.
COLD	COLD	Archive storage class.

**Table 14** ObjectMetadata
Parameter	Type	Mandatory (Yes/No)	Description
contentLength	Long	No	Explanation: Object size. Restrictions: The object size in a single upload ranges from 0 to 5 GB. To upload files larger than 5 GB, multipart uploads should be used. Default value: If this parameter is not specified, the SDK automatically calculates the size of the file.
contentType	String	No	Explanation: MIME type of the object file. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data. Value range: See What Is Content-Type (MIME)? (Java SDK) Default value: If this parameter is not specified, the SDK determines the file type based on the suffix of the object name and assigns a value to the parameter. For example, if the suffix of the object name is .xml, the object is an application/xml file. If the suffix is .html, the object is a text/html file.
contentEncoding	String	No	Explanation: Content-Encoding header in the response. It specifies which encoding is applied to the object. Default value: None
contentDisposition	String	No	Explanation: Provides a default file name for the requested object. When the object with the default file name is being downloaded or accessed, the content is displayed as part of a web page in the browser or as an attachment in a download dialog box. Default value: None
cacheControl	String	No	Explanation: Cache-Control header in the response. It specifies the cache behavior of the web page when an object is downloaded. Default value: None
contentLanguage	String	No	Explanation: Language or language combination for visitors to customize and use. For details, see the definition of ContentLanguage in the HTTP protocol. Default value: None
expires	String	No	Explanation: The time a cached web page object expires. Restrictions: The time must be in the GMT format. Default value: None
contentMd5	String	No	Explanation: Base64-encoded MD5 value of the object data. It is provided for the OBS server to verify data integrity. The OBS server will compare this MD5 value with the MD5 value calculated based on the file data. If the two values are not the same, HTTP status code 400 is returned. Restrictions: The MD5 value of the file must be Base64 encoded. If the MD5 value is not specified, the OBS server will not verify the MD5 value of the file. Value range: Base64-encoded 128-bit MD5 value of the request body calculated according to RFC 1864. Example: n58IG6hfM7vqI4K0vnWpog== Default value: None
storageClass	StorageClassEnum	No	Explanation: Storage class of an object that can be specified at object creation. If you do not specify this header, the object inherits the storage class of the bucket. Value range: See Table 13. Default value: None
webSiteRedirectLocation	String	No	Explanation: If the bucket is configured with website hosting, the request for obtaining the object can be redirected to another object in the bucket or an external URL. This parameter specifies the address the request for the object is redirected to. The request is redirected to an object anotherPage.html in the same bucket: WebsiteRedirectLocation:/anotherPage.html The request is redirected to an external URL http://www.example.com/: WebsiteRedirectLocation:http://www.example.com/ Restrictions: The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB. OBS only supports redirection for objects in the root directory of a bucket. Default value: None
nextPosition	long	No	Explanation: Start position for the next append upload. Value range: 0 to the object length, in bytes. Default value: None
appendable	boolean	No	Explanation: Whether the object is appendable. Value range: true: The object is appendable. false: The object is not appendable. Default value: None
userMetadata	Map<String, Object>	No	Explanation: User-defined metadata of the object. To define it, you can add a header starting with x-obs-meta- in the request. In Map, the String key indicates the name of the user-defined metadata that starts with x-obs-meta-, and the Object value indicates the value of the user-defined metadata. To obtain the user-defined metadata of an object, use ObsClient.getObjectMetadata. For details, see Obtaining Object Metadata (SDK for Java). Restrictions: An object can have multiple pieces of metadata. The metadata size cannot exceed 8 KB in total. When you call ObsClient.getObject to download an object, its user-defined metadata will also be downloaded. Default value: None

**Table 15** AccessControlList
Parameter	Type	Mandatory (Yes/No)	Type
owner	Owner	No	Explanation: Bucket owner information. For details, see Table 16.
delivered	boolean	No	Explanation: Whether the bucket ACL is applied to all objects in the bucket. Value range: true: The bucket ACL is applied to all objects in the bucket. false: The bucket ACL is not applied to any objects in the bucket. Default value: false
grants	Set<GrantAndPermission>	No	Explanation: Grantee information. For details, see Table 17.

**Table 16** Owner
Parameter	Type	Mandatory (Yes/No)	Description
id	String	Yes	Explanation: Account (domain) ID of the bucket owner. Value range: To obtain the account ID, see How Do I Get My Account ID and User ID? Default value: None
displayName	String	No	Explanation: Account name of the owner. Value range: To obtain the account name, see How Do I Get My Account ID and User ID? Default value: None

**Table 17** GrantAndPermission
Parameter	Type	Mandatory (Yes/No)	Description
grantee	GranteeInterface	Yes	Explanation: Grantees (users or user groups). For details, see Table 19.
permission	Permission	Yes	Explanation: Permissions to grant. Value range: See Table 18. Default value: None
delivered	boolean	No	Explanation: Whether the bucket ACL is applied to all objects in the bucket. Value range: true: The bucket ACL is applied to all objects in the bucket. false: The bucket ACL is not applied to any objects in the bucket. Default value: false

**Table 18** Permission
Constant	Default Value	Description
PERMISSION_READ	READ	Read permission. A grantee with this permission for a bucket can obtain the list of objects, multipart uploads, bucket metadata, and object versions in the bucket. A grantee with this permission for an object can obtain the object content and metadata.
PERMISSION_WRITE	WRITE	Write permission. A grantee with this permission for a bucket can upload, overwrite, and delete any object or part in the bucket. This permission is not available for objects.
PERMISSION_READ_ACP	READ_ACP	Permission to read an ACL. A grantee with this permission can obtain the ACL of a bucket or object. A bucket or object owner has this permission for their bucket or object by default.
PERMISSION_WRITE_ACP	WRITE_ACP	Permission to modify an ACL. A grantee with this permission can update the ACL of a bucket or object. A bucket or object owner has this permission for their bucket or object by default. This permission allows the grantee to change the access control policies, meaning the grantee has full control over a bucket or object.
PERMISSION_FULL_CONTROL	FULL_CONTROL	Full control access, including read and write permissions for a bucket and its ACL, or for an object and its ACL. A grantee with this permission for a bucket has READ, WRITE, READ_ACP, and WRITE_ACP permissions for the bucket. A grantee with this permission for an object has READ, READ_ACP, and WRITE_ACP permissions for the object.

**Table 19** GranteeInterface
Parameter	Description
CanonicalGrantee	Explanation: Grantee (user) information. For details, see Table 20.
GroupGrantee	Explanation: Grantee (user group) information. Value range: See Table 21. Default value: None

**Table 20** CanonicalGrantee
Parameter	Type	Mandatory (Yes/No)	Description
grantId	String	Yes if Type is set to GranteeUser	Explanation: Account (domain) ID of the grantee. Value range: To obtain the account ID, see How Do I Get My Account ID and User ID? Default value: None
displayName	String	No	Parameter description: Account name of the grantee. Value range: To obtain the account name, see How Do I Get My Account ID and User ID? Default value: None

**Table 21** GroupGrantee
Constant	Description
ALL_USERS	All users.
AUTHENTICATED_USERS	Authorized users. This constant is deprecated.
LOG_DELIVERY	Log delivery group. This constant is deprecated.

Responses

**Table 22** AppendObjectResult
Parameter	Type	Description
statusCode	int	Explanation: HTTP status code. Value range: A status code is a group of digits that can be 2xx (indicating successes) or 4xx or 5xx (indicating errors). It indicates the status of a response. For more information, see Status Code. Default value: None
responseHeaders	Map<String, Object>	Explanation: Response header list, composed of tuples. In a tuple, the String key indicates the name of the header, and the Object value indicates the value of the header. Default value: None
objectKey	String	Explanation: Object name. An object is uniquely identified by an object name in a bucket. An object name is a complete path that does not contain the bucket name. For example, if the address for accessing the object is examplebucket.obs.ap-southeast-1.myhuaweicloud.com/folder/test.txt, the object name is folder/test.txt. Value range: The value must contain 1 to 1,024 characters. Default value: None
bucketName	String	Explanation: Bucket name. Restrictions: A bucket name must be unique across all accounts and regions. A bucket name: Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed. Cannot be formatted as an IP address. Cannot start or end with a hyphen (-) or period (.). Cannot contain two consecutive periods (..), for example, my..bucket. Cannot contain periods (.) and hyphens (-) adjacent to each other, for example, my-.bucket or my.-bucket. If you repeatedly create buckets of the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request. Default value: None
etag	String	Explanation: Base64-encoded, 128-bit MD5 value of the appended content. The ETag returned for the append upload is the ETag for the appended content, not that for the entire object. ETag is the unique identifier of the object content. It can be used to determine whether the object content is changed. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, the object content is changed. The ETag reflects changes only to the contents of the object, not its metadata. An uploaded object or copied object has a unique ETag. Restrictions: If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object. Value range: The value must contain 32 characters. Default value: None
storageClass	StorageClassEnum	Explanation: Storage class of an object that can be specified at object creation. If you do not specify this header, the object inherits the storage class of the bucket. Value range: See Table 13. Default value: None
nextPosition	long	Explanation: Position from which the next append upload starts Default value: None

Code Examples

This example appends data to object objectname in bucket examplebucket by specifying an append position.

    
     
       
       
         import com.obs.services.ObsClient;
import com.obs.services.exception.ObsException;
import com.obs.services.model.AppendObjectRequest;
import com.obs.services.model.AppendObjectResult;
import com.obs.services.model.ObjectMetadata;
import java.io.ByteArrayInputStream;
public class AppendObject001 {
    public static void main(String[] args) {
        // Obtain an AK/SK pair using environment variables or import the AK/SK pair in other ways. Using hard coding may result in leakage.
        // Obtain an AK/SK pair on the management console.
        String ak = System.getenv("ACCESS_KEY_ID");
        String sk = System.getenv("SECRET_ACCESS_KEY_ID");
        // (Optional) If you are using a temporary AK/SK pair and a security token to access OBS, you are advised not to use hard coding, which may result in information leakage.
        // Obtain an AK/SK pair and a security token using environment variables or import them in other ways.
        // String securityToken = System.getenv("SECURITY_TOKEN");
        // Enter the endpoint corresponding to the bucket. CN-Hong Kong is used here as an example. Replace it with the one in your actual situation.
        String endPoint = "https://obs.ap-southeast-1.myhuaweicloud.com";
        // Obtain an endpoint using environment variables or import it in other ways.
        //String endPoint = System.getenv("ENDPOINT");
        
        // Create an ObsClient instance.
        // Use the permanent AK/SK pair to initialize the client.
        ObsClient obsClient = new ObsClient(ak, sk,endPoint);
        // Use the temporary AK/SK pair and security token to initialize the client.
        // ObsClient obsClient = new ObsClient(ak, sk, securityToken, endPoint);

        try (ObsClient obsClient = new ObsClient(ak, sk, securityToken, endPoint)) {
            // Append data for the first time.
            AppendObjectRequest request = new AppendObjectRequest();
            request.setBucketName("examplebucket");
            request.setObjectKey("objectname");
            request.setPosition(0);
            request.setInput(new ByteArrayInputStream("Hello OBS".getBytes()));
            AppendObjectResult result = obsClient.appendObject(request);
            // Append data for the second time.
            request.setPosition(result.getNextPosition());
            request.setInput(new ByteArrayInputStream("Hello OBS Again".getBytes()));
            result = obsClient.appendObject(request);
            System.out.println("appendObject successfully");
            System.out.println("NextPosition:" + result.getNextPosition());
            System.out.println("Etag:" + result.getEtag());
            // Use the API for obtaining object metadata to get the start position for the next append.
            ObjectMetadata metadata = obsClient.getObjectMetadata("examplebucket", "objectname");
            System.out.println("NextPosition from metadata:" + metadata.getNextPosition());
        } catch (ObsException e) {
            System.out.println("appendObject failed");
            // Request failed. Print the HTTP status code.
            System.out.println("HTTP Code:" + e.getResponseCode());
            // Request failed. Print the server-side error code.
            System.out.println("Error Code:" + e.getErrorCode());
            // Request failed. Print the error details.
            System.out.println("Error Message:" + e.getErrorMessage());
            // Request failed. Print the request ID.
            System.out.println("Request ID:" + e.getErrorRequestId());
            System.out.println("Host ID:" + e.getErrorHostId());
            e.printStackTrace();
        } catch (Exception e) {
            System.out.println("appendObject failed");
            // Print other error information.
            e.printStackTrace();
        }
    }
}

        

      

    
   