Bucket管理

更新时间：2025-05-09

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。

1err := bosClient.PutBucketAclFromCanned(bucketName, "private")

用户可设置的CannedACL包含三个值：private 、public-read 、public-read-write，它们分别对应相关权限。具体内容可以参考BOS API文档使用CannedAcl方式的权限控制。

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

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

1// import "github.com/baidubce/bce-sdk-go/bce"
2// import "github.com/baidubce/bce-sdk-go/services/bos/api"
3
4// 1. 直接上传ACL文件流
5aclBodyStream := bce.NewBodyFromFile("<path-to-acl-file>")
6err := bosClient.PutBucketAcl(bucket, aclBodyStream)
7
8// 2. 直接使用ACL json字符串
9aclString := `{
10    "accessControlList":[
11        {
12            "grantee":[{
13                "id":"e13b12d0131b4c8bae959df4969387b8" //指定用户ID
14            }],
15            "permission":["FULL_CONTROL"] //指定用户权限
16        }
17    ]
18}`
19err := bosClient.PutBucketAclFromString(bucket, aclString)
20
21// 3. 使用ACL文件
22err := bosClient.PutBucketAclFromFile(bucket, "<acl-file-name>")
23
24// 4. 使用ACL struct对象设置
25grantUser1 := api.GranteeType{"<user-id-1>"}
26grantUser2 := api.GranteeType{"<user-id-2>"}
27grant1 := api.GrantType{
28	Grantee: []api.GranteeType{grantUser1},
29	Permission: []string{"FULL_CONTROL"},
30}
31grant2 := api.GrantType{
32	Grantee: []api.GranteeType{granteUser2},
33	Permission: []string{"READ"},
34}
35grantArr := make([]api.GranteeType, 0)
36grantArr = append(grantArr, grant1)
37grantArr = append(grantArr, grant2)
38args := &api.PutBucketAclArgs{grantArr}
39err := bosClient.PutBucketAclFromStruct(bucketName, args)

注意： Permission中的权限设置包含三个值：READ、WRITE、FULL_CONTROL，它们分别对应相关权限。具体内容可以参考BOS API文档上传ACL文件方式的权限控制。 ACL规则比较复杂，直接编辑ACL的文件或JSON字符串比较困难，因此提供了第四种方式方便使用代码创建ACL规则。

设置更多Bucket访问权限

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

1aclString := `{
2    "accessControlList":[
3        {
4            "grantee":[{"id":"*"]},        //指定用户ID为全部用户
5            "permission":["FULL_CONTROL"], //指定用户权限
6            "condition":[{"referer": {"stringEquals": "http://allowed-domain/"}}]
7        }
8    ]
9}`
10err := bosClient.PutBucketAclFromString(bucket, aclString)

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

1aclString := `{
2    "accessControlList":[
3        {
4            "grantee":[{"id":"*"]}, //指定用户ID为全部用户
5            "permission":["READ"],  //指定用户权限
6            "condition":[{"ipAddress": ["ip-1", "ip-2"]}]
7        }
8    ]
9}`
10err := bosClient.PutBucketAclFromString(bucket, aclString)

设置STS临时token权限

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

STS的简介及设置临时权限的方式可参见临时授权访问。

使用BOS GO SDK设置STS临时token权限可参考如下示例：

1// import "github.com/baidubce/bce-sdk-go/services/sts"
2
3AK, SK := <your-access-key-id>, <your-secret-access-key>
4stsClient, err := sts.NewClient(AK, SK)
5aclString := `{
6    "accessControlList":[
7        {
8            "grantee":[{"id":"*"]},        //指定用户ID为全部用户
9            "permission":["FULL_CONTROL"], //指定用户权限
10            "condition":[{"referer": {"stringEquals": "http://allowed-domain/"}}]
11        }
12    ]
13}`
14//使用有效期为300秒且指定ACL的方式获取临时STS token
15sts, err := stsClient.GetSessionToken(300, aclString)

查看Bucket的访问权限

用户可以通过如下接口查看Bucket的访问权限，注意：Bucket的访问权限不能删除，默认为私有。

1result, err := bosClient.GetBucketAcl(bucketName)

返回的结果对象的字段包含了访问权限的详细内容，具体定义如下：

1type GetBucketAclResult struct {
2	AccessControlList []struct{
3		Grantee []struct {
4			Id string
5		}
6		Permission []string
7	}
8	Owner struct {
9		Id string
10	}
11}

查看Bucket所属的区域

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

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

1location, err := bosClient.GetBucketLocation(bucketName)

新建Bucket

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

1// 新建Bucket的接口为PutBucket，需指定Bucket名称
2if loc, err := bosClient.PutBucket(<your-bucket-name>); err != nil {
3	fmt.Println("create bucket failed:", err)
4} else {
5	fmt.Println("create bucket success at location:", loc)
6}

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

Bucket的命名有以下规范：

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

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

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

新建lcc bucket

go sdk支持新建lcc bucket，用户可以在构造api.PutBucketArgs结构体，填入LccLocation，调用PutBucketWithArgs接口创建lcc bucket，api.PutBucketArgs具体参数如下：

参数	类型	说明
TagList	string	Bucket标签
EnableMultiAz	bool	是否开启多AZ
LccLocation	string	lcc id，用于创建lcc bucket到特定的lcc集群
EnableDedicated	bool	用于控制控制台开启lcc识别白名单

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

1//调用PutBucketWithArgs创建lcc bucket，需指定Bucket名称和lcc id
2putBucketArgs := &api.PutBucketArgs{}
3putBucketArgs.LccLocation = "<lcc id>"
4putBucketArgs.EnableDedicated = true
5if loc, err := bosClient.PutBucketWithArgs(<your-bucket-name>, putBucketArgs); err != nil {
6	fmt.Println("create lcc bucket failed:", err)
7} else {
8	fmt.Println("create lcc bucket success at location:", loc)
9}

列举Bucket

如下代码可以列出用户所有的Bucket：

1if res, err := bosClient.ListBuckets(); err != nil {
2	fmt.Println("list buckets failed:", err)
3} else {
4	fmt.Println("owner:", res.Owner)
5	for i, b := range res.Buckets {
6		fmt.Println("bucket", i)
7		fmt.Println("    Name:", b.Name)
8		fmt.Println("    Location:", b.Location)
9		fmt.Println("    CreationDate:", b.CreationDate)
10	}
11}

删除Bucket

如下代码可以删除一个Bucket：

1err := bosClient.DeleteBucket(bucketName)

注意：

在删除前需要保证此Bucket下的所有Object已经已被删除，否则会删除失败。

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

判断Bucket是否存在

若用户需要判断某个Bucket是否存在，则如下代码可以做到：

1exists, err := bosClient.DoesBucketExist(bucketName)
2if err == nil && exists {
3	fmt.Println("Bucket exists")
4} else {
5	fmt.Println("Bucket not exists")
6}

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

初始化

文件管理

百度智能云

BOS 对象存储