对象存储列出对象-SDK 文档-文档中心-腾讯云

简介
本文介绍对象存储 COS 通过 C++ SDK 实现列出对象功能的示例代码和描述。
注意事项
若您要使用列出对象功能，需要先具有目标桶的读取权限：在您进行 授权策略 时，action 需要设置为 cos:GetBucket ，更多授权请参见 支持CAM的业务接口。
相关示例
功能名称
描述
示例代码
列出对象
提供了查询存储桶下的部分或者全部对象的功能。
﻿GitHub完整示例﻿
前期准备
创建 CosAPI
调用 COS 的接口之前，必须先创建一个 CosAPI 的实例。这个实例用来后续调用请求。
qcloud_cos::CosAPI InitCosAPI() {
    uint64_t appid = 12500000000;
    std::string region = "ap-guangzhou";// bucket 的地域，请参见 https://cloud.tencent.com/document/product/436/62
    std::string secret_id = "AKIDXXXXXXXX"; //用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
    std::string secret_key = "1A2Z3YYYYYYYYYY"; //用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
        
    qcloud_cos::CosConfig config(appid, secret_id, secret_key, region);
    qcloud_cos::CosAPI cos_tmp(config);
    return cos_tmp;
}
使用临时密钥创建 CosAPI
如果要使用临时密钥请求 COS，则需要用临时密钥创建 CosAPI 实例。
qcloud_cos::CosAPI InitCosAPI() {
    // 需要已经获取到临时密钥的结果：tmp_secret_id、tmp_secret_key、
    // 临时密钥的生成参见 https://cloud.tencent.com/document/product/436/14048#cos-sts-sdk
    uint64_t appid = 12500000000;
    std::string region = "ap-guangzhou";
    std::string tmp_secret_id = "AKIDXXXXXXXX";
    std::string tmp_secret_key = "1A2Z3YYYYYYYYYY";
    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;
}
使用案例
列出桶下对象
说明：
该 Demo 演示了如何使用 COS C++ SDK 列出桶下的对象。
可以指定列出对象名的前缀等请求参数信息，具体可以看下方请求体中的设置方法。
方法原型
CosResult CosAPI::GetBucket(const GetBucketReq& req, GetBucketResp* resp)
请求示例
void GetBucketDemo(qcloud_cos::CosAPI& cos) {
    qcloud_cos::GetBucketReq req(bucket_name);
    // 设置列出的对象名以 prefix 为前缀
    req.SetPrefix("test");
    // 设置最大列出多少个对象, 一次 listobject 最大支持1000
    req.SetMaxKeys(10);
    qcloud_cos::GetBucketResp resp;
    qcloud_cos::CosResult result = cos.GetBucket(req, &resp);

    std::cout << "===================GetBucketResponse=====================" << std::endl;
    if (result.IsSucc()) {
        // object contents 表示此次列出的对象列表
        std::vector<Content> contents = resp.GetContents();
        for (const Content& content : contents) {
            // 对象的 key
            std::string key = content.m_key;
            // 对象的 etag
            std::string etag = content.m_etag;
            // 对象的长度
            std::string file_size = content.m_size;
            // 对象的存储类型
            std::string storage_classes = content.m_storage_class;
            std::cout << "key:" << key << "\\netag:" << etag << "\\nfile_size:" << file_size << "\\nstorage_classes:" << storage_classes << std::endl;
            std::cout << "==================================" << std::endl;
        }
﻿
        if (resp.IsTruncated()) {
            // 表示还没有列完，被截断了
            // 下一次开始的位置
            std::string next_marker = resp.GetNextMarker();
            std::cout << "next_marker:" << next_marker << std::endl;
        }
    } else {
        std::cout << "GetBucket Fail, ErrorMsg: " << result.GetErrorMsg() << std::endl;
    }
    std::cout << "=========================================================" << std::endl;
}
参数说明
参数名称
描述
类型
req
列出对象请求
GetBucketReq
resp
列出对象响应
GetBucketResp
GetBucketReq 成员或函数说明：
成员或函数
描述
参数类型
bucket_name
存储桶名，可通过构造函数或 set 方法进行设置
存储桶的命名格式为 BucketName-APPID，详情请参见 命名规范﻿
string
SetPrefix
限制返回的结果对象，以 prefix 为前缀。不调用则不进行限制，即 Bucket 下所有的成员。
string
SetDelimiter
分隔符，限制返回的是以 prefix 开头，并以 delimiter 第一次出现的结束的路径
string
SetMarker
标记 list 的起点位置，第一次可设置为空，后续请求需设置为上一次 listObjects 返回值中的 nextMarker
string
SetMaxKeys
最大返回的成员个数（不得超过1000）。默认值： 1000
uint64_t
GetBucketResp 成员函数说明：
成员函数
描述
返回类型
GetContents
获取此次列出的对象列表，具体用法参考上方的请求示例
vector<Content>
IsTruncated
响应是否被截断，有截断返回 true，否则 false
bool
GetNextMarker
仅当响应有截断（IsTruncated 为 true）才会返回该节点，该节点的值为当前响应条目中的最后一个对象键，当需要继续请求后续条目时，将该节点的值作为下一次请求的 marker 参数传入
string
GetCommonPrefixes
从 prefix 或从头（如未指定 prefix）到首个 delimiter 之间相同的部分，定义为 Common Prefix。仅当请求中指定了 delimiter 参数才有可能返回该节点。
vector<std::string>
GetXCosRequestId
获取请求 ID
string
返回说明
CosResult 主要成员函数说明如下：
成员函数
描述
返回类型
IsSucc
判断是否成功，成功返回 true，失败返回 false。
bool
GetHttpStatus
获得 http 状态码。
int
GetErrorCode
请求失败时获取错误码。
string
GetErrorMsg
请求失败时获取错误信息。
string
GetXCosRequestId
获取请求 ID。
string
对 CosResult 的使用样例如下，用户可根据信息选择使用：
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 操作
关于列出对象的 API 接口说明，请参见 List Objects 文档。

