对象存储
有奖：腾讯混元大模型征文大赛邀您参加！> HOT
文档中心>对象存储>SDK 文档>C++ SDK>对象操作>上传对象

上传对象

最近更新时间：2024-08-13 16:19:51

我的收藏

本页目录：

简介

本文介绍对象存储 COS 通过 C++ SDK 实现上传对象功能的示例代码和描述。包括高级接口、简单接口、异步高级接口、异步简单接口、分块上传五个部分。

注意事项

若您使用简单上传，需要具有目标对象的写权限：在您进行 授权策略 时，action 需要设置为cos:PutObject ，更多授权请参见 支持CAM的业务接口。
若您使用高级接口的自动分块上传或使用简单接口实现分块上传，需要具有目标对象的初始化分块上传、上传分块、完成分块上传的权限：在您进行 授权策略 时，action 需要设置为 cos:InitiateMultipartUpload，cos:UploadPart，cos:CompleteMultipartUpload，更多授权请参见 支持CAM的业务接口。
若您使用高级接口的断点续传，需要具有目标对象的初始化分块上传、上传分块、完成分块上传、列举分块上传任务、列举已上传分块的权限：在您进行 授权策略 时，action 需要设置为 cos:InitiateMultipartUpload，cos:UploadPart，cos:CompleteMultipartUpload，cos:ListMultipartUploads，cos:ListParts更多授权请参见 支持CAM的业务接口。

相关示例

功能名称
描述
示例代码
高级接口
高级接口封装了分块上传接口，多线程并发同时上传多个分块，同时支持断点续传功能，仅支持本地文件上传，不支持流类型上传。
简单接口
PUT Object 接口可以上传一个对象至指定存储桶中，不支持多线程和断点续传，支持本地文件和流类型上传，最大支持上传不超过5GB的对象，5GB以上对象请使用 分块上传 或 高级接口 上传。
异步高级接口
异步高级接口封装了分块上传接口，多线程并发同时上传多个分块，支持断点续传、进度回调和上传状态回调功能，仅支持本地文件上传，不支持流类型上传。
异步简单接口
异步简单接口封装了简单上传接口，支持本地文件和流类型上传，支持进度回调和上传状态回调功能，最大支持上传不超过5GB的对象。不支持多线程和断点续传，
分块操作
分块上传可以实现将整个对象切分为多个分块，然后再将这些分块上传到对象存储（Cloud Object Storage，COS）。该操作需要用户自行组合调用初始化、上传、完成分块接口。

高级接口（推荐）

注意：
仅支持文件上传，不支持流式上传。
高级接口会多线程并发同时上传多个分块。
分块大小支持用户自行配置，默认为10MB。
上传线程池大小支持用户自行配置，默认5。

前期准备：创建 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 示范如何使用高级上传接口进行对象上传。
仅支持文件上传，不支持流式上传，内部封装了分块上传的各接口。
可通过全局设置上传线程池大小、分块大小。该上传线程池是每次上传独立的。

方法原型

CosResult CosAPI::MultiPutObject(const MultiPutObjectReq& req, MultiPutObjectResp* resp)

请求示例

void MultiUploadObjectDemo(qcloud_cos::CosAPI& cos) {
    std::string local_file = "test_file/big_file.txt";
    std::string object_name = "big_file.txt";
    // 此配置是全局性配置，主动设置后，后续的涉及多线程的上传接口，都使用此配置
    CosSysConfig::SetUploadThreadPoolSize(5);           // 上传线程池大小 默认5
    CosSysConfig::SetUploadPartSize(10 * 1024 * 1024);  // 上传分块大小 默认10M

    qcloud_cos::MultiPutObjectReq req(bucket_name, object_name, local_file);
    qcloud_cos::MultiPutObjectResp resp;
    qcloud_cos::CosResult result = cos.MultiPutObject(req, &resp);

    std::cout << "===================MultiUploadObject=======================" << std::endl;
    if (result.IsSucc()) {
        std::cout << "MultiUpload Succ." << std::endl;
        std::cout << resp.GetLocation() << std::endl;
        std::cout << resp.GetKey() << std::endl;
        std::cout << resp.GetBucket() << std::endl;
        std::cout << resp.GetEtag() << std::endl;
    } else {
        std::cout << "MultiUpload Fail." << std::endl;
        // 获取具体失败在哪一步
        std::string resp_tag = resp.GetRespTag();
        if ("Init" == resp_tag) {
            // print result
        } else if ("Upload" == resp_tag) {
            // print result
        } else if ("Complete" == resp_tag) {
            // print result
        }
        PrintResult(result, resp);
    }
    std::cout << "===========================================================" << std::endl;
}

参数说明

参数名称
描述
类型
req
上传文件请求
MultiPutObjectReq
resp
上传文件响应
MultiPutObjectResp
MultiPutObjectReq 成员或函数说明：
成员或函数
描述
参数类型
bucket_name
存储桶名，可通过构造函数或 set 方法进行设置
存储桶的命名格式为 BucketName-APPID，详情请参见 命名规范
string
object_name
对象键（Key），可通过构造函数或 set 方法进行设置
是对象在存储桶中的唯一标识。例如，在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中，对象键为 doc/picture.jpg，详情请参见 对象键
string
local_file_path
本地文件路径，可通过构造函数或 set 方法进行设置
string
SetXCosStorageClass
设置存储类型，设置方法为 req.SetXCosStorageClass("xxxx")
string
MultiPutObjectResp 成员函数说明：
成员函数
描述
返回类型
GetRespTag
获取失败环节： Init或Upload或Complete
string
GetXCosServerSideEncryption
获取 Server 端加密使用的算法
string
GetEtag
获取存储对象的 Etag
string
GetXCosRequestId
获取请求 ID

CosSysConfig 类用于进行相关的配置，在该样例中主要成员函数说明如下：
成员函数
描述
参数类型
SetUploadPartSize
设置分块上传的块大小，单位：字节（Byte），默认为10MB
设置方法为 CosSysConfig::SetUploadPartSize(10 * 1024 * 1024)
uint64_t
SetUploadThreadPoolSize
设置上传线程池大小，默认为5。
设置方法为 CosSysConfig::SetUploadThreadPoolSize(5)
unsigned

返回说明

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;
    }
}

简单接口

前期准备：创建 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 进行本地文件的简单上传。
最大支持上传不超过5GB的对象。

方法原型

CosAPI::PutObject(const PutObjectByFileReq& req, PutObjectByFileResp* resp)

请求示例

void PutObjectByFileDemo(qcloud_cos::CosAPI& cos) {
    std::string object_name = "test.txt";
    std::string file_path = "./test_file/text.txt";
    qcloud_cos::PutObjectByFileReq req(bucket_name, object_name, file_path);
    // 限速上传对象，默认单位为 bit/s，限速值设置范围为 819200 - 838860800
    // uint64_t traffic_limit = 0;
    // req.SetTrafficLimit(traffic_limit);
    qcloud_cos::PutObjectByFileResp resp;
    qcloud_cos::CosResult result = cos.PutObject(req, &resp);

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

参数说明

参数名称
描述
类型
req
上传文件请求
PutObjectByFileReq
resp
上传文件响应
PutObjectByFileResp
PutObjectByFileReq 成员或函数说明：
成员或函数
描述
参数类型
bucket_name
存储桶名，可通过构造函数或 set 方法进行设置
存储桶的命名格式为 BucketName-APPID，详情请参见 命名规范
string
object_name
对象键（Key），可通过构造函数或 set 方法进行设置
是对象在存储桶中的唯一标识。例如，在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中，对象键为 doc/picture.jpg，详情请参见 对象键
string
local_file_path
本地文件路径，可通过构造函数或 set 方法进行设置
string
SetXCosStorageClass
设置存储类型，设置方法为 req.SetXCosStorageClass("xxxx")
string
SetTrafficLimit
设置单链接限速，设置方法为 req.SetTrafficLimit(819200)，默认单位为 bit/s，限速值设置范围为 819200 - 838860800
uint64_t
PutObjectByFileResp 成员函数说明：
成员函数
描述
返回类型
GetVersionId
获取 Object 的版本号, 如果 Bucket 未开启多版本, 返回空字符串
string
GetXCosServerSideEncryption
获取 Server 端加密使用的算法
string
GetEtag
获取存储上传对象的 Etag
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;
    }
}

使用案例：上传流类型

说明：
该 Demo 演示了如何使用 COS C++ SDK 进行流类型的简单上传。
最大支持上传不超过5GB的对象。

方法原型

CosResult CosAPI::PutObject(const PutObjectByStreamReq& req, PutObjectByStreamResp* resp)

请求示例

void PutObjectByStreamDemo(qcloud_cos::CosAPI& cos) {
    std::istringstream iss("put object");
    std::string object_name = "text.txt";
    qcloud_cos::PutObjectByStreamReq req(bucket_name, object_name, iss);
    // 限速上传对象，默认单位为 bit/s，限速值设置范围为 819200 - 838860800
    // uint64_t traffic_limit = 0;
    // req.SetTrafficLimit(traffic_limit);
    qcloud_cos::PutObjectByStreamResp resp;
    qcloud_cos::CosResult result = cos.PutObject(req, &resp);



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

参数说明

参数名称
描述
类型
req
上传文件请求
PutObjectByStreamReq
resp
上传文件响应
PutObjectByStreamResp
PutObjectByStreamReq 成员或函数说明：
成员或函数
描述
参数类型
bucket_name
存储桶名，可通过构造函数或 set 方法进行设置
存储桶的命名格式为 BucketName-APPID，详情请参见 命名规范
string
object_name
对象键（Key），可通过构造函数或 set 方法进行设置
是对象在存储桶中的唯一标识。例如，在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中，对象键为 doc/picture.jpg，详情请参见 对象键
string
in_stream
输入流，可通过构造函数进行设置
istream
SetXCosStorageClass
设置存储类型，设置方法为 req.SetXCosStorageClass("xxxx")
string
SetTrafficLimit
设置单链接限速，设置方法为 req.SetTrafficLimit(819200)，默认单位为 bit/s，限速值设置范围为 819200 - 838860800
uint64_t
PutObjectByStreamResp 成员函数说明：
成员函数
描述
返回类型
GetVersionId
获取 Object 的版本号, 如果 Bucket 未开启多版本, 返回空字符串
string
GetXCosServerSideEncryption
获取 Server 端加密使用的算法
string
GetEtag
获取存储上传对象的 Etag
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;
    }
}

异步高级接口

注意：
仅支持文件上传，不支持流式上传。
多线程并发同时上传多个分块。
分块大小支持用户自行配置，默认为10MB。
上传线程池大小支持用户自行配置，默认5。
异步线程池大小支持用户自行配置，默认为2。

前期准备：创建 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 示范如何使用异步高级上传接口进行对象上传。包含进度回调和上传状态回调的样例。
仅支持文件上传，不支持流式上传，内部封装了分块上传的各接口。
可通过全局设置上传线程池大小、分块大小。该上传线程池是每次上传独立的。
可通过全局设置异步线程池大小。该线程池全局共用，供异步调度使用。
方法原型
SharedAsyncContext CosAPI::AsyncMultiPutObject(const AsyncMultiPutObjectReq& req)
请求示例
/*
 * 该方法是异步上传对象的进度回调示例
 */
void ProgressCallback(uint64_t transferred_size, uint64_t total_size, void* user_data) {
    qcloud_cos::ObjectReq* req = static_cast<qcloud_cos::ObjectReq*>(user_data);
    if (0 == transferred_size % 1048576) {
        std::cout << "ObjectName:" << req->GetObjectName() << ", TranferedSize:" << transferred_size << ",TotalSize:" << total_size << std::endl;
    }
}


/*
 * 该方法是异步上传对象的完成回调示例
 */
void PutObjectAsyncDoneCallback(const SharedAsyncContext& context, void* user_data) {
    UNUSED_PARAM(user_data)
    std::cout << "PutObjectAsyncDoneCallback, BucketName:" << context->GetBucketName() << ", ObjectName:" << context->GetObjectName() << ", LocalFile:" << context->GetLocalFilePath() << std::endl;
    if (context->GetResult().IsSucc()) {
        // 获取响应
        std::cout << "AsyncMultiPutObject succeed" << std::endl;
        std::cout << "Result:" << context->GetResult().DebugString() << std::endl;
        AsyncResp resp = context->GetAsyncResp();
        // std::cout << "Location:" << resp.GetLocation() << std::endl;
        // std::cout << "Bucket:" << resp.GetBucket() << std::endl;
        // std::cout << "Key:" << resp.GetKey() << std::endl;
        std::cout << "ETag:" << resp.GetEtag() << std::endl;
        std::cout << "Crc64:" << resp.GetXCosHashCrc64Ecma() << std::endl;
    } else {
        std::cout << "AsyncMultiPutObject failed" << std::endl;
        std::cout << "ErrorMsg:" << context->GetResult().GetErrorMsg() << std::endl;
    }
}

void AsyncMultiPutObjectDemo(qcloud_cos::CosAPI& cos) {
    // 此配置是全局性配置，主动设置后，后续涉及异步接口，都使用此配置
    CosSysConfig::SetAsynThreadPoolSize(2);  // 设置异步线程池大小 默认2
    std::string local_file = "test_file/big_file.txt";
    std::string object_name = "big_file.txt";
    qcloud_cos::AsyncMultiPutObjectReq req(bucket_name, object_name, local_file);
    req.SetRecvTimeoutInms(1000 * 60);
    // 设置上传进度回调
    req.SetTransferProgressCallback(&ProgressCallback);
    // 设置上传状态回调
    req.SetDoneCallback(&PutObjectAsyncDoneCallback);
    // 设置私有数据，对应回调中的 user_data
    req.SetUserData(&req);

    // 开始上传
    SharedAsyncContext context = cos.AsyncMultiPutObject(req);

    std::cout << "===================AsyncMultiPutObject======================" << std::endl;
    // 等待上传结束
    std::cout << "wait finish..." << std::endl;
    context->WaitUntilFinish();

    // 检查结果
    if (context->GetResult().IsSucc()) {
        // 获取响应
        std::cout << "AsyncMultiPutObject succeed" << std::endl;
        std::cout << "Result:" << context->GetResult().DebugString() << std::endl;
        AsyncResp resp = context->GetAsyncResp();
        // std::cout << "Location:" << resp.GetLocation() << std::endl;
        // std::cout << "Bucket:" << resp.GetBucket() << std::endl;
        // std::cout << "Key:" << resp.GetKey() << std::endl;
        std::cout << "ETag:" << resp.GetEtag() << std::endl;
        std::cout << "Crc64:" << resp.GetXCosHashCrc64Ecma() << std::endl;
    } else {
        std::cout << "AsyncMultiPutObject failed" << std::endl;
        std::cout << "ErrorMsg:" << context->GetResult().GetErrorMsg() << std::endl;
    }
    std::cout << "============================================================" << std::endl;
}
参数说明
参数名称
描述
类型
req
上传文件请求
AsyncMultiPutObjectReq
AsyncMultiPutObjectReq 成员或函数说明：
成员或函数
描述
参数类型
bucket_name
存储桶名，可通过构造函数或 set 方法进行设置
存储桶的命名格式为 BucketName-APPID，详情请参见 命名规范
string
object_name
对象键（Key），可通过构造函数或 set 方法进行设置
是对象在存储桶中的唯一标识。例如，在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中，对象键为 doc/picture.jpg，详情请参见 对象键
string
local_file_path
本地文件路径，可通过构造函数或 set 方法进行设置
string
SetXCosStorageClass
设置存储类型，设置方法为 req.SetXCosStorageClass("xxxx")
string
SetRecvTimeoutInms
设置接收超时，单位为ms，默认 5s
uint64_t
SetTransferProgressCallback
设置上传进度回调方法
TransferProgressCallback
SetDoneCallback
设置上传进度状态方法
DoneCallback

CosSysConfig 类用于进行相关的配置，在该样例中主要成员函数说明如下：
成员函数
描述
参数类型
SetAsynThreadPoolSize
设置异步线程池的大小，默认为2
设置方法为CosSysConfig::SetAsynThreadPoolSize(2)
unsigned
返回说明
context 主要成员函数说明如下：
成员函数
描述
返回类型
WaitUntilFinish
等待上传结束
无
GetResult
获取 Result 结果
CosResult
GetAsyncResp
获取 Resp 响应结果
AsyncResp
AsyncResp 主要成员函数说明如下：
成员函数
描述
返回类型
GetXCosHashCrc64Ecma
获取存储上传对象的 CRC64
string
GetEtag
获取存储上传对象的 Etag
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;
    }
}

异步简单接口

前期准备：创建 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 进行本地文件的异步简单上传。
最大支持上传不超过5GB的对象。
包含进度回调和上传状态回调的样例。
方法原型
SharedAsyncContext CosAPI::AsyncPutObject(const AsyncPutObjectReq& req)
请求示例
/*
 * 该方法是异步上传对象的进度回调示例
 */
void ProgressCallback(uint64_t transferred_size, uint64_t total_size, void* user_data) {
    qcloud_cos::ObjectReq* req = static_cast<qcloud_cos::ObjectReq*>(user_data);
    if (0 == transferred_size % 1048576) {
        std::cout << "ObjectName:" << req->GetObjectName() << ", TranferedSize:" << transferred_size << ",TotalSize:" << total_size << std::endl;
    }
}

/*
 * 该方法是异步上传对象的完成回调示例
 */
void PutObjectAsyncDoneCallback(const SharedAsyncContext& context, void* user_data) {
    UNUSED_PARAM(user_data)
    std::cout << "PutObjectAsyncDoneCallback, BucketName:" << context->GetBucketName() << ", ObjectName:" << context->GetObjectName() << ", LocalFile:" << context->GetLocalFilePath() << std::endl;
    if (context->GetResult().IsSucc()) {
        // 获取响应
        std::cout << "PutObject succeed" << std::endl;
        std::cout << "Result:" << context->GetResult().DebugString() << std::endl;
        AsyncResp resp = context->GetAsyncResp();
        // std::cout << "Location:" << resp.GetLocation() << std::endl;
        // std::cout << "Bucket:" << resp.GetBucket() << std::endl;
        // std::cout << "Key:" << resp.GetKey() << std::endl;
        std::cout << "ETag:" << resp.GetEtag() << std::endl;
        std::cout << "Crc64:" << resp.GetXCosHashCrc64Ecma() << std::endl;
    } else {
        std::cout << "PutObject failed" << std::endl;
        std::cout << "ErrorMsg:" << context->GetResult().GetErrorMsg() << std::endl;
    }
}

void AsyncPutObjectDemo(qcloud_cos::CosAPI& cos) {
    std::string local_file = "test_file/text.txt";
    std::string object_name = "text.txt";
    qcloud_cos::AsyncPutObjectReq req(bucket_name, object_name, local_file);
    req.SetRecvTimeoutInms(1000 * 60);
    // 设置上传进度回调
    req.SetTransferProgressCallback(&ProgressCallback);
    // 设置上传状态回调
    req.SetDoneCallback(&PutObjectAsyncDoneCallback);
    // 设置私有数据，对应回调中的 user_data
    req.SetUserData(&req);

    // 开始上传
    SharedAsyncContext context = cos.AsyncPutObject(req);
    std::cout << "===================AsyncPutObjectByFile======================" << std::endl;
    
    // 等待上传结束
    std::cout << "wait finish..." << std::endl;
    context->WaitUntilFinish();

    // 检查结果
    if (context->GetResult().IsSucc()) {
        // 获取响应
        std::cout << "AsyncPutObjectByFile succeed" << std::endl;
        std::cout << "Result:" << context->GetResult().DebugString() << std::endl;
        AsyncResp resp = context->GetAsyncResp();
        // std::cout << "Location:" << resp.GetLocation() << std::endl;
        // std::cout << "Bucket:" << resp.GetBucket() << std::endl;
        // std::cout << "Key:" << resp.GetKey() << std::endl;
        std::cout << "ETag:" << resp.GetEtag() << std::endl;
        std::cout << "Crc64:" << resp.GetXCosHashCrc64Ecma() << std::endl;
    } else {
        std::cout << "AsyncPutObjectByFile failed" << std::endl;
        std::cout << "ErrorMsg:" << context->GetResult().GetErrorMsg() << std::endl;
    }
    std::cout << "=============================================================" << std::endl;
}
参数说明
参数名称
描述
类型
req
上传文件请求
AsyncPutObjectReq
AsyncPutObjectReq 成员或函数说明：
成员或函数
描述
参数类型
bucket_name
存储桶名，可通过构造函数或 set 方法进行设置
存储桶的命名格式为 BucketName-APPID，详情请参见 命名规范
string
object_name
对象键（Key），可通过构造函数或 set 方法进行设置
是对象在存储桶中的唯一标识。例如，在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中，对象键为 doc/picture.jpg，详情请参见 对象键
string
local_file_path
本地文件路径，可通过构造函数或 set 方法进行设置
string
SetXCosStorageClass
设置存储类型，设置方法为 req.SetXCosStorageClass("xxxx")
string
SetRecvTimeoutInms
设置接收超时，单位为ms，默认 5s
uint64_t
SetTransferProgressCallback
设置上传进度回调方法
TransferProgressCallback
SetDoneCallback
设置上传进度状态方法
DoneCallback
返回说明
context 主要成员函数说明如下：
成员函数
描述
返回类型
WaitUntilFinish
等待上传结束
无
GetResult
获取 Result 结果
CosResult
GetAsyncResp
获取 Resp 响应结果
AsyncResp
AsyncResp 主要成员函数说明如下：
成员函数
描述
返回类型
GetXCosHashCrc64Ecma
获取存储上传对象的 CRC64
string
GetEtag
获取存储上传对象的 Etag
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;
    }
}

使用案例：上传流类型

说明：
该 Demo 演示了如何使用 COS C++ SDK 进行流类型的简单上传。
最大支持上传不超过5GB的对象。
方法原型
SharedAsyncContext CosAPI::AsyncPutObject(const AsyncPutObjectByStreamReq& req)
请求示例
/*
 * 该方法是异步上传对象的进度回调示例
 */
void ProgressCallback(uint64_t transferred_size, uint64_t total_size, void* user_data) {
    qcloud_cos::ObjectReq* req = static_cast<qcloud_cos::ObjectReq*>(user_data);
    if (0 == transferred_size % 1048576) {
        std::cout << "ObjectName:" << req->GetObjectName() << ", TranferedSize:" << transferred_size << ",TotalSize:" << total_size << std::endl;
    }
}

/*
 * 该方法是异步上传对象的完成回调示例
 */
void PutObjectAsyncDoneCallback(const SharedAsyncContext& context, void* user_data) {
    UNUSED_PARAM(user_data)
    std::cout << "PutObjectAsyncDoneCallback, BucketName:" << context->GetBucketName() << ", ObjectName:" << context->GetObjectName() << ", LocalFile:" << context->GetLocalFilePath() << std::endl;
    if (context->GetResult().IsSucc()) {
        // 获取响应
        std::cout << "AsyncMultiPutObject succeed" << std::endl;
        std::cout << "Result:" << context->GetResult().DebugString() << std::endl;
        AsyncResp resp = context->GetAsyncResp();
        // std::cout << "Location:" << resp.GetLocation() << std::endl;
        // std::cout << "Bucket:" << resp.GetBucket() << std::endl;
        // std::cout << "Key:" << resp.GetKey() << std::endl;
        std::cout << "ETag:" << resp.GetEtag() << std::endl;
        std::cout << "Crc64:" << resp.GetXCosHashCrc64Ecma() << std::endl;
    } else {
        std::cout << "AsyncMultiGetObject failed" << std::endl;
        std::cout << "ErrorMsg:" << context->GetResult().GetErrorMsg() << std::endl;
    }
}

void AsyncPutObjectDemo(qcloud_cos::CosAPI& cos) {
    std::string object_name = "text.txt";
    std::istringstream iss("put object");
    qcloud_cos::AsyncPutObjectByStreamReq req(bucket_name, object_name, iss);
    req.SetRecvTimeoutInms(1000 * 60);
    // 设置上传进度回调
    req.SetTransferProgressCallback(&ProgressCallback);
    // 设置上传状态回调
    req.SetDoneCallback(&PutObjectAsyncDoneCallback);
    // 设置私有数据，对应回调中的 user_data
    req.SetUserData(&req);



    // 开始上传
    SharedAsyncContext context = cos.AsyncPutObject(req);



    std::cout << "===================AsyncPutObjectByStream======================" << std::endl;
    // 等待上传结束
    std::cout << "wait finish..." << std::endl;
    context->WaitUntilFinish();



    // 检查结果
    if (context->GetResult().IsSucc()) {
        // 获取响应
        std::cout << "AsyncPutObjectByStream succeed" << std::endl;
        std::cout << "Result:" << context->GetResult().DebugString() << std::endl;
        AsyncResp resp = context->GetAsyncResp();
        // std::cout << "Location:" << resp.GetLocation() << std::endl;
        // std::cout << "Bucket:" << resp.GetBucket() << std::endl;
        // std::cout << "Key:" << resp.GetKey() << std::endl;
        std::cout << "ETag:" << resp.GetEtag() << std::endl;
        std::cout << "Crc64:" << resp.GetXCosHashCrc64Ecma() << std::endl;
    } else {
        std::cout << "AsyncPutObjectByStream failed" << std::endl;
        std::cout << "ErrorMsg:" << context->GetResult().GetErrorMsg() << std::endl;
    }
    std::cout << "===============================================================" << std::endl;
}
参数说明
参数名称
描述
类型
req
上传文件请求
AsyncPutObjectByStreamReq
AsyncPutObjectByStreamReq 成员或函数说明：
成员或函数
描述
参数类型
bucket_name
存储桶名，可通过构造函数或 set 方法进行设置
存储桶的命名格式为 BucketName-APPID，详情请参见 命名规范
string
object_name
对象键（Key），可通过构造函数或 set 方法进行设置
是对象在存储桶中的唯一标识。例如，在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中，对象键为 doc/picture.jpg，详情请参见 对象键
string
in_stream
输入流，可通过构造函数进行设置
istream
SetXCosStorageClass
设置存储类型，设置方法为 req.SetXCosStorageClass("xxxx")
string
SetRecvTimeoutInms
设置接收超时，单位为ms，默认 5s
uint64_t
SetTransferProgressCallback
设置上传进度回调方法
TransferProgressCallback
SetDoneCallback
设置上传进度状态方法
DoneCallback
返回说明
context 主要成员函数说明如下：
成员函数
描述
返回类型
WaitUntilFinish
等待上传结束
无
GetResult
获取 Result 结果
CosResult
GetAsyncResp
获取 Resp 响应结果
AsyncResp
AsyncResp 主要成员函数说明如下：
成员函数
描述
返回类型
GetXCosHashCrc64Ecma
获取存储上传对象的 CRC64
string
GetEtag
获取存储上传对象的 Etag
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;
    }
}

分块操作

分块操作是大文件上传时，使用一系列分块，改善大文件上传耗时太久可能导致的各种中断问题。关于分块上传的更多说明请参见 分块上传。分块上传对象的操作流程如下。
说明：
如果要上传的文件可以完整获取，推荐使用高级接口。

前期准备：创建 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;
}

操作流程

分块上传的流程

1. 初始化分块上传（Initiate Multipart Upload），得到 UploadId。
2. 使用 UploadId 上传分块（Upload Part）。
3. 完成分块上传（Complete Multipart Upload）。

分块继续上传的流程

1. 如果没有记录 UploadId，则要先查询分块上传任务（List Multipart Uploads），得到对应文件的 UploadId。
2. 使用 UploadId 列出已上传的分块（List Parts）。
3. 使用 UploadId 上传剩余的分块（Upload Part）。
4. 完成分块上传（Complete Multipart Upload）。

终止分块上传的流程

1. 如果没有记录 UploadId，则查询分块上传任务（List Multipart Uploads），得到对应文件的 UploadId。
2. 终止分块上传并删除已上传分块（Abort Multipart Upload）。

使用案例：初始化分块上传

初始化分块上传操作，获取对应的 uploadId 用于后续的操作。
方法原型
CosResult CosAPI::InitMultiUpload(const InitMultiUploadReq& req, InitMultiUploadResp* resp)
请求示例
void InitMultiUpload(qcloud_cos::CosAPI& cos, const std::string& bucket_name,
                     const std::string& object_name, std::string* upload_id) {
  qcloud_cos::InitMultiUploadReq req(bucket_name, object_name);
  qcloud_cos::InitMultiUploadResp resp;
  qcloud_cos::CosResult result = cos.InitMultiUpload(req, &resp);


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

  *upload_id = resp.GetUploadId();
}
参数说明
参数名称
描述
类型
req
初始化分块上传请求
InitMultiUploadReq
resp
初始化分块上传响应
InitMultiUploadResp
InitMultiUploadReq 成员说明：
成员
设置方法
描述
类型
bucket_name
构造函数或 set 方法
存储桶的命名格式为 BucketName-APPID，详情请参见 命名规范
string
object_name
构造函数或 set 方法
对象键（Key）是对象在存储桶中的唯一标识。
例如，在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中，对象键为 doc/picture.jpg，详情请参见 对象键
string
InitMultiUploadResp 成员函数说明：
成员函数
描述
类型
GetUploadId
获取 UploadId
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;
    }
}

使用案例：查询分块上传任务

查询分块上传任务（List Multipart Uploads），获取当前正在进行的所有上传任务，可以从中找到需要处理的 uploadId。
方法原型
CosResult ListMultipartUpload(const ListMultipartUploadReq& req, ListMultipartUploadResp* resp)
请求示例
void ListMultipartUpload(qcloud_cos::CosAPI& cos,
                         const std::string& bucket_name) {
  qcloud_cos::ListMultipartUploadReq req(bucket_name);
  qcloud_cos::ListMultipartUploadResp resp;
  qcloud_cos::CosResult result = cos.ListMultipartUpload(req, &resp);
  std::vector<Upload> rst = resp.GetUpload();

  for (std::vector<qcloud_cos::Upload>::const_iterator itr = rst.begin(); itr != rst.end(); ++itr) {
    const qcloud_cos::Upload& upload = *itr;
    std::cout << "key = " << upload.m_key << ", uploadid= " << upload.m_uploadid
              << ", storagen class = " << upload.m_storage_class
              << ", m_initiated= " << upload.m_initiated << std::endl;
  }

  std::cout << "===================ListMultipartUpload=====================" << std::endl;
  PrintResult(result, resp);
  std::cout << "===========================================================" << std::endl;
}
参数说明
参数名称
描述
类型
req
查询分块上传任务请求
ListMultipartUploadReq
resp
查询分块上传任务响应
ListMultipartUploadResp
ListMultipartUploadReq 成员及函数说明：
成员或函数
描述
参数类型
bucket_name
存储桶名，可以通过构造函数或 set 方法进行设置
存储桶的命名格式为 BucketName-APPID，详情请参见 命名规范
string
SetKeyMarker
列出条目从该 Key 值开始
设置方法为req.SetKeyMarker("xxx")
string
SetDelimiter
定界符为一个符号，如果有 Prefix，则将 Prefix 到 delimiter 之间的相同路径归为一类，定义为 Common Prefix，然后列出所有 Common Prefix。如果没有 Prefix，则从路径起点开始
设置方法为req.SetDelimiter("xxx")
string
SetPrefix
限定返回的 Object key 必须以 Prefix 作为前缀。注意使用 prefix 查询时，返回的 key 中仍会包含 Prefix
设置方法为req.SetPrefix("xxx")
string
SetUploadIdMarker
列出条目从该 UploadId 值开始
设置方法为req.SetUploadIdMarker("xxx")
string
SetMaxUploads
设置最大返回的 multipart 数量，合法值1到1000
设置方法为req.SetMaxUploads("xxx")
string
SetEncodingType
规定返回值的编码方式，可选值：url
设置方法为req.SetEncodingType("xxx")
string
ListMultipartUploadResp 成员函数说明:
成员函数
描述
类型
GetUpload
获取 UploadId列表。使用方式参考样例
vector<qcloud_cos::Upload>
CosResult 主要成员函数说明如下：
成员函数
描述
返回类型
IsSucc
判断是否成功，成功返回 true，失败返回 false。
bool
GetHttpStatus
获得 http 状态码。
int
GetErrorCode
请求失败时获取错误码。
string
GetErrorMsg
请求失败时获取错误信息。
string
GetXCosRequestId
获取请求 ID。
string
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;
    }
}

使用案例：上传分块

方法原型
CosResult CosAPI::UploadPartData(const UploadPartDataReq& req, UploadPartDataResp* resp)
请求示例
void UploadPartData(qcloud_cos::CosAPI& cos, const std::string& bucket_name,
                    const std::string& object_name,
                    const std::string& upload_id, std::fstream& is,
                    uint64_t number, std::string* etag) {
  qcloud_cos::UploadPartDataReq req(bucket_name, object_name, upload_id, is);
  req.SetPartNumber(number);
  qcloud_cos::UploadPartDataResp resp;
  qcloud_cos::CosResult result = cos.UploadPartData(req, &resp);
  *etag = resp.GetEtag();

  std::cout << "======================UploadPartData====================="<< std::endl;
  PrintResult(result, resp);
  std::cout << "========================================================="<< std::endl;
}
参数说明
参数名称
描述
类型
req
上传文件请求
UploadPartDataReq
resp
上传文件响应
UploadPartDataResp
UploadPartDataReq 成员或函数说明：
成员或函数
描述
参数类型
bucket_name
存储桶名，可通过构造函数或 set 方法进行设置
存储桶的命名格式为 BucketName-APPID，详情请参见 命名规范
string
object_name
对象键（Key），可通过构造函数或 set 方法进行设置
是对象在存储桶中的唯一标识。例如，在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中，对象键为 doc/picture.jpg，详情请参见 对象键
string
in_stream
输入流，可通过构造函数进行设置
istream
upload_id
upload_id，可通过构造函数进行设置

SetXCosStorageClass
设置存储类型，设置方法为 req.SetXCosStorageClass("xxxx")
string
SetTrafficLimit
设置单链接限速，设置方法为 req.SetTrafficLimit(819200)，默认单位为 bit/s，限速值设置范围为 819200 - 838860800
uint64_t
UploadPartDataResp 成员函数说明：
成员函数
描述
返回类型
GetEtag
获取存储上传对象的 Etag
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;
    }
}

使用案例：查询已上传的分块

查询特定分块上传操作中的已上传的块（List Parts）。
方法原型
CosResult ListParts(const ListPartsReq& req, ListPartsResp* resp)
请求示例
void ListParts(qcloud_cos::CosAPI& cos, const std::string& bucket_name,
               const std::string& object_name, const std::string& upload_id) {
  qcloud_cos::ListPartsReq req(bucket_name, object_name, upload_id);
  req.SetMaxParts(100);
  req.SetPartNumberMarker("1");
  qcloud_cos::ListPartsResp resp;
  qcloud_cos::CosResult result = cos.ListParts(req, &resp);


  std::cout << "===================ListParts=====================" << std::endl;
  PrintResult(result, resp);
  std::cout << "=================================================" << std::endl;
}
参数说明
参数名称
描述
类型
req
查询指定分块上传任务请求
ListPartsReq
resp
查询分块上传任务响应
ListPartsResp
ListPartsReq 成员或函数说明：
成员或函数
描述
参数类型
bucket_name
存储桶名，可以通过构造函数或 set 方法进行设置
存储桶的命名格式为 BucketName-APPID，详情请参见 命名规范
string
object_name
指定分块上传到 COS 上的路径，即对象键。例如对象键为 folder/picture.jpg
string
upload_id
标识指定分块上传的 uploadId
string
SetMaxParts
单次返回最大的条目数量，默认1000
string
SetPartNumberMarker
默认以 UTF-8 二进制顺序列出条目，所有列出条目从 marker 开始
string
ListPartsResp 成员或函数说明：
成员函数
描述
返回类型
GetParts
获取 Parts 列表，包含每一分块的 ETag 和编号。
vector<Part>
GetNextPartNumberMarker
下一次 list 的起点 marker
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;
    }
}

使用案例：完成分块上传

完成整个文件的分块上传（Complete Multipart Upload）。
说明：
完成分块上传之后，分块上传任务将删除，任务对应的 uploadId 不再有效。
方法原型
CosResult CompleteMultiUpload(const CompleteMultiUploadReq& req, CompleteMultiUploadResp* resp)
请求示例
void CompleteMultiUpload(qcloud_cos::CosAPI& cos,
                         const std::string& bucket_name,
                         const std::string& object_name,
                         const std::string& upload_id,
                         const std::vector<std::string>& etags,
                         const std::vector<uint64_t>& numbers) {
  qcloud_cos::CompleteMultiUploadReq req(bucket_name, object_name, upload_id);
  qcloud_cos::CompleteMultiUploadResp resp;
  req.AddParam("versionId", "MTg0NDY3NDI1NjQ4NjUyMjQ1MTA");
  req.SetEtags(etags);
  req.SetPartNumbers(numbers);


  qcloud_cos::CosResult result = cos.CompleteMultiUpload(req, &resp);

  std::cout << "===================Complete=============================" << std::endl;
  PrintResult(result, resp);
  std::cout << "========================================================" << std::endl;
}
参数说明
参数名称
描述
类型
req
完成分块上传请求
CompleteMultiUploadReq
resp
完成分块上传响应
CompleteMultiUploadResp
CompleteMultiUploadReq 成员及函数说明：
成员及函数
描述
类型
bucket_name
存储桶的命名格式为 BucketName-APPID，详情请参见 命名规范
string
object_name
指定分块上传到 COS 上的路径，即 对象键 。例如对象键为 folder/picture.jpg
string
upload_id
标识指定分块上传的 uploadId
string
SetEtags
标识分块上传返回的 Etag，需要和 numbers 顺序一致
req.SetEtags(etags)
vector<std::string>
SetPartNumbers
标识分块块的编号，需要和 etags 顺序一致
req.SetPartNumbers(numbers)
vector<uint64_t>
CompleteMultiUploadResp 成员函数说明：
成员函数
描述
返回类型
GetVersionId
获取 Object 的版本号, 如果 Bucket 未开启多版本, 返回空字符串
string
GetXCosServerSideEncryption
获取 Server 端加密使用的算法
string
GetEtag
获取存储上传对象的 Etag
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;
    }
}

使用案例：终止分块上传

终止一个分块上传操作并删除已上传的分块（Abort Multipart Upload）。
说明：
终止分块上传之后，分块上传任务和已经上传的分块都会被删除，对应的 uploadId 不再有效。
方法原型
CosResult AbortMultiUpload(const AbortMultiUploadReq& req, AbortMultiUploadResp* resp)
请求示例
void AbortMultiUpload(qcloud_cos::CosAPI& cos, const std::string& bucket_name,
                      const std::string& object_name,
                      const std::string& upload_id) {
  qcloud_cos::AbortMultiUploadReq req(bucket_name, object_name, upload_id);
  qcloud_cos::AbortMultiUploadResp resp;
  qcloud_cos::CosResult result = cos.AbortMultiUpload(req, &resp);
  std::cout << "======================AbortUploadPart=====================";
  PrintResult(result, resp);
  std::cout << "=========================================================";
}
参数说明
参数名称
描述
类型
req
终止分块上传请求
AbortMultiUploadReq
resp
终止分块上传响应
AbortMultiUploadResp
AbortMultiUploadReq 成员及函数说明：
成员及函数
描述
类型
bucket_name
存储桶的命名格式为 BucketName-APPID，详情请参见 命名规范
string
object_name
指定分块上传到 COS 上的路径，即 对象键 。例如对象键为 folder/picture.jpg
string
upload_id
标识指定分块上传的 uploadId
string
AbortMultiUploadResp 成员函数说明：
成员函数
描述
返回类型
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;
    }
}

使用案例：分块上传完整示例

说明：
该 Demo 示范如何自行组合使用各分块操作进行对象上传。
仅支持流式上传。
void PutPartDemo(qcloud_cos::CosAPI& cos) {
    std::string object_name = "big_file.txt";

    // 1. InitMultiUpload
    qcloud_cos::InitMultiUploadReq init_req(bucket_name, object_name);
    qcloud_cos::InitMultiUploadResp init_resp;
    qcloud_cos::CosResult init_result = cos.InitMultiUpload(init_req, &init_resp);


    std::cout << "=====================InitMultiUpload=====================" << std::endl;
    PrintResult(init_result, init_resp);
    std::cout << "=========================================================" << std::endl;

    // 2. UploadPartData
    // UploadPartData 部分，可以根据实际选择分块数量和分块大小，这里以 2 个分块为例
    std::vector<std::string> etags;
    std::vector<uint64_t> part_numbers;
    std::string upload_id = init_resp.GetUploadId();
    {
        uint64_t part_number = 1;
        // 模拟上传分块数据，这里以 1M 为例
        std::vector<char> data(1024 * 1024, 'A');
        std::string content(data.begin(), data.end());
        std::istringstream iss(content);
        qcloud_cos::UploadPartDataReq req(bucket_name, object_name, upload_id, iss);
        req.SetPartNumber(part_number);
        qcloud_cos::UploadPartDataResp resp;
        qcloud_cos::CosResult result = cos.UploadPartData(req, &resp);
        std::cout << "==================UploadPartDataResp1=====================" << std::endl;
        PrintResult(result, resp);
        std::cout << "==========================================================" << std::endl;
        if (result.IsSucc()) {
            part_numbers.push_back(part_number);
            etags.push_back(resp.GetEtag());
        }
    }
    {
        uint64_t part_number = 2;
        std::istringstream iss("The last part can be smaller than 1MB");
        qcloud_cos::UploadPartDataReq req(bucket_name, object_name, upload_id, iss);
        req.SetPartNumber(part_number);
        qcloud_cos::UploadPartDataResp resp;
        qcloud_cos::CosResult result = cos.UploadPartData(req, &resp);



        std::cout << "==================UploadPartDataResp2=====================" << std::endl;
        PrintResult(result, resp);
        std::cout << "==========================================================" << std::endl;
        if (result.IsSucc()) {
            part_numbers.push_back(part_number);
            etags.push_back(resp.GetEtag());
        }
    }


    // 3. Complete
    CompleteMultiUploadReq comp_req(bucket_name, object_name, upload_id);
    CompleteMultiUploadResp comp_resp;

    comp_req.SetEtags(etags);
    comp_req.SetPartNumbers(part_numbers);

    qcloud_cos::CosResult result = cos.CompleteMultiUpload(comp_req, &comp_resp);

    std::cout << "===================Complete=============================" << std::endl;
    PrintResult(result, comp_resp);
    std::cout << "========================================================" << std::endl;
    return;
}

API 操作

关于简单操作的 API 接口说明，请参见 PUT Object 文档。
关于分块操作的 API 接口说明，请参见 List Multipart Uploads 、Initiate Multipart Upload 、Upload Part 、List Parts、Abort Multipart Upload、Complete Multipart Upload文档。

中国站
文档反馈
文档活动
message-icon联系我们
目录