控制台指南

最佳实践

开发者指南

API 文档

SDK 文档

快速入门

最近更新时间:2021-07-21 16:41:15

下载与安装

相关资源

说明:

如果您在使用 XML 版本 SDK 时遇到函数或方法不存在等错误,请先将 XML 版本 SDK 升级到最新版再重试。如果您仍在使用 JSON 版本 SDK,请 升级到 XML C++ SDK

已编译(推荐)

下载 XML C++ SDK 源码,libs 目录中有编译完成的库,可以直接使用,使用时请选择对应的系统版本。

libs/linux/libcossdk.a #linux的静态库
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动态库
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 库到生产环境中。

  1. 测试 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 #运行demon
  2. 使用 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 目录中,修改 bin/config.json 可运行 cos_demo。

  5. 使用 SDK
    编译生成的库文件在 build/lib 目录中,静态库名称为libcossdk.a,动态库名称为libcossdk-shared.dylib。使用时,请将库拷贝至您的工程中,同时将 include 目录拷贝至您的工程中的 include 路径下。

开始使用

下面为您介绍如何使用 COS C++ SDK 完成一个基础操作,如初始化客户端、创建存储桶、查询存储桶列表、上传对象、查询对象列表、下载对象和删除对象。

说明:

关于文章中出现的 SecretId、SecretKey、Bucket 等名称的含义和获取方式请参见 COS 术语信息

初始化

配置文件各字段介绍:

"SecretId":"********************************",  // V5.4.3 之前的版本使用AccessKey
"SecretKey":"*******************************",
"Region":"ap-guangzhou",                // COS区域, 一定要保证正确,地域及简称请参阅 https://cloud.tencent.com/document/product/436/6224 
"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,请先在 COS 控制台配置自定义域名,操作指引请参见 开启自定义源站域名

假如您使用的域名为 mydomain.com,则在 config.json 中增加如下配置:

"IsDomainSameToHost":true,
"DestDomain":"mydomain.com",

使用临时密钥访问 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");
  // 设置临时密钥
  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"; // 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 << "ErrorInfo=" << result.GetErrorInfo() << 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;
  }
}

查询存储桶列表

#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 << "ErrorInfo=" << result.GetErrorInfo() << 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;
  }
}

上传对象

#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"; // 上传的目的 Bucket 名称
  std::string object_name = "exampleobject"; //exampleobject 即为对象键(Key),是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg。
  // request 的构造函数中需要传入本地文件路径
  qcloud_cos::PutObjectByFileReq req(bucket_name, object_name, "/path/to/local/file");
  req.SetXCosStorageClass("STANDARD_IA"); // 调用 Set 方法设置元数据等
  qcloud_cos::PutObjectByFileResp resp;

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

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

查询对象列表

#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"; // 上传的目标存储桶名称
  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 << "ErrorInfo=" << result.GetErrorInfo() << 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;
  }
}

下载对象

#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"; // 上传的目的 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 << "ErrorInfo=" << result.GetErrorInfo() << 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;
  }
}

删除对象

#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"; // 上传的目标存储桶名称
  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 << "ErrorInfo=" << result.GetErrorInfo() << 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;
  }
}
目录