功能名称	描述	示例代码
列出对象	提供了查询存储桶下的部分或者全部对象的功能。	GitHub完整示例

参数名称	描述	类型
req	列出对象请求	GetBucketReq
resp	列出对象响应	GetBucketResp

成员或函数	描述	参数类型
bucket_name	存储桶名，可通过构造函数或 set 方法进行设置存储桶的命名格式为 BucketName-APPID，详情请参见命名规范	string
SetPrefix	限制返回的结果对象，以 prefix 为前缀。不调用则不进行限制，即 Bucket 下所有的成员。	string
SetDelimiter	分隔符，限制返回的是以 prefix 开头，并以 delimiter 第一次出现的结束的路径	string
SetMarker	标记 list 的起点位置，第一次可设置为空，后续请求需设置为上一次 listObjects 返回值中的 nextMarker	string
SetMaxKeys	最大返回的成员个数（不得超过1000）。默认值： 1000	uint64_t

成员函数	描述	返回类型
GetContents	获取此次列出的对象列表，具体用法参考上方的请求示例	vector<Content>
IsTruncated	响应是否被截断，有截断返回 true，否则 false	bool
GetNextMarker	仅当响应有截断（IsTruncated 为 true）才会返回该节点，该节点的值为当前响应条目中的最后一个对象键，当需要继续请求后续条目时，将该节点的值作为下一次请求的 marker 参数传入	string
GetCommonPrefixes	从 prefix 或从头（如未指定 prefix）到首个 delimiter 之间相同的部分，定义为 Common Prefix。仅当请求中指定了 delimiter 参数才有可能返回该节点。	vector<std::string>
GetXCosRequestId	获取请求 ID	string

列出对象

本页目录：

简介

注意事项

相关示例

前期准备

创建 CosAPI

使用临时密钥创建 CosAPI

使用案例

列出桶下对象

方法原型

请求示例

参数说明

返回说明

API 操作