Bucket管理

更新时间：2025-08-21

Bucket既是BOS上的命名空间，也是计费、权限控制、日志记录等高级功能的管理实体。

Bucket名称在所有区域中具有全局唯一性，且不能修改。

说明： 百度智能云目前开放了多区域支持，请参考区域选择说明。

目前支持“华北-北京”、“华南-广州”和“华东-苏州”三个区域。北京区域：http://bj.bcebos.com，广州区域：http://gz.bcebos.com，苏州区域：http://su.bcebos.com。
存储在BOS上的每个Object都必须包含在一个Bucket中。
一个用户最多可创建100个Bucket，但每个Bucket中存放的Object的数量和大小总和没有限制，用户不需要考虑数据的可扩展性。

Bucket权限管理

设置Bucket的访问权限

如下代码将Bucket的权限设置为了private。

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

CannedAccessControlList是枚举类型，包含三个值： Private 、 PublicRead 、 PublicReadWrite ，它们分别对应相关权限。具体内容可以参考BOS API文档使用CannedAcl方式的权限控制。

设置指定用户对Bucket的访问权限

BOS还可以实现设置指定用户对Bucket的访问权限，参考如下代码实现：

                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();

// 授权给特定用户
grantees.add(new Grantee("user_id1"));
grantees.add(new Grantee("user_id2"));
grantees.add(new Grantee("user_id3"));

//授权给Everyone
grantees.add(new Grantee("*"));


//设置权限
permissions.add(Permission.WRITE);
permissions.add(Permission.READ);
permissions.add(Permission.LIST);

// 设置ip
ipAddress.add("ipAddress1");
ipAddress.add("ipAddress2");
ipAddress.add("ipAddress3");
condition.setIpAddress(ipAddress);

//设置 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);

// 设置 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);

// 设置 resource
resource.add("yourBucketName");


//设置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();

// 授权给特定用户
grantees1.add(new Grantee("user_id4"));
grantees1.add(new Grantee("user_id5"));
grantees1.add(new Grantee("user_id6"));

//授权给Everyone
grantees.add(new Grantee("*"));

//设置权限
permissions.add(Permission.FULL_CONTROL);
permissions1.add(Permission.WRITE);
permissions1.add(Permission.READ);
permissions1.add(Permission.LIST);

// 设置ip
ipAddress1.add("ipAddress4");
ipAddress1.add("ipAddress5");
ipAddress1.add("ipAddress6");
condition1.setIpAddress(ipAddress1);

//设置 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);

// 设置 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);

// 设置 resource
resource1.add("yourBucketName");

// 设置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);
            

注意： resource和notResource不能同时设置 Permission中的权限设置包含三个值：READ、WRITE、FULL_CONTROL，它们分别对应相关权限。具体内容可以参考BOS API文档上传ACL文件方式的权限控制。

设置更多Bucket访问权限

通过设置refer白名单方式设置防盗链

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

其中jsonAcl为{\"accessControlList\":["+ "{\"grantee\":[{\"id\":\"*\"}], "+ "\"permission\":[\"FULL_CONTROL\"], "+ "\"condition\":{\"referer\":{\"stringEquals\":[\"http://test/index\"]}" + "}}]}

限制客户端IP访问，只允许部分客户端IP访问

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

其中jsonAcl为{\"accessControlList\":["+ "{\"grantee\":[{\"id\":\"*\"}], "+ "\"permission\":[\"FULL_CONTROL\"], "+ "\"condition\":{\"ipAddress\":[\"192.170.0.6\"]" + "}}]}")

设置STS临时token权限

对于通过STS方式创建的临时访问身份，管理员也可进行专门的权限设定。 STS的简介及设置临时权限的方式可参见临时授权访问。

使用BOS JAVA SDK设置STS临时token权限可参考使用STS创建BosClient

查看Bucket的权限

如下代码可以查看Bucket的权限：

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

getBucketAcl方法返回的解析类中可供调用的参数有：

参数	说明
owner	Bucket owner信息
id	Bucket owner的用户ID
acl	标识Bucket的权限列表
grantee	标识被授权人
-id	被授权人ID
permission	标识被授权人的权限

查看Bucket所属的区域

Bucket Location即Bucket Region，百度智能云支持的各region详细信息可参见区域选择说明。

如下代码可以获取该Bucket的Location信息：

                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());

新建Bucket

如下代码可以新建一个Bucket：

                Java
                
                public void createBucket (BosClient client, String bucketName) {
    // 新建一个Bucket
    client.createBucket(<bucketName>);                               //指定Bucket名称
}

注意： 由于Bucket的名称在所有区域中是唯一的，所以需要保证bucketName不与其他所有区域上的Bucket名称相同。

Bucket的命名有以下规范：

只能包括小写字母，数字，短横线（-）。

必须以小写字母或者数字开头。

长度必须在4-63字节之间。

通过上述代码创建的bucket，权限是私有读写，存储类型是标准类型（Standard）。

新建lcc bucket

java sdk支持新建lcc bucket，用户可以在构造新建bucket的请求中填入lcclocation，CreateBucketRequest具体参数如下：

