Bucket management

Updated at：2025-11-03

A bucket serves as both a namespace within BOS and a management entity for advanced features like billing, permission control, and log recording.

Bucket names are globally unique across all regions and cannot be changed after creation.

Notes Baidu AI Cloud currently supports multiple regions. Please refer to[Region Selection Guide](Reference/Region Selection Instructions/Region.md).

Currently, the supported regions include "North China-Beijing," "South China-Guangzhou" and "East China-Suzhou." Beijing region: http://bj.bcebos.com, Guangzhou region: http://gz.bcebos.com, Suzhou region: http://su.bcebos.com.
Each item stored in BOS is required to reside within a bucket.
Users can create up to 100 buckets, with no limits on the number or total size of objects stored in each bucket. Data scalability is automatically managed by the system, so users need not worry about capacity limits.

Bucket permission management

Set bucket access permissions

The following example sets the bucket's permission to private.

                Java
                
                public void setBucketPrivate (BosClient client, String bucketName) {
    client.setBucketAcl(<bucketName>, CannedAccessControlList.Private);
}

CannedAccessControlList an enumerated type and contains three values: Private, PublicRead and PublicReadWrite, which correspond to relevant permissions respectively. For details, refer to BOS API Documentation [Permission Control Using CannedAcl](BOS/API Reference/Access control.md#Permission control by CannedAcl).

Set access permissions for a specific user on the bucket

BOS can also set the access permissions of a specified user to the bucket. Refer to the following code for implementation:

                Java
                
            

                List<Grant> accessControlList = new ArrayList<Grant>();
List<Grantee> grantees = new ArrayList<Grantee>();
List<Permission> permissions = new ArrayList<Permission>();
List<String> ipAddress = new ArrayList<String>();
List<String> stringLike = new ArrayList<String>();
List<String> stringEquals = new ArrayList<String>();
List<String> resource = new ArrayList<String>();
List<String> notResource = new ArrayList<String>();
Referer referer = new Referer();
Condition condition = new Condition();
 // Grant permission to specific user
grantees.add(new Grantee("user_id1"));
grantees.add(new Grantee("user_id2"));
grantees.add(new Grantee("user_id3"));
 //Grant permission to Everyone
grantees.add(new Grantee("*"));
 //Set permissions
permissions.add(Permission.WRITE);
permissions.add(Permission.READ);
permissions.add(Permission.LIST);
 // Set ip
ipAddress.add("ipAddress1");
ipAddress.add("ipAddress2");
ipAddress.add("ipAddress3");
condition.setIpAddress(ipAddress);
 // Set refer stringLike
stringLike.add("http://www.example1.com/");
stringLike.add("http://www.example2.com/");
stringLike.add("http://www.example3.com/");
referer.setStringLike(stringLike);
condition.setReferer(referer);
 // Set refer stringEquals
stringEquals.add("http://www.baidu.com");
stringEquals.add("http://www.xiaomi.com");
stringEquals.add("http://www.google.com");
referer.setStringEquals(stringEquals);
condition.setReferer(referer);
 // Set resource
resource.add("yourBucketName");
 // Set notResource
List<String> notResouce = new ArrayList<String>();
notResouce.add("yourBucketName");
notResouce.add("yourBucketName/*");
Grant grant = new Grant();
grant.setGrantee(grantees);
grant.setPermission(permissions);
grant.setCondition(condition);
grant.setResource(resource);
List<Grantee> grantees1 = new ArrayList<Grantee>();
List<Permission> permissions1 = new ArrayList<Permission>();
List<String> ipAddress1 = new ArrayList<String>();
List<String> stringLike1 = new ArrayList<String>();
List<String> stringEquals1 = new ArrayList<String>();
List<String> resource1 = new ArrayList<String>();
List<String> notResource1 = new ArrayList<String>();
Referer referer1 = new Referer();
Condition condition1 = new Condition();
 // Grant permission to specific user
grantees1.add(new Grantee("user_id4"));
grantees1.add(new Grantee("user_id5"));
grantees1.add(new Grantee("user_id6"));
 //Grant permission to Everyone
grantees.add(new Grantee("*"));
 //Set permissions
permissions.add(Permission.FULL_CONTROL);
permissions1.add(Permission.WRITE);
permissions1.add(Permission.READ);
permissions1.add(Permission.LIST);
 // Set ip
ipAddress1.add("ipAddress4");
ipAddress1.add("ipAddress5");
ipAddress1.add("ipAddress6");
condition1.setIpAddress(ipAddress1);
 // Set refer stringLike
stringLike1.add("http://www.example4.com/");
stringLike1.add("http://www.example5.com/");
stringLike1.add("http://www.example6.com/");
referer1.setStringLike(stringLike1);
condition1.setReferer(referer1);
 // Set refer stringEquals
stringEquals1.add("http://www.baidu1.com");
stringEquals1.add("http://www.xiaomi1.com");
stringEquals1.add("http://www.google1.com");
referer1.setStringEquals(stringEquals1);
condition1.setReferer(referer1);
 // Set resource
resource1.add("yourBucketName");
 // Set notResource
List<String> notResouce = new ArrayList<String>();
notResouce.add("yourBucketName");
notResouce.add("yourBucketName/*");
Grant grant1 = new Grant();
grant1.setGrantee(grantees1);
grant1.setPermission(permissions1);
grant1.setCondition(condition1);
grant1.setResource(resource1);
accessControlList.add(grant);
accessControlList.add(grant1);
SetBucketAclRequest request = new SetBucketAclRequest("yourBucketName",accessControlList);
client.setBucketAcl(request);
            

Note: resource and notResource cannot be set at the same time The permission settings in Permission include three values: READ, WRITE, FULL_CONTROL, which correspond to relevant permissions respectively. For details, refer to BOS API Documentation - [Permission Control via Uploading ACL Files](BOS/API Reference/Access control.md#Permission control by uploading ACL files).

Set more bucket access permissions

Set anti-leech through refer allow list

                Java
                
                String jsonAcl = "";
client.setBucketAcl("bucketName", jsonAcl)

Among them, jsonAcl is {"accessControlList":["+ "{"grantee":[{"id":"*"}], "+ ""permission":["FULL_CONTROL"], "+ ""condition":{"referer":{"stringEquals":["http://test/index"]}" + "}}]}

Restrict client IP access, only allow some client IPs to access

                Java
                
                String jsonAcl = "";
client.setBucketAcl("bucketName", jsonAcl)

Among them, jsonAcl is {\"accessControlList\":["+ "{\"grantee\":[{\"id\":\"*\"}], "+ "\"permission\":[\"FULL_CONTROL\"], "+ "\"condition\":{\"ipAddress\":[\"192.170.0.6\"]" + "}}]}")

Set STS temporary token permissions

For temporary access identities created through STS, administrators can also set specific permissions. For an introduction to STS and how to set temporary permissions, please refer to [Temporary Authorization Access](BOS/API Reference/Access control.md#Temporary authorized access).

For setting STS temporary token permissions using the BOS JAVA SDK, you can refer to [Creating BosClient with STS](BOS/SDK/Java-SDK/Initialization.md#Create a BosClient with STS)

View bucket permissions

The following code can be used to view the bucket permissions:

                Java
                
                GetBucketAclResponse aclResponse = client.getBucketAcl("bucketName");
System.out.println(aclResponse.getAccessControlList().toString());

The parameters available for calling in the resolution class returned by the getBucketAcl method are as follows:

Parameters	Description
owner	Bucket owner information
id	User ID of bucket owner
acl	Identify the permission list of the bucket
grantee	Identify the grantee
-id	Authorized person ID
permission	Identify the grantee permissions

View the region to which a bucket belongs

Bucket Location refers to Bucket Region. For details on regions supported by Baidu AI Cloud, refer to [Region Selection Guide](Reference/Region Selection Instructions/Region.md).

The following code can retrieve the bucket's location information:

                Java
                
            

                BosClient client = new BosClient(config);
ListBucketsResponse listBucketsResponse =  client.listBuckets();
List<BucketSummary> bucketSummaryList =  listBucketsResponse.getBuckets();
for(BucketSummary bs : bucketSummaryList){
    System.out.println( bs.getLocation());
}
System.out.println(client.getBucketLocation("bucket-test").getLocationConstraint());
            

Create Bucket

The following code can be used to create a bucket:

                Java
                
                public void createBucket (BosClient client, String bucketName) {
 // Create a new bucket
 client.createBucket(<bucketName>); //Specify bucket name
}

Note: Since the bucket name is unique across all regions, it is necessary to ensure that the bucketName is not the same as the BucketName on all other regions.

Bucket naming follows the following conventions:

Only lowercase letters, numbers, and hyphens (-) are allowed.

Must start with a lowercase letter or a number.

Length should range between 4-63 bytes.

The bucket created using the above code has private read-write permissions and a standard (Standard) storage class.

Create a new lcc bucket

The Java SDK supports creating LCC buckets. Users can fill in lcclocation in the request for creating a new bucket. The specific parameters of CreateBucketRequest are as follows:

Parameters	Types	Description
bucketTags	String	Bucket tags
lccLocation	String	lcc id, used to create an lcc bucket in a specific lcc cluster
enableDedicated	Boolean	Used to control the console to enable the lcc recognition allow list

The following code can be used to create a lcc bucket:

                Java
                
            

                public void createBucket (BosClient client, String bucketName) {
    CreateBucketRequest request = new CreateBucketRequest("bucketName");
 // Set lcc location id
    request.setLccLocation("lcc id");
    request.setEnableDedicated(true);
    client.createBucket(request);                               
}
            

List buckets

List all the user’s buckets using the following code or with reference to Complete Example.

                Java
                
            

                public void listBuckets (BosClient client) {
 // Obtain the user's bucket list
    List<BucketSummary> buckets = client.listBuckets().getBuckets();
 // Traverse bucket
    for (BucketSummary bucket : buckets) {
        System.out.println(bucket.getName());
    }
}
            

Delete bucket

Delete a bucket using the following code or with reference to Complete Example.

                Java
                
                public void deleteBucket (BosClient client, String bucketName) {
 // Delete bucket
 client.deleteBucket(<BucketName>);     //Specify bucket name
}

Note:

Before deletion, ensure that all objects and any unfinished multipart uploads in the bucket have been fully removed. Otherwise, the deletion will fail.

Before deleting a bucket, verify that Cross-Region Replication (CRR) is not enabled for the bucket, and that it is neither the source nor target bucket in any CRR rules. Otherwise, the deletion will fail.

Check if bucket exists

Users can determine whether a bucket exists using the following code or with reference to Complete Example.

                Java
                
            

                public void doesBucketExist (BosClient client, String bucketName) {
 // Retrieve bucket existence information
 boolean exists = client.doesBucketExist(<BucketName>); //Specify the bucket name
 // Output result
    if (exists) {
        System.out.println("Bucket exists");
    } else {
        System.out.println("Bucket not exists");
    }
}
            

Note: If the bucket is not null (that is, there are objects in the bucket), the bucket cannot be deleted. The bucket must be emptied before it can be deleted successfully.

Set bucket storage class

A newly created bucket is of the standard storage class by default. Users can set or get the storage class of a specified bucket through the following code:

Parameters	Description
storageClass	Storage classes, supporting "STANDARD", "STANDARD_IA", "COLD", "ARCHIVE"

                Java
                
            

                public void PutBucketStorageClass() {
 // Set to "STANDARD_IA", infrequent access storage
    String storageClass = STORAGE_CLASS_STANDARD_IA;
    this.client.putBucketStorageClass(this.bucketName, storageClass);
}
public String GetBucketStorageClass() {
    GetBucketStorageClassResponse response = this.client.getBucketStorageClass(this.bucketName);
    return response.getStorageClass();
}
            

Set Bucket server-side encryption

If users need to enable the server-side encryption of the bucket, the following code can achieve this:

Parameters	Description
encryptionAlgorithm	This specifies the server-side encryption type for a bucket, which currently supports AES256 encryption only.

                Java
                
            

                public void PutBucketEncryptionByEncryption(BosClient client, String bucketName, String encryptionAlgorithm ) {
    SetBucketEncryptionRequest setBucketEncryptionRequest = new SetBucketEncryptionRequest();
    setBucketEncryptionRequest.setBucketName(bucketName);
    BucketEncryption encryption = new BucketEncryption();
    encryption.setEncryptionAlgorithm(encryptionAlgorithm);
    setBucketEncryptionRequest.setBucketEncryption(encryption);
    client.setBucketEncryption(setBucketEncryptionRequest);
}
            

If users want to view the server-side encryption information of the bucket, the following code can achieve this:

                Java
                
            

                public GetBucketEncryptionResponse GetBucketEncryption(BosClient client, String bucketName) {
    GetBucketEncryptionRequest getBucketEncryptionRequest = new GetBucketEncryptionRequest();
    getBucketEncryptionRequest.withBucketName(bucketName);
    GetBucketEncryptionResponse resp = new GetBucketEncryptionResponse();
    resp = client.getBucketEncryption(getBucketEncryptionRequest);
    return resp;
}
            

If users want to delete the server-side encryption information of the bucket, the following code can achieve this:

                Java
                
            

                public void DeleteBucketEncryption(BosClient client, String bucketName) {
    DeleteBucketEncryptionRequest deleteBucketEncryptionRequest = new DeleteBucketEncryptionRequest();
    deleteBucketEncryptionRequest.withBucketName(bucketName);
    client.deleteBucketEncryption(deleteBucketEncryptionRequest);
}
            

Bucket data synchronization

If users need to enable data synchronization between buckets, the following code can achieve this:

Parameters	Required or not	Description
id	Yes	Rule name of replication. The ID must consist of numbers, letters, hyphens (-), and underscores (_), and shall not exceed 20 characters.
status	Yes	Whether it takes effect; “enabled” means it is effective
resource	Yes	Effective prefix of replication. The resource configuration format is ｛$bucket_name/｝, and must start with `$bucket_name`+`/`.
destination	Yes	Destination location configuration of replication
+bucket	Yes	Destination Bucket name
+storageClass	No	Storage class of destination object. If you want to keep the same storage class as the source Bucket, this parameter does not need to be configured; if you need to specify a separate storage class, it can be `STANDARD`, `STANDARD_IA`, `COLD`.
replicateHistory	No	Historical file replication: When enabled, all existing objects will be synchronously replicated to the destination bucket, sharing the same resource scope.
+storageClass	No	Storage class of destination object. If you want to keep the same storage class as the source Bucket, this parameter does not need to be configured; if you need to specify a separate storage class, it can be `STANDARD`,`STANDARD_IA` and `COLD`.
replicateDeletes	Yes	It indicates whether Delete synchronization function is enabled. It is `enabled`,`disabled`.

                Java
                
            

                public void PutBucketReplicationByReplication(BosClient client, String bucketName, String replicationId, String dstBucketName) {
  SetBucketReplicationRequest request = new SetBucketReplicationRequest(bucketName);
    request.setId(replicationId);
    request.setStatus("enabled");
    String[] resource = {bucketName + "/abc"};
    request.setResource(resource);
    Destination destination = new Destination();
    destination.setBucket(dstBucketName);
    request.setDestination(destination);
    request.setReplicateDeletes("enabled");
    client.setBucketReplication(request);
  }
            

Users can obtain data synchronization details for a specified bucket ID, including the source bucket name, destination bucket name, storage class, whether historical replication is enabled, data synchronization policy, destination region, and more. The following code demonstrates this:

                Java
                
            

                public void GetBucketReplication(BosClient client, String bucketName, String replicationId) {
   GetBucketReplicationRequest grequest = new GetBucketReplicationRequest(bucketName);
   grequest.setId(replicationId);
   GetBucketReplicationResponse response = client.getBucketReplication(grequest);
 }
            

If users want to delete the data synchronization with a specified ID in the bucket, the following code can achieve this:

                Java
                
            

                public void DeleteBucketReplication(BosClient client, String bucketName, String replicationId) {
    DeleteBucketReplicationRequest drequest = new          DeleteBucketReplicationRequest();
    drequest.setBucketName(this.bucketName);
    drequest.setId(this.replicationId);
    client.deleteBucketReplication(drequest);
}
            

If users want to get all replication synchronization rules of the bucket, the following code can achieve this:

                Java
                
            

                public void ListBucketReplication(BosClient client, String bucketName) {
    ListBucketReplicationResponse replicationResponse;
    ListBucketReplicationRequest listreq = new ListBucketReplicationRequest(this.bucketName);
    replicationResponse = client.listBucketReplication(listreq);
}
            

If users want to get the progress status of data synchronization replication with a specified ID, the following code can achieve this:

                Java
                
            

                public void GetBucketReplicationProgress(BosClient client, String bucketName，String replicationId) {
    GetBucketReplicationProgressRequest proreq = new GetBucketReplicationProgressRequest(this.bucketName);
    proreq.setId(this.replicationId);
    BucketReplicationProgress progress = client.getBucketReplicationProgress(proreq);
}
            

Bucket static website hosting

Hosting a website on a bucket enables lightweight operation and maintenance, which can be achieved with the following code:

Parameters	Description
index	Index file name
notFound	404 file name

                Java
                
            

                public void PutBucketStaticWebsite(BosClient client, String bucketName, String index, String notFound) {
    SetBucketStaticWebsiteRequest setBucketStaticWebsiteRequest = new SetBucketStaticWebsiteRequest();
    setBucketStaticWebsiteRequest.setBucketName(bucketName);
    setBucketStaticWebsiteRequest.setIndex(index);
    setBucketStaticWebsiteRequest.setNotFound(notFound);
    client.setBucketStaticWebSite(setBucketStaticWebsiteRequest);
}
            

If users want to view the static website hosting information, the following code can achieve this:

                Java
                
            

                public GetBucketStaticWebsiteResponse GetBucketStaticWebsite(BosClient client, String bucketName) {
    GetBucketStaticWebsiteRequest getBucketStaticWebsiteRequest = new GetBucketStaticWebsiteRequest();
    getBucketStaticWebsiteRequest.withBucketName(bucketName);
    GetBucketStaticWebsiteResponse resp = new GetBucketStaticWebsiteResponse();
    resp = client.getBucketStaticWebsite(getBucketStaticWebsiteRequest);
    return resp;
}
            

Users can disable the static website hosting function using the following code:

                Java
                
            

                public void DeleteBucketStaticWebsite(BosClient client, String bucketName) {
    DeleteBucketStaticWebsiteRequest deleteBucketStaticWebsiteRequest = new DeleteBucketStaticWebsiteRequest();
    deleteBucketStaticWebsiteRequest.withBucketName(bucketName);
    client.deleteBucketStaticWebSite(deleteBucketStaticWebsiteRequest);
}
            

Original image protection

If users want to enable the original image protection function of the bucket, the following code can achieve this:

Parameters	Description
resource	Indicate the scope of effective resources

                Java
                
            

                public void PutBucketCopyrightProtection(BosClient client, String bucketName, List<String> resource) {
    SetBucketCopyrightProtectionRequest request = new SetBucketCopyrightProtectionRequest();
    request.setBucketName(bucketName);
    request.setResource(resource);
    client.setBucketCopyrightProtection(request);
}
            

If users want to get the original image protection configuration details of the bucket, the following code can achieve this:

                Java
                
            

                public GetBucketCopyrightProtectionResponse GetBucketCopyrightProtection(BosClient client, String bucketName) {
    GetBucketCopyrightProtectionRequest getBucketCopyrightProtectionRequest =
                    new GetBucketCopyrightProtectionRequest();
    getBucketCopyrightProtectionRequest.withBucketName(bucketName);
    GetBucketCopyrightProtectionResponse resp = new GetBucketCopyrightProtectionResponse();
    resp = client.getBucketCopyrightProtection(getBucketCopyrightProtectionRequest);
    return resp;
}
            

If users want to disable the original image protection function of the bucket, the following code can achieve this:

                Java
                
            

                public void DeleteBucketCopyrightProtection(BosClient client, String bucketName) {
    DeleteBucketCopyrightProtectionRequest deleteBucketCopyrightProtectionRequest =
                    new DeleteBucketCopyrightProtectionRequest();
    deleteBucketCopyrightProtectionRequest.withBucketName(bucketName);
    client.deleteBucketCopyrightProtection(deleteBucketCopyrightProtectionRequest);
}
            

Data Processing and Usage

Bucket management