Bucket Management
Bucket is not only a namespace on BOS, but also a management entity with advanced features such as billing, permission control and logging.
-
Bucket names are globally unique in all regions and cannot be modified
Note: Baidu AI Cloud currently has opened access to multi-region support, please refer to Region Selection Description.
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 Permission Management
Set Access Permissions of Bucket
The following code sets the permissions of bucket private.
int setBucketPrivate (Client& client, const std::string& bucketName) {
PutBucketAclRequest request(bucketName, "private");//第二个参数为CannedACL
PutBucketAclResponse response;
int ret = client.put_bucket_acl(request, &response);
//client error
if (ret != 0) {
return ret;
}
//response errro
if (response.is_fail()) {
printf("error-message:%s\n", response.error().message().c_str());
return response.status_code();
}
return 0;
}CannedACL contains three values: private, public-read, public-read-write . They correspond to the respective permissions. For specific contents, Please see BOS API Document Privilege Control Through CannedAcl.
View Permissions of Bucket
The following code can view the permissions of bucket:
GetBucketAclRequest("bucketName");
GetBucketAclResponse response;
int ret = client.get_bucket_acl(request, &response);
if (response.is_fail()) {
printf("error-message:%s\n", response.error().message().c_str());
return;
}
std::string owner_id = reponse.owner().id;
std::cout << "owner_id: " << owner_id << std::endl;
for (const Grant& grant : response.access_control_list()) {//c++11
do_something(grant);
} The parameters available for calling in the response returned by the get_bucket_acl method include:
| Parameter | Type | Description |
|---|---|---|
| owner | Owner(string) | bucket owner id |
| access_control_list | vector\<Grant> | Container holding acl |
| +grantee | vector\<string> | Authorized person ID. |
| +permission | vector\<string> | Identify the permission of the authorized person. |
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:
Client client (ak, sk, config);
ListBucketsRequest listBucketsRequest;
ListBucketsResponse listBucketsResponse;
int ret = client.list_buckets(listBucketsRequest, &listBucketsResponse)
std::vector<BucketSummary> bucketSummaryList = listBucketsResponse.buckets();
if (listBucketsResponse.is_fail()) {
printf("error-message:%s\n", listBucketsResponse.error().message().c_str());
return ;
}
for(const BucketSummary& bs : bucketSummaryList){
std::cout << "name: " << bs.name <<
" location: " << bs.location << std::endl;
}
GetBucketLocationRequest getBucketLocationRequest("bucketName");
GetBucketLocationResponse getBucketLocationResponse;
ret = client.get_bucket_location(getBucketLocationRequest,
&getBucketLocationResponse);
if (getBucketLocationResponse.is_fail()) {
printf("error-message:%s\n", response.error().message().c_str());
return;
}
std::cout << "location: " << getBucketLocationResponse.location() << std::endl;Create Bucket
The following code can create bucket:
int createBucket (Client& client, const std::string& bucketName) {
// Create Bucket
PutBucketRequest request(bucketName);
PutBucketResponse response;
int ret = client.put_bucket(request, &response);
if (ret !=0) {
return ret;
}
if (response.is_fail()) {
printf("error-message:%s\n", response.error().message().c_str());
}
return ret;
}
int main() {
std::sting ak = "ak";
std::string sk = "sk";
Client client(ak, sk);
int ret = createBucket(client, "bucketName");
std::string ret_info = stringfy_ret_code(ret);
std::cout << ret_info << std::endl;
}Note: Since the name of the bucket is unique in all regions, you need to make sure that the BucketName is different from that on 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.
The bucket created by the above code has private read and write permissions and the storage type is Standard.
Enumerate Bucket
The following code can list all the users' buckets:
int listBuckets (Client& client) {
// Get the user's bucket list
ListBucketsRequest listBucketsRequest;
ListBucketsResponse listBucketsResponse;
int ret = client.list_buckets(listBucketsRequest, &listBucketsResponse)
std::vector<BucketSummary> bucketSummaryList = listBucketsResponse.buckets();
if (listBucketsResponse.is_fail()) {
printf("error-message:%s\n", listBucketsResponse.error().message().c_str());
return ret;
}
// Traverse all buckets
for(const BucketSummary& bs : bucketSummaryList){
std::cout << "bucketName: " << bs.name << std::endl;
}
return ret;
} Delete Bucket
The following code can delete a bucket:
int deleteBucket (Client& client, const std::string& bucketName) {
// Delete Bucket
DeleteBucketRequest request(bucketName);
DeleteBucketResponse response;
int ret = client.delete_bucket(request, &response);
if (response.is_fail()) {
printf("error-message:%s\n", listBucketsResponse.error().message().c_str());
}
return ret;
}Note:
- Before deleting, you need to make sure that all objects under this bucket and the unfinished three-step upload Parts have been deleted, otherwise, the 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:
//0 means check succeeded and bucket exists.
//1 means absence of bucket.
//other means other errors, given by error-message.
int checkBucketExist (Client& client, const std:string& BucketName) {
bool exist = false;
// Obtain the presence information of the bucket
HeadbucketRequest request(BucketName);
HeadBucketResponse response;
int ret = client.head_bucket(request, &response);
if (response.is_fail() && response.status_code() != 404){
printf("error-message:%s\n", response.error().message().c_str());
return ret;
} else if (response.status_code() == 404){
return -1;
}
//200 ok
return 0;
} 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.