tencent cloud

文档反馈

快速入门

最后更新时间:2024-03-14 09:53:07

    下载与安装

    相关资源

    对象存储 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 安装 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;
    }
    }
    
    联系我们

    联系我们,为您的业务提供专属服务。

    技术支持

    如果你想寻求进一步的帮助,通过工单与我们进行联络。我们提供7x24的工单服务。

    7x24 电话支持