Upload Object

Updated at：2025-11-03

Simplest upload

Basic workflow

Instantiate the BOSClient class.
The BOSClient.putObject() method allows objects to be uploaded in four ways: file, data stream, binary string, and plain string.
For the returned PutObjectResponse instance, call getETag() to get the successfully uploaded ETag.

Example code

                Java
                
            

                // Get specified file
 File file = new File(<FilePath>);     //Specify the file path
 // Upload object as a file
PutObjectResponse putObjectFromFileResponse =
    client.putObject(<BucketName>, <ObjectKey>, file);
 // Obtain data stream
InputStream inputStream = new FileInputStream(<FilePath>);
 // Upload an object in the form of a data stream
PutObjectResponse putObjectResponseFromInputStream =
    client.putObject(<BucketName>, <ObjectKey>, inputStream);
 // Upload object as binary string
PutObjectResponse putObjectResponseFromByte =
    client.putObject(<BucketName>, <ObjectKey>, <byte>);
 // Upload object in string form
PutObjectResponse putObjectResponseFromString =
    client.putObject(<BucketName>, <ObjectKey>, <string>);
 // Print ETag
System.out.println(putObjectFromFileResponse.getETag());
            

Note: Objects are uploaded to BOS as files, and the putObject function supports uploading objects with a size not exceeding 5GB. After the putObject request is processed successfully, BOS will return the ETag of the object in the Header as the file identifier.

Complete example

                Java
                
            

                import java.io.File;
import java.io.FileInputStream;
import java.io.FileNotFoundException;
import java.io.InputStream;
import android.app.Activity;
import android.os.Bundle;
import com.baidubce.BceClientException;
import com.baidubce.BceServiceException;
import com.baidubce.auth.DefaultBceCredentials;
import com.baidubce.development.R;
import com.baidubce.services.bos.BosClient;
import com.baidubce.services.bos.BosClientConfiguration;
import com.baidubce.services.bos.model.PutObjectResponse;
​    
public class ExampleActivity extends Activity {
  private String bucketName = <BucketName>;
  private String objectKey = <ObjectKey>;
  byte[] b = null;
  String str = <PutString>;
  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    new Thread(new Runnable() {
        @Override
        public void run() {
            try {
                BosClientConfiguration config = new BosClientConfiguration();
                config.setCredentials(new DefaultBceCredentials(<AccessKeyID>, <SecretAccessKey>));
                config.setEndpoint(<EndPoint>);
                BosClient client = new BosClient(config);
 // Get specified file
                File file = new File("/path/to/file.zip");
 // Upload object as a file
                PutObjectResponse putObjectFromFileResponse = client.putObject(<BucketName>, <ObjectKey>, file);
 // Obtain data stream
                InputStream inputStream = new FileInputStream("/path/to/test.zip");
 // Upload an object in the form of a data stream
                PutObjectResponse putObjectResponseFromInputStream = client.putObject(<BucketName>, <ObjectKey>, inputStream);
 // Upload object as binary string
                PutObjectResponse putObjectResponseFromByte = client.putObject(<BucketName>, <ObjectKey>, b);
 // Upload object in string form
                PutObjectResponse putObjectResponseFromString = client.putObject(<BucketName>, <ObjectKey>, str);
 // Print ETag
                System.out.println(putObjectFromFileResponse.getETag());
            } catch (BceServiceException e) {
                System.out.println("Error ErrorCode: " + e.getErrorCode());
                System.out.println("Error RequestId: " + e.getRequestId());
                System.out.println("Error StatusCode: " + e.getStatusCode());
                System.out.println("Error Message: " + e.getMessage());
                System.out.println("Error ErrorType: " + e.getErrorType());
            } catch (BceClientException e) {
                System.out.println("Error Message: " + e.getMessage());
            } catch (FileNotFoundException e) {
                // TODO Auto-generated catch block
                e.printStackTrace();
            }
        }
    }).start();
}}
            

Set the Copy attributes of an object

The CopyObject API copies an existing object to a new one. During the process, it checks the source object's ETag or modification status to decide whether to proceed with the operation. The detailed parameters are as follows:

Name	Types	Description	Whether required
x-bce-copy-source-if-match	String	If the ETag value of the source object matches the ETag value provided by the user, the copy operation is performed; otherwise, it fails.	No
x-bce-copy-source-if-none-match	String	If the ETag value of the source object does not match the ETag value provided by the user, the copy operation is performed; otherwise, it fails.	No
x-bce-copy-source-if-unmodified-since	String	If the source object has not been modified since x-bce-copy-source-if-unmodified-since, the copy operation will proceed; otherwise, it will fail.	No
x-bce-copy-source-if-modified-since	String	If the source object has been modified since x-bce-copy-source-if-modified-since, the copy operation will proceed; otherwise, it will fail.	No

Example code

                Java
                
            

                // Initialize BosClient
BosClient client = ...;
 // Create CopyObjectRequest object
CopyObjectRequest copyObjectRequest = new CopyObjectRequest(srcBucketName, srcKey, destBucketName, destKey);
 // Set new Metadata
Map<String, String> userMetadata = new HashMap<String, String>();
userMetadata.put("<user-meta-key>","<user-meta-value>");
ObjectMetadata meta = new ObjectMetadata();
meta.setUserMetadata(userMetadata);
copyObjectRequest.setNewObjectMetadata(meta);
//copy-source-if-match
copyObjectRequest.withETag("111111111183bf192b57a4afc76fa632");
//copy-source-if-none-match
copyObjectRequest.withNoMatchingETagConstraint("111111111183bf192b57a4afc76fa632");
Date modifiedSinceConstraint = new Date();    
SimpleDateFormat df = new SimpleDateFormat("E, dd MMM yyyy HH:mm:ss z", Locale.UK);  
df.setTimeZone(new java.util.SimpleTimeZone(0, "GMT"));        
String date = df.format(modifiedSinceConstraint);
//copy-source-if-modified-since
copyObjectRequest.withModifiedSinceConstraint(date);
//copy-source-if-unmodified-since
copyObjectRequest.withUnmodifiedSinceConstraint(date);
 // Copy Object
CopyObjectResponse copyObjectResponse = client.copyObject(copyObjectRequest);
            

Set object's HTTP Header

BOS allows setting Http Headers when uploading an object.

Basic workflow

Create an ObjectMetadata instance.
Use methods like setContentLength() and setContentType() to configure Http Headers.
Pass the metadata as a parameter when calling client.putObject().

Example code

                Java
                
            

                // Create an instance of the ObjectMetadata class
ObjectMetadata meta = new ObjectMetadata();
 // Set ContentLength size
meta.setContentLength(<Length>);
 // Set ContentType
meta.setContentType("application/json");
client.putObject(<BucketName>, <ObjectKey>, content, meta);
            

Note: Headers can be set with attributes such as "Cache-Control", "Content-Encoding", "Content-Disposition", and "Expires"

Complete example

                Java
                
            

                import java.io.FileInputStream;
