tencent cloud

Feedback

Bucket Operations

Last updated: 2022-05-25 15:43:19

    Overview

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

    API Operation Description
    GET Service (List Buckets) Querying a bucket list Queries the list of all buckets under a specified account
    PUT Bucket Creating a bucket Creates a bucket under a specified account
    HEAD Bucket Checking a bucket and its permissions Checks whether a bucket exists and whether you have permission to access it
    DELETE Bucket Deleting a bucket Deletes an empty bucket from a specified account

    Querying a Bucket List

    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"; // Bucket name in the format of BucketName-APPID (APPID is required), which can be viewed in the COS console at https://console.intl.cloud.tencent.com/cos5/bucket. Replace it with your bucket name.
    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

    Parameter Description Type Required
    req Request of the GetService operation GetServiceReq Yes
    resp Response of the GetService operation GetServiceResp Yes

    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

    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"; // Bucket name in the format of BucketName-APPID (APPID is required), which can be viewed in the COS console at https://console.intl.cloud.tencent.com/cos5/bucket. Replace it with your bucket name.
    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

    Parameter Description Type Required
    req Request of the PutBucket operation PutBucketReq Yes
    resp Response of the PutBucket operation PutBucketResp Yes

    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 of 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 of 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 of 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

    Description

    This API is used to verify whether a bucket exists and whether 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"; // Bucket name in the format of BucketName-APPID (APPID is required), which can be viewed in the COS console at https://console.intl.cloud.tencent.com/cos5/bucket. Replace it with your bucket name.
    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

    Parameter Description Type Required
    req Request of the HeadBucket operation HeadBucketReq Yes
    resp Response of the HeadBucket operation HeadBucketResp Yes

    Deleting a Bucket

    Description

    This API 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"; // Bucket name in the format of BucketName-APPID (APPID is required), which can be viewed in the COS console at https://console.intl.cloud.tencent.com/cos5/bucket. Replace it with your bucket name.
    // 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

    Parameter Description Type Required
    req Request of the DeleteBucket operation DeleteBucketReq Yes
    resp Response of the DeleteBucket operation DeleteBucketResp Yes
    Contact Us

    Contact our sales team or business advisors to help your business.

    Technical Support

    Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

    7x24 Phone Support