Bucket Management
Bucket is not only a namespace on BOS, but also a management entity with advanced features such as billing, privilege control and logging.
- Buckets names are globally unique in all regions and cannot be modified
Note:
Baidu AI Cloud opens multi-region support, please see Region Selection Introduction Currently, it supports "North China-Beijing", "South China-Guangzhou" and "East China-Suzhou". Beijing:
http://bj.bcebos.com; Guangzhou:http://gz.bcebos.com; Suzhou:http://su.bcebos.com.
- Each object stored on the BOS must be contained in a bucket.
- A user can create up to 100 buckets. However, there is no limit on the total number and size of objects stored in each bucket, so users do not need to consider the extensibility of data.
Bucket Privilege Management
Set Access Privilege of Bucket
The following code sets the privileges of bucket private.
err := bosClient.PutBucketAclFromCanned(bucketName, "private") The CannedACL that can be set by users contains 3 values: private, public-read, public-read-write. They correspond to the respective privileges. For specific contents, Please see BOS API Document Privilege Control through CannedAcl.
Set the Specified User's Access to the Bucket
BOS can also set the access privilege of specified users to bucket, see the following codes:
// import "github.com/baidubce/bce-sdk-go/bce"
// import "github.com/baidubce/bce-sdk-go/services/bos/api"
// 1.Upload ACL file stream directly
aclBodyStream := bce.NewBodyFromFile("<path-to-acl-file>")
err := bosClient.PutBucketAcl(bucket, aclBodyStream)
// 2.Use ACL json string directly
aclString := `{
"accessControlList":[
{
"grantee":[{
"id":"e13b12d0131b4c8bae959df4969387b8" //Specify user ID
}],
"privilege":["FULL_CONTROL"] //Specify user privilege
}
]
}`
err := bosClient.PutBucketAclFromString(bucket, aclString)
// 3. Use ACL file
err := bosClient.PutBucketAclFromFile(bucket, "<acl-file-name>")
// 4. Use ACL struct object setting
grantUser1 := api.GranteeType{"<user-id-1>"}
grantUser2 := api.GranteeType{"<user-id-2>"}
grant1 := api.GrantType{
Grantee: []api.GranteeType{grantUser1},
privilege: []string{"FULL_CONTROL"}
}
grant2 := api.GrantType{
Grantee: []api.GranteeType{granteUser2},
privilege: []string{"READ"}
}
grantArr := make([]api.GranteeType)
grantArr = append(grantArr, grant1)
grantArr = append(grantArr, grant2)
args := &api.PutBucketAclArgs{grantArr}
err := bosClient.PutBucketAclFromStruct(bucketName, args)Note: The privilege setting in privilege contains 3 values:
READ,WRITEandFULL_CONTROL, corresponding to respective privileges. For the specific contents, please see BOS API Document Privilege Control Through ACL File Uploading. ACL rules are complex, and it is difficult to directly edit ACL file or JSON string, so the fourth mode is provided to create ACL rules with code.
Set More Bucket Access Privileges
1.Set an anti-theft chain by using referrer whitelist
aclString := `{
"accessControlList":[
{
"grantee":[{"id":"*"]}, //Specify user ID as all users
"privilege":["FULL_CONTROL"], //Specify user privilege
"condition":[{"referer": {"stringEquals": "http://allowed-domain/"}}]
}
]
}`
err := bosClient.PutBucketAclFromString(bucket, aclString)2.Limit client IP access, and only allow a few client IP accesses
aclString := `{
"accessControlList":[
{
"grantee":[{"id":"*"]}, //Specify user ID as all users
"privilege":["READ"], //pecify user privilege
"condition":[{"ipAddress": ["ip-1", "ip-2"]}]
}
]
}`
err := bosClient.PutBucketAclFromString(bucket, aclString)Set STS Temporary Token Privilege
For the temporary access identity created by STS, the administrator also can set a special privilege.
See Temporary Authorized Access for introduction of STS and the mode of setting temporary privilege.
See the following example for setting of STS temporary token privilege with BOS GO SDK:
// import "github.com/baidubce/bce-sdk-go/services/sts"
AK, SK :=<your-access-key-id>,<your-secret-access-key>
stsClient, err := sts.NewClient(AK, SK)
aclString := `{
"accessControlList":[
{
"grantee":[{"id":"*"]}, //Specify user ID as all users
"privilege":["FULL_CONTROL"], //Specify user privilege
"condition":[{"referer": {"stringEquals": "http://allowed-domain/"}}]
}
]
}`
//The valid term of use is 300 sec, and ACL mode is specified to obtain temporary STS token.
sts, err := stsClient.GetSessionToken(300, aclString) View the Access privilege of Bucket
Users can view the access privilege of bucket via the following interfaces. Note: The access privilege of bucket cannot be deleted, and is private by default.
result, err := bosClient.GetBucketAcl(BucketName) The fields of result object returned contain the detailed contents of access privilege, and they are specifically defined as follows:
type GetBucketAclResult struct {
AccessControlList []struct{
Grantee []struct {
Id string
}
privilege []string
}
Owner struct {
Id string
}
} View the Region to Which the Bucket Belongs
Bucket Location is bucket Region. For details of each region supported by Baidu AI Cloud, please see Region Selection Description.
The following code can get the Location information of this bucket:
location, err := bosClient.GetbucketLocation(BucketName) Create Bucket
The following code can create a bucket:
// The interface of created bucket is Putbucket, and bucket name needs to be specified.
if loc, err := bosClient.Putbucket(<your-bucket-name>); err != nil {
fmt.Println("create bucket failed:", err)
} else {
fmt.Println("create bucket success at location:", loc)
} Note: The name of bucket is unique in all regions, so you need to guarantee that bucketName is not the same with the name of bucket in all other regions.
bucket has the following naming specifications:
- Only lowercase letters, numbers and dashes (-) can be included.
- It must begin with a lowercase letter or number.
- The length must be between 3 and 63 bytes.
Enumerate Bucket
The following code can list all the users' buckets:
if res, err := bosClient.ListBuckets(); err != nil {
fmt.Println("list buckets failed:", err)
} else {
fmt.Println("owner:", res.Owner)
for i, b := range res.Buckets {
fmt.Println("bucket", i)
fmt.Println(" Name:", b.Name)
fmt.Println(" Location:", b.Location)
fmt.Println(" CreationDate:", b.CreationDate)
}
} Delete Bucket
The following code can delete a bucket:
err := bosClient.DeleteBucket(BucketName) Note:
- Before deletion, guarantee that all objects under the bucket have been deleted, otherwise, deletion will fail.
- Before deleting bucket, you make sure that the bucket does not enable cross-region replication. It is not the source bucket or target bucket in the cross-region replication rule, otherwise it cannot be deleted.
Judge whether a Bucket Exists or Not
To judge whether a bucket exists, you need to do with the following code:
exists, err := bosClient.DoesBucketExist(bucketName)
if err == nil && exists {
fmt.Println("Bucket exists")
} else {
fmt.Println("Bucket not exists")
}Note: If the bucket is not null (i.e. bucket has object), the bucket cannot be deleted and must be emptied to be deleted successfully.