import java.io.FileNotFoundException;
import java.io.InputStream;
import android.app.Activity;
import android.os.Bundle;
import com.baidubce.BceClientException;
import com.baidubce.BceServiceException;
import com.baidubce.auth.DefaultBceCredentials;
import com.baidubce.demo.R;
import com.baidubce.services.bos.BosClient;
import com.baidubce.services.bos.BosClientConfiguration;
import com.baidubce.services.bos.model.ObjectMetadata;
import com.baidubce.services.bos.model.PutObjectResponse;
public class ExampleActivity extends Activity {
private String bucketName = <BucketName>;
private String objectKey = <ObjectKey>;
@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    new Thread(new Runnable() {
        @Override
        public void run() {
            try {
                BosClientConfiguration config = new BosClientConfiguration();
                config.setCredentials(new DefaultBceCredentials(<AccessKeyID>, <SecretAccessKey>));
                config.setEndpoint(<EndPoint>);
                BosClient client = new BosClient(config);
 // Obtain data stream
                InputStream inputStream = new FileInputStream("/path/to/test.zip");
 // Create an instance of the ObjectMetadata class
                ObjectMetadata meta = new ObjectMetadata();
 // Set ContentLength size
                meta.setContentLength(1000);
 // Set ContentType
                meta.setContentType("application/json");
                PutObjectResponse putObjectResponseFromInputStream = client.putObject(bucketName, objectKey, inputStream, meta);
 // Print ETag
                System.out.println(putObjectResponseFromInputStream.getETag());
            } catch (BceServiceException e) {
                System.out.println("Error ErrorCode: " + e.getErrorCode());
                System.out.println("Error RequestId: " + e.getRequestId());
                System.out.println("Error StatusCode: " + e.getStatusCode());
                System.out.println("Error Message: " + e.getMessage());
                System.out.println("Error ErrorType: " + e.getErrorType());
            } catch (BceClientException e) {
                System.out.println("Error Message: " + e.getMessage());
            } catch (FileNotFoundException e) {
                // TODO Auto-generated catch block
                e.printStackTrace();
            }
        }
    }).start();
}}
            

User-defined metadata

BOS supports user-defined metadata for object descriptions.

Basic workflow

Create an ObjectMetadata instance.
Use the addUserMetadata() method to add custom metadata to the Http Headers.
Pass the metadata as a parameter when calling client.putObject().

Example code

                Java
                
                // Set the value of custom metadata name to my-data
meta.addUserMetadata("name", "my-data");	  
 // Upload Object
client.putObject(<BucketName>, <ObjectKey>, <Content>, meta);

Note: In the provided example, a user-defined metadata property is created with the key "name" and the value "my-data." This metadata can be retrieved when the object is downloaded. Though multiple such parameters can be added, the combined size of all User Metadata must not exceed 2KB.

Complete example

                Java
                
            

                import java.io.FileInputStream;
import java.io.FileNotFoundException;
import java.io.InputStream;
import android.app.Activity;
import android.os.Bundle;
import com.baidubce.BceClientException;
import com.baidubce.BceServiceException;
import com.baidubce.auth.DefaultBceCredentials;
import com.baidubce.demo.R;
import com.baidubce.services.bos.BosClient;
import com.baidubce.services.bos.BosClientConfiguration;
import com.baidubce.services.bos.model.ObjectMetadata;
import com.baidubce.services.bos.model.PutObjectResponse;
public class ExampleActivity extends Activity {
private String bucketName = <BucketName>;
private String objectKey = <ObjectKey>;
@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    new Thread(new Runnable() {
        @Override
        public void run() {
            try {
                BosClientConfiguration config = new BosClientConfiguration();
                config.setCredentials(new DefaultBceCredentials(<AccessKeyID>, <SecretAccessKey>));
                config.setEndpoint(<EndPoint>);
                BosClient client = new BosClient(config);
 // Obtain data stream
                InputStream inputStream = new FileInputStream("/path/to/test.zip");
 // Create an instance of the ObjectMetadata class
                ObjectMetadata meta = new ObjectMetadata();
 // Custom metadata
                meta.addUserMetadata("name", "my-data");	    
                PutObjectResponse putObjectResponseFromInputStream = client.putObject(<BucketName>, <ObjectKey>, inputStream, meta);
 // Print ETag
                System.out.println(putObjectResponseFromInputStream.getETag());
            } catch (BceServiceException e) {
                System.out.println("Error ErrorCode: " + e.getErrorCode());
                System.out.println("Error RequestId: " + e.getRequestId());
                System.out.println("Error StatusCode: " + e.getStatusCode());
                System.out.println("Error Message: " + e.getMessage());
                System.out.println("Error ErrorType: " + e.getErrorType());
            } catch (BceClientException e) {
                System.out.println("Error Message: " + e.getMessage());
            } catch (FileNotFoundException e) {
                // TODO Auto-generated catch block
                e.printStackTrace();
            }
        }
    }).start();
}}
            

Upload object in append mode

BOS provides an AppendObject feature for uploading files in append mode, making it ideal for scenarios like log appending, live streaming, and real-time video uploads. Objects created via AppendObject belong to the Appendable Objects category, allowing additional data to be appended. In contrast, objects uploaded using PutObject are classified as Normal Objects and do not support data appending. An AppendObject has a size limit between 0 and 5GB.

Example code

                Java
                
            

                public void AppendObject(BosClient client, String bucketName, String objectKey, byte[] byte1, String string1) {
 // Get specified file
      File file = new File("/path/to/file.zip");
 // Obtain data stream
      InputStream inputStream = new FileInputStream("/path/to/test.zip");
 // Upload object as a file
      AppendObjectResponse appendObjectFromFileResponse = client.appendObject(bucketName, objectKey, file);
 // Upload an object in the form of a data stream
      AppendObjectResponse appendObjectResponseFromInputStream = client.appendObject(bucketName, objectKey, inputStream);
 // Upload object as binary string
      AppendObjectResponse appendObjectResponseFromByte = client.appendObject(bucketName, objectKey, byte1);
 // Upload object in string form
      AppendObjectResponse appendObjectResponseFromString = client.appendObject(bucketName, objectKey, string1);
 // Append content to AppendFile
      Long nextOffset = appendObjectFromFileResponse.getNextAppendOffset();
      AppendObjectRequest request =new AppendObjectRequest(bucketName, objectKey,
      RestartableInputStream.wrap(string1.getBytes()));
      request.withOffset(nextOffset);
      AppendObjectResponse appendResponse = client.appendObject(request);      
}
            

Obtain upload progress

The Android SDK supports providing real-time upload progress information during the upload. It currently supports four APIs: PutObject, AppendObject, UploadPart and PutSuperObjectFromFile Using the progress upload interface requires constructing the corresponding Request (PutObjectRequest, AppendObjectRequest, UploadPartRequest and PutSuperObjectRequest).

The SDK offers an upload progress callback API that enables you to define operations to execute during uploads, such as updating the UI.

                Java
                
            

                public interface BceProgressCallback<T extends AbstractBceRequest> {
 // request is the upload request
 // currentSize is the current upload size (unit: byte)
 // totalSize is the total size to be uploaded in this request (unit: byte)
      void onProgress(T request, long currentSize, long totalSize);
｝
            

PutObject example code

                Java
                
            

                PutObjectRequest request = new PutObjectRequest(this.bucketName, "test", file);
ObjectMetadata objectMetadata = new ObjectMetadata();
objectMetadata.setContentType("text/plain");
request.setObjectMetadata(objectMetadata);
request.setProgressCallback(new BosProgressCallback<PutObjectRequest>() {
    @Override
    public void onProgress(PutObjectRequest request, long currentSize, long totalSize) {
        Log.e(currentSize + "", totalSize + "");
    }
});
String eTag = this.client.putObject(request).getETag();
            

AppendObject example code

                Java
                
            

                ObjectMetadata objectMetadata = new ObjectMetadata();
objectMetadata.setContentType("text/plain");
AppendObjectRequest request = new AppendObjectRequest(this.bucketName, "test", file);
request.setObjectMetadata(objectMetadata);
AppendObjectResponse response = this.client.appendObject(request);
Long nextOffset = response.getNextAppendOffset();
request.withOffset(nextOffset);
request.setProgressCallback(new BosProgressCallback<AppendObjectRequest>() {
    @Override
    public void onProgress(AppendObjectRequest request, long currentSize, long totalSize) {
        Log.e(currentSize + "", totalSize + "");
    }
});
response = this.client.appendObject(request);
            

UploadPart example code

                Java
                
            

                UploadPartRequest request = new UploadPartRequest().withBucketName(this.bucketName)
        .withKey("test").withUploadId(uploadId).withPartNumber(1).withPartSize(8000)
        .withInputStream(fis);
request.setProgressCallback(new BosProgressCallback<UploadPartRequest>() {
    @Override
    public void onProgress(UploadPartRequest request, long currentSize, long totalSize) {
        Log.e(currentSize + "", totalSize + "");
    }
});
UploadPartResponse response = this.client.uploadPart(request);
            

PutSuperObjectFromFile example code

                Java
                
            

                PutSuperObjectRequest request = new PutSuperObjectRequest().withBucketName(this.bucketName)
        .withKey("test").withPartSize(1024*1024*2L).withFile(file);
request.setProgressCallback(new BosProgressCallback<PutSuperObjectRequest>() {
    @Override
    public void onProgress(PutSuperObjectRequest request, long currentSize, long totalSize) {
        Log.e(currentSize + "", totalSize + "");
    }
});
PutSuperObjectResponse response = this.client.putSuperObjectFromFile(request);
            

By default, the SDK’s upload progress callback granularity is 2,048 bytes. You can adjust the granularity to better suit your application using the provided methods.

BosClientConfiguration config=new BosClientConfiguration(); config.setUploadSegmentPart(1024);

Note: This value must be between 1-8192. If outside this range, Android SDK will forcibly set it to 2048.

Cancellation interface

Android SDK supports canceling this request during the request process. The remaining data in the upload request will not be uploaded to BOS. Canceling the operation in the download request will close the connection, and the executing operation will throw Request is canceled! exception.

All BOS operations support cancellation interfaces, but completed requests cannot be canceled, and no exceptions will be thrown for completed operations

                Java
                
            

                // Take the upload interface cancellation as an example
final PutObjectRequest req = new PutObjectRequest(<BucketName>, <ObjectName>,
         new FileInputStream(<FilePath>));
Runnable cancelTask = new Runnable() {
    @Override
    public void run() {
        try {
            Thread.sleep(100);
        } catch (InterruptedException e) {
            e.printStackTrace()
        }
 // Cancel the current upload request
        req.cancel();
    }
};
new Thread(cancelTask).start();
client.putObject(req);
            

Synchronous callback

The Android SDK supports the BOS server-side synchronous callback API. By setting the process parameter in the PutObjectRequest, the BOS server can actively trigger the callback API after upload completion to notify the client.

                Java
                
            

                PutObjectRequest request = new PutObjectRequest({bucket}, {object}, {inputStream});
 // Set the x-bce-process parameter
request.setProcess({x-bce-process});
PutObjectResponse response = client.putObject(request);
 // Obtain the returned http status code
int statusCode = response.getHttpResponse().getStatusCode();
 // Obtain the data returned by the callback API
string callbackString = response.getServerCallbackReturnBody();
            

Single-link rate limit

Baidu AI Cloud Object Storage (BOS) applies bandwidth limits per bucket. When the user's upload or download bandwidth usage reaches the threshold, the error code RequestRateLimitExceeded will be triggered.

To ensure normal service usage, BOS implements traffic control during upload and download processes, ensuring that large traffic services do not impact other applications.

The read-write API supports setting the specified rate limit value. The value range of the rate limit value is 819200~838860800 in bit/s, that is, 100KB/s~100MB/s. The rate limit value must be a number. BOS will limit the rate of this request according to the specified rate limit value. When the rate limit value is not within this range or is illegal, it will return the error code 400.

Currently, PutObjectRequest, PutSuperObjectRequest, UploadPartRequest, CopyObjectRequest and GetObjectRequest all support setting single-link rate limits. Take PutObjectRequest as an example:

                Java
                
                PutObjectRequest request = new PutObjectRequest({bucket}, {object}, {inputStream});
 // Set single-link rate limit
request.setTrafficLimitBitPS(819200);

Copy Object

Delete Object