tencent cloud

Cloud Object Storage

DocumentaçãoCloud Object StorageSDK DocumentationC++ SDKBucket operationsHEAD Bucket

HEAD Bucket

PDF
Modo Foco
Tamanho da Fonte
Última atualização: 2026-03-06 11:08:54

Introduction

This document provides an overview of APIs for checking a buckets and sample code for SDKs.

Must-Knows

Before performing bucket-related operations, you need to have the relevant permissions:
If you want to check a bucket, when the authorization policy is set up, action needs to be set to cos:HeadBucket. For more authorization, see business APIs that support CAM.

Related Examples

Function Name
Description
Example code
Head Bucket
Checks whether a bucket exists and you have permission to access it

Preliminary Preparation

Using Permanent Key to Create CosAPI

Before calling the COS API, you must first create an instance of CosAPI to make 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: Head Bucket

Checks whether a bucket exists and whether you have permission to access it.

Method Prototype

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

Request Example

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

  std::cout << "===================HeadBucketResponse====================="
            << std::endl;
  PrintResult(result, resp);
  std::cout << "=========================================================="
            << std::endl;
}

Parameter Description

Parameter Name
Description
Type
req
Head bucket request.
HeadBucketReq
resp
Head bucket response.
HeadBucketResp
HeadBucketReq 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
HeadBucketResp Member or Function Description:
Member or Function
Description
Parameter Type
GetXCosRequestId
Obtain the request ID.
string

Returning Description

CosResult main member functions are as follows:
Member functions
Description
Return Type
IsSucc
Indicates whether the operation is successful; returns true for success, false for failure.
bool
GetHttpStatus
Obtain 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 checking a buckets, see the HEAD Bucket document.

Anterior: GET ServicePróximo: Check Bucket Existence

Ajuda e Suporte

Esta página foi útil?

comentários