tencent cloud

PUT Bucket
Download PDF
Last updated:2026-03-03 18:07:34
PUT Bucket
Last updated: 2026-03-03 18:07:34
Download PDF

Introduction

This document provides an overview of the API for creating a bucket and SDK sample code.

Must-Knows

Before performing bucket-related operations, you need to have the relevant permissions:
If you want to create a bucket, when setting the authorization policy, set action to cos:PutBucket. For more authorization information, see CAM-Supported Service APIs.

Related Examples

Function Name
Description
Example code
Creating a Bucket
Create a bucket under a specified account.

Preliminary Preparation

Using Permanent Key to Create CosAPI

Before calling the COS API, you must first create an instance of CosAPI for subsequent call requests.
qcloud_cos::CosAPI InitCosAPI() {
    uint64_t appid = 12500000000;
    std::string region = "ap-guangzhou";// Region of the bucket, see https://www.tencentcloud.com/document/product/436/62?from_cn_redirect=1
    std::string secret_id = "************************************"; // User's SecretId. It is recommended to use sub-account keys, with authorization following the least privilege principle to mitigate usage risks. For information on how to obtain sub-account keys, see https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
    std::string secret_key = "************************************"; // User's SecretKey. It is recommended to use sub-account keys, with authorization following the least privilege principle to mitigate usage risks. For information on how to obtain sub-account keys, see https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
        
    qcloud_cos::CosConfig config(appid, secret_id, secret_key, region);
    qcloud_cos::CosAPI cos_tmp(config);
    return cos_tmp;
}

Create CosAPI Using a Temporary Key

To access COS with a temporary key, you need to create a CosAPI instance using the temporary key.
qcloud_cos::CosAPI InitCosAPI() {
    // You need to have obtained the temporary key results: tmp_secret_id, tmp_secret_key,
    // For generating temporary keys, see https://www.tencentcloud.com/document/product/436/14048?from_cn_redirect=1#cos-sts-sdk
    uint64_t appid = 12500000000;
    std::string region = "ap-guangzhou";
    std::string tmp_secret_id = "************************************";
    std::string tmp_secret_key = "************************************";
    std::string tmp_token = "token";
    
    qcloud_cos::CosConfig config(appid, tmp_secret_id, tmp_secret_key, region);
    config.SetTmpToken(tmp_token);
    qcloud_cos::CosAPI cos_tmp(config);
    return cos_tmp;
}

Use Cases: Create Bucket

Create a bucket under a specified account. Under the same user account, multiple buckets can be created, with a limit of 200 (regardless of region), and there is no limit on the number of objects in a bucket.
Note:
Creating a Bucket is an infrequent operation. It is generally recommended to create Buckets in the console and perform Object operations in the SDK.

Method Prototype

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

Request Example

void PutBucket(qcloud_cos::CosAPI& cos) {
    qcloud_cos::PutBucketReq req(bucket_name);
    // Create an MAZ bucket. Call the function below to set it up.
    //req.SetMAZBucket();
    qcloud_cos::PutBucketResp resp;
    qcloud_cos::CosResult result = cos.PutBucket(req, &resp);
  
    std::cout << "===================PutBucketResponse====================="
              << std::endl;
    PrintResult(result, resp);
    std::cout << "========================================================="
              << std::endl;
}

Parameter Description

Parameter Name
Description
Type
req
Bucket Creation Request.
PutBucketReq
resp
Bucket Creation Response.
PutBucketResp
PutBucketReq Member or Function Description:
Member or Function
Description
Parameter Type
bucket_name
Bucket name, which can be set via the constructor or set method.
The naming format for buckets is BucketName-APPID. For details, see Naming Conventions.
string
SetMAZBucket
Create an MAZ bucket.
string
PutBucketResp Member or Function Description:
Member or Function
Description
Parameter Type
GetXCosRequestId
Obtain the request ID.
string

Returning Description

CosResult key member function description:
Member functions
Description
Return Type
IsSucc
Indicates whether the operation is successful; returns true for success, false for failure.
bool
GetHttpStatus
Get the http status code.
int
GetErrorCode
Obtain the error code when the request fails.
string
GetErrorMsg
Obtain the error message when the request fails.
string
GetXCosRequestId
Obtain the request ID.
string
Usage examples for CosResult are as follows. Users may choose to utilize them based on their needs:
void PrintResult(const qcloud_cos::CosResult& result, const qcloud_cos::BaseResp& resp) {
    if (result.IsSucc()) {
        std::cout << "Request Succ." << std::endl;
        std::cout << resp.DebugString() << std::endl;
    } else {
        std::cout << "ErrorMsg=" << result.GetErrorMsg() << std::endl;
        std::cout << "HttpStatus=" << result.GetHttpStatus() << std::endl;
        std::cout << "ErrorCode=" << result.GetErrorCode() << std::endl;
        std::cout << "ErrorMsg=" << result.GetErrorMsg() << std::endl;
        std::cout << "ResourceAddr=" << result.GetResourceAddr() << std::endl;
        std::cout << "XCosRequestId=" << result.GetXCosRequestId() << std::endl;
        std::cout << "XCosTraceId=" << result.GetXCosTraceId() << std::endl;
    }
}

API Operations

For the description of the API for creating a bucket, see the PUT Bucket document.
Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback