tencent cloud

数据万象

动态与公告
产品动态
产品公告
产品简介
产品概述
产品优势
应用场景
功能概览
地域与域名
使用限制
产品计费
计费概述
计费方式
计费项
免费额度
欠费说明
查看消费明细
常见问题
快速入门
注册与登录
绑定存储桶
上传和处理文件
下载和删除文件
解绑存储桶
通过 COS 使用数据万象
能力地图
图片处理
媒体处理
内容审核
AI 内容识别
文档处理
智能语音
文件处理
用户指南
概览
存储桶管理
智能工具箱
任务与工作流
数据监控
用量统计
实践教程
版权保护解决方案
图片处理实践
API 授权策略使用指引
工作流实践
API 文档
API 概览
结构体
公共请求头部
公共响应头部
开通万象服务
图片处理
AI 内容识别
智能语音
媒体处理
内容审核
文档处理
文件处理
任务与工作流
云查毒
错误码
请求签名
SDK 文档
SDK 概览
图片处理 Android SDK
图片处理 iOS SDK
COS Android SDK
C SDK
C++ SDK
.NET(C#) SDK
Go SDK
COS iOS SDK
Java SDK
JavaScript SDK
Node.js SDK
PHP SDK
Python SDK
小程序 SDK
SDK 产品个人信息保护规则
安全与合规
权限管理
常见问题
基础设置
文档处理
媒体处理
内容识别
智能语音
服务协议
Service Level Agreement
联系我们
词汇表

快速入门

PDF
聚焦模式
字号
最后更新时间: 2025-11-20 09:51:30

下载与安装

相关资源

对象存储 COS 的 XML C++ SDK 源码下载地址: Linux 版本/Windows 版本/macOS 版本: XML Linux C++ SDK
SDK 快速下载地址:XML C++ SDK
示例 Demo 下载地址:COS XML C++ SDK 示例
SDK 更新日志请参见 ChangeLog
说明
如果您在使用 XML 版本 SDK 时遇到函数或方法不存在等错误,请先将 XML 版本 SDK 升级到最新版再重试。如果您仍在使用 JSON 版本 SDK,请升级到 XML C++ SDK。

已编译(推荐)

下载 XML C++ SDK 源码,libs 目录中有编译完成的库,可以直接使用,使用时请选择对应的系统版本。
libs/linux/libcossdk.a #linux 的静态库,libcossdk.a 是基于 gcc version 4.8.5版本编译的,如果客户编译环境的gcc版本不同,需要重新编译libcossdk.a
libs/linux/libcossdk-shared.so #linux 动态库
libs/Win32/cossdk.lib #Win32库
libs/x64/cossdk.lib #Win64 库
libs/macOS/libcossdk.a #macOS 静态库
libs/macOS/libcossdk-shared.dylib #macOS 动态库
说明
使用时,请将对应系统的库文件和 SDK include 头文件拷贝至您的工程中。
Third-party 目录下有第三方依赖库,如下:
third_party/lib/linux/poco/ #linux下依赖的 poco 动态库,poco 库是基于 OpenSSL 1.0.2版本编译的,如果客户编译环境的openssl版本不同,需要重新编译poco
third_party/lib/Win32/openssl/ #Win32依赖的 openssl 库
third_party/lib/Win32/poco/ #Win32依赖的 poco 库
third_party/lib/x64/openssl/ #Win64依赖的 openssl 库
third_party/lib/x64/poco/ #Win64依赖的 poco 库
third_party/lib/macOS/poco/ #macOS 依赖的 poco 库
说明
使用时,请将对应系统的依赖库拷贝至您的工程中。

手动编译

编译选项

在根目录下的 CMakeLists.txt 文件可以配置编译选项,有以下编译选项:
option(BUILD_UNITTEST "Build unittest" OFF) #配置编译单元测试
option(BUILD_DEMO "Build demo" ON) #配置编译 demo 测试代码
option(BUILD_SHARED_LIB "Build shared library" OFF) #配置编译动态库

依赖库

依赖动态库:poco、openssl、crypto。

编译 Linux 版本 SDK

1. 安装编译工具及依赖库
yum install -y gcc gcc-c++ make cmake openssl
#cmake版本要求大于2.8
2. 编译 SDK 下载 XML C++ SDK 源码 到您的开发环境,并执行以下命令:
cd ${cos-cpp-sdk}
mkdir -p build
cd build
cmake ..
make
3. 安装 Poco 库
cd ${cos-cpp-sdk}
sh install-libpoco.sh
说明
该脚本将 Poco 动态库安装到 /usr/lib64 目录中,并创建软链接,如果要在生产环境中使用 COS SDK,也需要安装 Poco 库到生产环境中。
4. 测试 demo
说明
如果不需要测试 demo,可跳过此步骤。
cd ${cos-cpp-sdk}
vim demo/cos_demo.cpp #修改 demo 中的存储桶名以及测试代码
vim CMakeLists.txt #修改根目录下的 CMakeLists.txt 中的 BUILD_DEMO 为 ON,开启编译demo
cd build && make #编译 demo
ls bin/cos_demo #生成的可执行文件在 bin 目录
vim bin/config.json #修改密钥和园区
cd bin && ./cos_demo #运行 demo
5. 使用 SDK 编译生成的库文件在 build/lib 目录中,静态库名称为 libcossdk.a,动态库名称为 libcossdk-shared.so。使用时,请将库拷贝至您的工程中,同时将 include 目录拷贝至您的工程中的 include 路径下。

编译 Windows 版本 SDK

1. 安装 Visual Studio 2017 开发环境。
2. 安装 CMake 工具 从 CMake官网 下载 Windows 版本的 CMake 编译工具,并将 ${CMake的安装路径}\\bin配置在 Windows 的系统环境变量 Path 中。
3. 编译 SDK i. 下载 XML Windows C++ SDK 源码 到您的开发环境。 ii. 打开 Windows 的命令行,cd 到 C++ SDK 的源码目录下,执行以下命令:
mkdir build
cd build
cmake .. #生成 Win32 makefile
cmake -G "Visual Studio 15 Win64" .. #生成 Win64 makefile
iii. 使用 Visual Studio 2017 打开解决方案资源管理器,进行编译。
4. 测试 demo
说明
如果不需要测试 demo,可跳过此步骤。
修改 demo 代码并编译,生成的 cos_demo.exe 在 bin 目录中,修改 bin/config.json 可运行 cos_demo.exe。
5. 使用 SDK 编译生成的库文件在 build/Release 目录中,静态库名称为cossdk.lib。使用时,请将库拷贝至您的工程中,同时将 include 目录拷贝至您的工程中的 include 路径下。

编译 Mac 版本 SDK

1. 安装编译工具及依赖库
brew install gcc make cmake openssl
2. 编译 SDK 下载 XML C++ SDK 源码 到您的开发环境,并执行以下命令:
cd ${cos-cpp-sdk}
mkdir -p build
cd build
cmake ..
make
3. 安装 Poco 库 Poco 库在 third_party/lib/macOS/poco 目录下,请自行安装。
4. 测试 demo
说明
如果不需要测试 demo,可跳过此步骤。
修改 demo 代码并编译,生成的 cos_demo 在 bin 目录中,拷贝 cos-cpp-sdk-v5/demo/config.json 到 bin 目录下,修改 bin/config.json 可运行 cos_demo。
5. 使用 SDK 编译生成的库文件在 build/lib 目录中,静态库名称为 libcossdk.a,动态库名称为 libcossdk-shared.dylib。使用时,请将库拷贝至您的工程中,同时将 include 目录拷贝至您的工程中的 include 路径下。

常见编译问题

1. 编译可执行程序的时候提示错误:
PocoCrypto.so.64: undefined reference to `PEM_write_bio_PrivateKey@libcrypto.so.10'
libPocoNetSSL.so.64: undefined reference to `X509_check_host@libcrypto.so.10'
ibPocoCrypto.so.64: undefined reference to `ECDSA_sign@OPENSSL_1.0.1_EC'
libPocoCrypto.so.64: undefined reference to `CRYPTO_set_id_callback@libcrypto.so.10'
ibPocoCrypto.so.64: undefined reference to `EVP_PKEY_id@libcrypto.so.10'
libPocoNetSSL.so.64: undefined reference to `SSL_get1_session@libssl.so.10'
libPocoNetSSL.so.64: undefined reference to `SSL_get_shutdown@libssl.so.10'
libPocoCrypto.so.64: undefined reference to `EVP_PKEY_set1_RSA@libcrypto.so.10'
libPocoCrypto.so.64: undefined reference to `SSL_load_error_strings@libssl.so.10'
这种情况一般是工程里自带的 poco 库的编译依赖的 SSL 版本与客户机器上的版本不一致导致的,需要用户重新编译 poco 库,并替换掉 third_party 里的poco 库。
wget https://github.com/pocoproject/poco/archive/refs/tags/poco-1.9.4-release.zip
cd poco-poco-1.9.4-release/
./configure --omit=Data/ODBC,Data/MySQL
mkdir my_build
cd my_build
cmake ..
make -j5
2. 编译 poco 库的时候无法编译出 PocoNetSSL 库,一般是因为机器没装 openssl-devel 库。
yum install -y openssl-devel
3. 编译可执行程序的时候提示错误:
undefined reference to `qcloud_cos::CosConfig::CosConfig(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&)
这种情况一般是因为工程自带的 libcossdk.a 编译使用的 gcc 版本与客户机器上的 gcc 版本不一致导致的,需要客户重新编译 poco 库和 libcossdk。

开始使用

下面为您介绍如何使用 COS C++ SDK 完成一个基础操作,如初始化客户端、创建存储桶、查询存储桶列表、上传对象、查询对象列表、下载对象和删除对象。
说明
关于文章中出现的 SecretId、SecretKey、Bucket 等名称的含义和获取方式请参见 COS 术语信息

初始化

注意
建议用户 使用临时密钥 调用 SDK,通过临时授权的方式进一步提高 SDK 使用的安全性。申请临时密钥时,请遵循 最小权限指引原则,防止泄露目标存储桶或对象之外的资源。
如果您一定要使用永久密钥,建议遵循 最小权限指引原则 对永久密钥的权限范围进行限制。
配置文件各字段介绍:
{
"SecretId":"********************************", // sercret_id 替换为用户的 SecretId,登录访问管理控制台查看密钥,https://console.tencentcloud.com/cam/capi
"SecretKey":"*******************************", // sercret_key 替换为用户的 SecretKey,登录访问管理控制台查看密钥,https://console.tencentcloud.com/cam/capi
"Region":"ap-guangzhou", // 存储桶地域, 替换为客户存储桶所在地域,可以在COS控制台指定存储桶的概览页查看存储桶地域信息,参考 https://console.tencentcloud.com/cos5/bucket/ ,关于地域的详情见 https://www.tencentcloud.com/document/product/436/6224?from_cn_redirect=1
"SignExpiredTime":360, // 签名超时时间, 单位s
"ConnectTimeoutInms":6000, // connect 超时时间, 单位ms
"ReceiveTimeoutInms":60000, // recv 超时时间, 单位ms
"UploadPartSize":10485760, // 上传文件分块大小,1M~5G, 默认为10M
"UploadCopyPartSize":20971520, // 上传复制文件分块大小,5M~5G, 默认为20M
"UploadThreadPoolSize":5, // 单文件分块上传线程池大小
"DownloadSliceSize":4194304, // 下载文件分块大小
"DownloadThreadPoolSize":5, // 单文件下载线程池大小
"AsynThreadPoolSize":2, // 异步上传下载线程池大小
"LogoutType":1, // 日志输出类型,0:不输出,1:输出到屏幕,2输出到syslog
"LogLevel":3, // 日志级别:1: ERR, 2: WARN, 3:INFO, 4:DBG
"IsDomainSameToHost":false, // 是否使用专有的 host
"DestDomain":"", // 特定 host
"IsUseIntranet":false, // 是否使用特定ip和端口号
"IntranetAddr":"" // 特定 ip 和端口号,例如“127.0.0.1:80”
}

使用临时密钥访问 COS

如果您需要使用临时密钥访问 COS,请参见如下代码:
#include "cos_api.h"
#include "cos_sys_config.h"
#include "cos_defines.h"
int main(int argc, char *argv[]) {
qcloud_cos::CosConfig config("./config.json");
// 如果使用永久密钥不需要填入 token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见 https://www.tencentcloud.com/document/product/436/14048
config.SetTmpToken("xxx");
qcloud_cos::CosAPI cos(config);
}

将 SDK 内部日志打印到自定义日志文件

如果您需要将 SDK 内部日志打印到自定义日志文件,特别是 Windows 系统,则参考如下代码:
#include "cos_api.h"
#include "cos_sys_config.h"
#include "cos_defines.h"
void TestLogCallback(const std::string& log) {
std::ofstream ofs;
ofs.open("test.log", std::ios_base::app);
ofs << log;
ofs.close();
}
int main(int argc, char** argv) {
qcloud_cos::CosConfig config("./config.json");
config.SetLogCallback(&TestLogCallback);
qcloud_cos::CosAPI cos(config);
}

创建存储桶

#include "cos_api.h"
#include "cos_sys_config.h"
#include "cos_defines.h"

int main(int argc, char *argv[]) {
// 1. 指定配置文件路径,初始化 CosConfig
qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);

// 2. 构造创建存储桶的请求
std::string bucket_name = "examplebucket-1250000000"; // 替换为用户的存储桶名,由bucketname-appid 组成,appid必须填入,可以在COS控制台查看存储桶名称。 https://console.tencentcloud.com/cos5/bucket
qcloud_cos::PutBucketReq req(bucket_name);
qcloud_cos::PutBucketResp resp;

// 3. 调用创建存储桶接口
qcloud_cos::CosResult result = cos.PutBucket(req, &resp);

// 4. 处理调用结果
if (result.IsSucc()) {
// 创建成功
} else {
// 创建存储桶失败,可以调用 CosResult 的成员函数输出错误信息,例如 requestID 等
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;
}
}


查询存储桶列表

#include "cos_api.h"
#include "cos_sys_config.h"
#include "cos_defines.h"

int main(int argc, char *argv[]) {
// 1. 指定配置文件路径,初始化 CosConfig
qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);

// 2. 构造查询存储桶列表的请求
qcloud_cos::GetServiceReq req;
qcloud_cos::GetServiceResp resp;
qcloud_cos::CosResult result = cos.GetService(req, &resp);

// 3. 获取响应信息
const qcloud_cos::Owner& owner = resp.GetOwner();
const std::vector<qcloud_cos::Bucket>& buckets = resp.GetBuckets();
std::cout << "owner.m_id=" << owner.m_id << ", owner.display_name=" << owner.m_display_name << std::endl;

for (std::vector<qcloud_cos::Bucket>::const_iterator itr = buckets.begin(); itr != buckets.end(); ++itr) {
const qcloud_cos::Bucket& bucket = *itr;
std::cout << "Bucket name=" << bucket.m_name << ", location="
<< bucket.m_location << ", create_date=" << bucket.m_create_date << std::endl;
}

// 4. 处理调用结果
if (result.IsSucc()) {
// 查询存储桶列表成功
} else {
// 查询存储桶列表失败,可以调用 CosResult 的成员函数输出错误信息,比如 requestID 等
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;
}
}

上传对象

#include "cos_api.h"
#include "cos_sys_config.h"
#include "cos_defines.h"

int main(int argc, char *argv[]) {
// 1. 指定配置文件路径,初始化 CosConfig
qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);

// 2. 构造上传文件的请求
std::string bucket_name = "examplebucket-1250000000"; // 替换为用户的存储桶名,由bucketname-appid 组成,appid必须填入,可以在COS控制台查看存储桶名称。 https://console.tencentcloud.com/cos5/bucket
std::string object_name = "exampleobject"; //exampleobject 即为对象键(Key),是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg,替换为用户指定的对象名。
qcloud_cos::PutObjectByFileReq req(bucket_name, object_name, "/path/to/local/file"); // 替换为用户指定的文件路径
//req.SetXCosStorageClass("STANDARD_IA"); // 默认为 STANDARD,可以调用 Set 方法设置存储类型
qcloud_cos::PutObjectByFileResp resp;

// 3. 调用上传文件接口
qcloud_cos::CosResult result = cos.PutObject(req, &resp);

// 4. 处理调用结果
if (result.IsSucc()) {
// 上传文件成功
} else {
// 上传文件失败,可以调用 CosResult 的成员函数输出错误信息,比如 requestID 等
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;
}
}

查询对象列表

#include "cos_api.h"
#include "cos_sys_config.h"
#include "cos_defines.h"

int main(int argc, char *argv[]) {
// 1. 指定配置文件路径,初始化 CosConfig
qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);

// 2. 构造查询对象列表的请求
std::string bucket_name = "examplebucket-1250000000"; // 替换为用户的存储桶名,由bucketname-appid 组成,appid必须填入,可以在COS控制台查看存储桶名称。 https://console.tencentcloud.com/cos5/bucket
qcloud_cos::GetBucketReq req(bucket_name);
qcloud_cos::GetBucketResp resp;
qcloud_cos::CosResult result = cos.GetBucket(req, &resp);

std::vector<qcloud_cos::Content> cotents = resp.GetContents();
for (std::vector<qcloud_cos::Content>::const_iterator itr = cotents.begin(); itr != cotents.end(); ++itr) {
const qcloud_cos::Content& content = *itr;
std::cout << "key name=" << content.m_key << ", lastmodified ="
<< content.m_last_modified << ", size=" << content.m_size << std::endl;
}

// 3. 处理调用结果
if (result.IsSucc()) {
// 查询对象列表成功
} else {
// 查询对象列表失败,可以调用 CosResult 的成员函数输出错误信息,例如 requestID 等
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;
}
}

下载对象

#include "cos_api.h"
#include "cos_sys_config.h"
#include "cos_defines.h"

int main(int argc, char *argv[]) {
// 1. 指定配置文件路径,初始化 CosConfig
qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);

// 2. 构造下载对象的请求
std::string bucket_name = "examplebucket-1250000000"; // 替换为用户的存储桶名,由bucketname-appid 组成,appid必须填入,可以在COS控制台查看存储桶名称。 https://console.tencentcloud.com/cos5/bucket
std::string object_name = "exampleobject"; // exampleobject 即为对象键(Key),是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg,替换为用户指定的对象名。
std::string local_path = "/tmp/exampleobject";
// request 需要提供 appid、bucketname、object,以及本地的路径(包含文件名)
qcloud_cos::GetObjectByFileReq req(bucket_name, object_name, local_path);
qcloud_cos::GetObjectByFileResp resp;

// 3. 调用下载对象接口
qcloud_cos::CosResult result = cos.GetObject(req, &resp);

// 4. 处理调用结果
if (result.IsSucc()) {
// 下载文件成功
} else {
// 下载文件失败,可以调用 CosResult 的成员函数输出错误信息,例如 requestID 等
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;
}
}

删除对象

#include "cos_api.h"
#include "cos_sys_config.h"
#include "cos_defines.h"

int main(int argc, char *argv[]) {
// 1. 指定配置文件路径,初始化 CosConfig
qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);

// 2. 构造删除对象的请求
std::string bucket_name = "examplebucket-1250000000"; // 替换为用户的存储桶名,由bucketname-appid 组成,appid必须填入,可以在COS控制台查看存储桶名称。 https://console.tencentcloud.com/cos5/bucket
std::string object_name = "exampleobject"; // exampleobject 即为对象键(Key),是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg,替换为用户指定的对象名。。
// 3. 调用删除对象接口
qcloud_cos::DeleteObjectReq req(bucket_name, object_name);
qcloud_cos::DeleteObjectResp resp;
qcloud_cos::CosResult result = cos.DeleteObject(req, &resp);

// 4. 处理调用结果
if (result.IsSucc()) {
// 删除对象成功
} else {
// 删除对象失败,可以调用 CosResult 的成员函数输出错误信息,例如 requestID 等
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;
}
}


帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