Overview

This document provides an overview of APIs and SDK code samples related to basic bucket operations.

Querying Bucket List

API description

This API is used to query the list of all buckets under a specified account.

Method prototype

CosResult GetService(const GetServiceReq& request, GetServiceResp* response)

Sample request

qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);

std::string bucket_name = "examplebucket-1250000000";

qcloud_cos::GetServiceReq req;
qcloud_cos::GetServiceResp resp;
qcloud_cos::CosResult result = cos.GetService(req, &resp);

// The call is successful. You can call the resp member functions to get the return content
if (result.IsSucc()) {
    const qcloud_cos::Owner& owner = resp.GetOwner();
    const std::vector<qcloud_cos::Bucket>& buckets = resp.GetBuckets();
    std::cout << "owner.m_id=" << owner.m_id << ", owner.display_name=" << owner.m_display_name << std::endl;               
     for (std::vector<qcloud_cos::Bucket>::const_iterator itr = buckets.begin(); itr != buckets.end(); ++itr) {
         const qcloud_cos::Bucket& bucket = *itr;
         std::cout << "Bucket name=" << bucket.m_name << ", location=" 
         << bucket.m_location << ", create_date=" << bucket.m_create_date << std::endl;                                  
     } 
} else {
    // You can call the CosResult member functions to output the error information, such as requestID
} 

Parameter description

GetServiceResp provides the following member functions to obtain the specific content (in XML format) returned by Get Service.

// Get bucket owner information
Owner GetOwner() const;
// Get list information for all buckets
std::vector<Bucket> GetBuckets() const

Owner is defined as follows:

struct Owner {
    std::string m_id;    // ID of the bucket owner
    std::string m_display_name; // Bucket owner name
}; 

Bucket is defined as follows:

// Describe the information of a single bucket                                                                                                                                                                    
struct Bucket {
    std::string m_name; // Bucket name
    std::string m_location; // Bucket region
    std::string m_create_date; // Creation time of the bucket, in ISO 8601 format, such as 2016-11-09T08:46:32.000Z
};

Creating a Bucket

API description

This API (PUT Bucket) is used to create a bucket.

Method prototype

CosResult PutBucket(const PutBucketReq& req, PutBucketResp* resp)

Sample request

qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);

std::string bucket_name = "examplebucket-1250000000";

qcloud_cos::PutBucketReq req(bucket_name);
qcloud_cos::PutBucketResp resp;
qcloud_cos::CosResult result = cos.PutBucket(req, &resp);

// The call is successful. You can call the resp member functions to get the return content
if (result.IsSucc()) {
    // ...
} else {
    // You can call the CosResult member functions to output the error information, such as requestID
} 

Parameter description

PutBucketReq provides the following member functions:

// Define the ACL attribute of the bucket. Valid values: private, public-read-write, public-read
// Default: private
void SetXCosAcl(const std::string& str);

// Grant read permission in the format: x-cos-grant-read: id=" ",id=" ".
// To authorize a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
// To authorize the root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
void SetXCosGrantRead(const std::string& str);

// Grant write permission in the format: x-cos-grant-write: id=" ",id=" "./
// To authorize a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>",
// To authorize the root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
void SetXCosGrantWrite(const std::string& str);
    
// Grant read-write permission in the format: x-cos-grant-full-control: id=" ",id=" ".
// To authorize a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>",
// To authorize the root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
void SetXCosGrantFullControl(const std::string& str);

Checking a Bucket and Its Permissions

API description

This API is used to verify whether a bucket exists and you have permission to access it.

Method prototype

CosResult HeadBucket(const HeadBucketReq& req, HeadBucketResp* resp)

Sample request

qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);

std::string bucket_name = "examplebucket-1250000000";

qcloud_cos::HeadBucketReq req(bucket_name);
qcloud_cos::HeadBucketResp resp;
qcloud_cos::CosResult result = cos.HeadBucket(req, &resp);

// The call is successful. You can call the resp member functions to get the return content
if (result.IsSucc()) {
    // ...
} else {
    // You can call the CosResult member functions to output the error information, such as requestID
} 

Parameter description

Deleting a Bucket

API description

This API (DELETE Bucket) is used to delete an empty bucket under a specified account.

Method prototype

CosResult DeleteBucket(const DeleteBucketReq& req, DeleteBucketResp* resp)

Sample request

qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);

std::string bucket_name = "examplebucket-1250000000";

// The bucket_name is required in the constructor of DeleteBucketReq
qcloud_cos::DeleteBucketReq req(bucket_name);
qcloud_cos::DeleteBucketResp resp;
qcloud_cos::CosResult result = cos.DeleteBucket(req, &resp);

// The call is successful. You can call the resp member functions to get the return content
if (result.IsSucc()) {
    // ...
} else {
    // You can call the CosResult member functions to output the error information, such as requestID
} 

Parameter description