参数	类型	说明
bucketTags	String	Bucket 标签
lccLocation	String	lcc id，用于创建lcc bucket到特定的lcc集群
enableDedicated	Boolean	用于控制控制台开启lcc识别白名单

如下代码可以新建一个lcc Bucket：

                Java
                
            

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

列举Bucket

如下代码可以列出用户所有的Bucket，或参考完整示例。

                Java
                
            

                public void listBuckets (BosClient client) {
    // 获取用户的Bucket列表
    List<BucketSummary> buckets = client.listBuckets().getBuckets();

    // 遍历Bucket
    for (BucketSummary bucket : buckets) {
        System.out.println(bucket.getName());
    }
} 
            

删除Bucket

如下代码可以删除一个Bucket，或参考完整示例。

                Java
                
                public void deleteBucket (BosClient client, String bucketName) {
    // 删除Bucket
    client.deleteBucket(<bucketName>);                                //指定Bucket名称
}

注意：

在删除前需要保证此Bucket下的所有Object和未完成的三步上传Part已经被删除，否则会删除失败。

在删除前确认该Bucket没有开通跨区域复制，不是跨区域复制规则中的源Bucket或目标Bucket，否则不能删除。

判断Bucket是否存在

若用户需要判断某个Bucket是否存在，则如下代码可以做到，或参考完整示例。

                Java
                
            

                public void doesBucketExist (BosClient client, String bucketName) {

    // 获取Bucket的存在信息
    boolean exists = client.doesBucketExist(<bucketName>);                //指定Bucket名称

    // 输出结果
    if (exists) {
        System.out.println("Bucket exists");
    } else {
        System.out.println("Bucket not exists");
    }
}
            

注意： 如果Bucket不为空（即Bucket中有Object存在），则Bucket无法被删除，必须清空Bucket后才能成功删除。

设置Bucket存储类型

新建的Bucket默认是标准存储类型，用户也可以通过如下代码设置或获取指定Bucket的存储类型：

参数	说明
storageClass	存储类型，支持"STANDARD"、"STANDARD_IA"、"COLD"、"ARCHIVE"

                Java
                
            

                public void PutBucketStorageClass() {
    // 设置"STANDARD_IA"，低频存储
    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();
}
            

设置Bucket服务端加密

若用户需要开启Bucket服务端加密，则如下代码可以做到：

参数	说明
encryptionAlgorithm	指定Bucket的服务器端加密类型，当前只支持AES256加密。

                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);
}
            

若用户想查看Bucket服务端加密信息，则如下代码可以做到:

                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;
}
            

若用户想删除Bucket服务端加密信息，则如下代码可以做到:

                Java
                
            

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

Bucket数据同步

若用户需要开启Bucket之间的数据同步，则如下代码可以做到：

参数	是否必须	描述
id	是	replication规则名，id 由数字字母 - _ 组成，不得超过20个字符
status	是	是否生效，生效为enabled
resource	是	replication生效前缀，resource的配置形式为｛$bucket_name/<生效的对象前缀>｝，必须要以`$bucket_name`+`/`开头
destination	是	复制的目的端配置
+bucket	是	目的Bucket name
+storageClass	否	目的Object的存储类型。如果保持和源Bucket的存储类型一致，则该参数不需要配置；如果需要单独指定存储类型可以为`STANDARD`，`STANDARD_IA`，`COLD`。
replicateHistory	否	历史文件复制，有该项则认为是开启。开启历史文件复制后，存量的全部Object都同步复制到目的Bucket，复制范围共用resource。
+storageClass	否	目的Object的存储类型。如果保持和源Bucket的存储类型一致，则该参数不需要配置；如果需要单独指定存储类型可以为`STANDARD`，`STANDARD_IA`，`COLD`。
replicateDeletes	是	是否开启删除同步,可以为`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);
  }
            

若用户想获取bucket指定id的数据同步信息，包括源Bucket名称、目的Bucket名称、存储类型、是否进行历史复制，数据同步策略，目的region等。如下代码可以做到:

                Java
                
            

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

若用户想删除bucket指定id的数据同步，则如下代码可以做到：

                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);
}
            

若用户想获取bucket所有的replication同步规则，则如下代码可以做到：

                Java
                
            

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

若用户想获取指定id的数据同步复制的进程状态，则如下代码可以做到：

                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静态网站托管

将网站托管在Bucket上，实现轻量化运维,如下代码可以做到：

参数	说明
index	Index文件名称
notFound	404文件名称

                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);
}
            

若用户想查看静态网站托管信息，则如下代码可以做到:

                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;
}
            

若用户想关闭静态网站托管功能，则如下代码可以做到：

                Java
                
            

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

原图保护

若用户想开启Bucket的原图保护功能，则如下代码可以做到:

参数	说明
resource	表示生效的资源范围

                Java
                
            

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

若用户想获取某个Bucket的原图保护配置情况，则如下代码可以做到:

                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;
}
            

若用户想关闭原图保护功能，则如下代码可以做到：

                Java
                
            

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

初始化

安装SDK工具包

对象存储 BOS