Bucket management

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.

Description:

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.

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

User settable CannedACL contains three values: private, public-read and public-read-write, which correspond to respective permissions. 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:

1// import "github.com/baidubce/bce-sdk-go/bce"
2// import "github.com/baidubce/bce-sdk-go/services/bos/api"
3 // 1. Directly upload ACL file stream
4aclBodyStream := bce.NewBodyFromFile("<path-to-acl-file>")
5err := bosClient.PutBucketAcl(bucket, aclBodyStream)
6 // 2. Directly use ACL json string
7aclString := `{
8    "accessControlList":[
9        {
10            "grantee":[{
11 "id":"e13b12d0131b4c8bae959df4969387b8" //Specify user ID
12            }],
13 "permission":["FULL_CONTROL"] //Specify user permissions
14        }
15    ]
16}`
17err := bosClient.PutBucketAclFromString(bucket, aclString)
18 // 3. Use ACL file
19err := bosClient.PutBucketAclFromFile(bucket, "<acl-file-name>")
20 // 4. Set using ACL struct object
21grantUser1 := api.GranteeType{"<user-id-1>"}
22grantUser2 := api.GranteeType{"<user-id-2>"}
23grant1 := api.GrantType{
24	Grantee: []api.GranteeType{grantUser1},
25	Permission: []string{"FULL_CONTROL"},
26}
27grant2 := api.GrantType{
28	Grantee: []api.GranteeType{granteUser2},
29	Permission: []string{"READ"},
30}
31grantArr := make([]api.GranteeType, 0)
32grantArr = append(grantArr, grant1)
33grantArr = append(grantArr, grant2)
34args := &api.PutBucketAclArgs{grantArr}
35err := bosClient.PutBucketAclFromStruct(bucketName, args)

Note: 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). ACL rules are relatively complex, and it is difficult to directly edit ACL files or JSON strings. Therefore, a fourth method is provided to facilitate the creation of ACL rules using code.

Set more bucket access permissions

1. Set anti-leech through referer allow list

   Go Copy

   1aclString := `{
   2    "accessControlList":[
   3        {
   4 "grantee":[{"id":"*"]},        //Specify user ID as all user
   5 "permission":["FULL_CONTROL"] //Specify user permissions
   6            "condition":[{"referer": {"stringEquals": "http://allowed-domain/"}}]
   7        }
   8    ]
   9}`
   10err := bosClient.PutBucketAclFromString(bucket, aclString)

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

   Go Copy

   1aclString := `{
   2    "accessControlList":[
   3        {
   4 "grantee":[{"id":"*"]},        //Specify user ID as all user
   5 "permission":["READ"],  //Specify user permissions
   6            "condition":[{"ipAddress": ["ip-1", "ip-2"]}]
   7        }
   8    ]
   9}`
   10err := bosClient.PutBucketAclFromString(bucket, aclString)

Set STS temporary token permissions

For temporary access credentials created via STS, administrators can also define 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).

To set STS temporary token permissions using BOS GO SDK, you can refer to the following example:

1// import "github.com/baidubce/bce-sdk-go/services/sts"
2AK, SK := <your-access-key-id>, <your-secret-access-key>
3stsClient, err := sts.NewClient(AK, SK)
4aclString := `{
5    "accessControlList":[
6        {
7 "grantee":[{"id":"*"]},        //Specify user ID as all user
8 "permission":["FULL_CONTROL"] //Specify user permissions
9            "condition":[{"referer": {"stringEquals": "http://allowed-domain/"}}]
10        }
11    ]
12}`
13 //Obtain a temporary STS token with a validity period of 300 seconds and specified ACL
14sts, err := stsClient.GetSessionToken(300, aclString)

View bucket access permissions

Users can check the bucket's access permissions using the following API. Note: Bucket access permissions cannot be removed and are private by default.

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

The fields of the returned result object contain detailed information about access permissions, with specific definitions as follows:

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}

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:

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

Create Bucket

The following code can be used to create a bucket:

1// The API for creating a new Bucket is PutBucket, and the Bucket name must be specified
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}

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.

• Create a new lcc bucket

The GO SDK supports creating new lcc buckets. Users can construct the api.PutBucketArgs structure, fill in LccLocation, and call the PutBucketWithArgs API to create an lcc bucket. The specific parameters of api.PutBucketArgs are as follows:

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

1// Call PutBucketWithArgs to create an lcc bucket, and the bucket name and lcc id must be specified
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}

List buckets

The following code can list all buckets of a user:

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}

Delete bucket

The following code can be used to delete a bucket:

1err := bosClient.DeleteBucket(bucketName)

Note:

• Before deleting a bucket, ensure all objects within it have been 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

If users need to determine whether a bucket exists, the following code can achieve this:

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

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.