tencent cloud

Cloud Object Storage

DocumentationCloud Object StorageSDK DocumentationC++ SDKObject operationsHEAD Object

HEAD Object

PDF
Focus Mode
Font Size
Last updated: 2026-03-05 16:59:56

Introduction

This document describes the sample code and description for implementing querying object metadata via the c++ SDK in COS.

Must-Knows

If you want to query the metadata of the target object, you need to have read permission for the target object: when you configure the authorization policy, the action needs to be set to cos:HeadObject. For more authorization, see business APIs that support CAM.

Related Examples

Function Name
Description
Example code
Querying Metadata of Objects
Provides the feature of querying object metadata.

Preliminary Preparation

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

Querying Metadata of Objects

Query the metadata of the specified object (HEAD Object).

Method Prototype

CosResult CosAPI::HeadObject(const HeadObjectReq& req, HeadObjectResp* resp)

Request Example

void HeadObjectDemo(qcloud_cos::CosAPI& cos) {
    std::string object_name = "test.txt";
    qcloud_cos::HeadObjectReq req(bucket_name, object_name);
    qcloud_cos::HeadObjectResp resp;
    qcloud_cos::CosResult result = cos.HeadObject(req, &resp);


    std::cout << "===================HeadObjectResponse=====================" << std::endl;
    std::map<std::string, std::string> cos_metas = resp.GetXCosMetas();  // obtain the custom metadata map
    std::string cos_meta = resp.GetXCosMeta("x-cos-meta-*");             // Obtain the specified custom metadata
    std::string restore = resp.GetXCosRestore();                         // Get the current restoration status of the archive-type object
    std::string sse = resp.GetXCosServerSideEncryption();                // Server-side encryption algorithm used
    PrintResult(result, resp);
    std::cout << "==========================================================" << std::endl;
}

Parameter Description

Parameter Name
Description
Type
req
Head request
HeadObjectReq
resp
Head response
HeadObjectResp
HeadObjectReq Member or Function Description:
Member or Function
Description
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
object_name
Object key (Key), which can be set via the constructor or set method.
is the unique identifier of the object in the bucket. For example, in the object access domain name examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg, the object key is doc/picture.jpg. For details, see Object Key
string
HeadObjectResp Member Function Description:
Member functions
Description
Return Type
GetXCosMetas
Obtain the custom metadata map.
map<std::string, std::string>
GetXCosMeta
Obtain the specified custom metadata
string
GetXCosRestore
Obtain the current restoration status of the archive-type object.
string
GetXCosServerSideEncryption
Obtain the server-side encryption algorithm used
string
GetEtag
Obtain the Etag of the stored object.
string
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
The error code can be obtained 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 API description related to querying object metadata, see the HEAD Object document.
Previous Topic: Verify Object ExistenceNext Topic: Object Access URL

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback