You need to enable JavaScript to run this app.
导航
对象存储
  • 文档首页
    • /对象存储/SDK 参考/C++/初始化客户端（C++ SDK）
初始化客户端（C++ SDK）
最近更新时间：2024.09.05 17:26:15首次发布时间：2022.04.08 10:56:29
我的收藏

TOSClient 提供了一系列接口用来与 TOS 服务进行交互，以管理存储桶和对象等 TOS 服务上的资源。您可通过 AccessKey/SecretKey、STS (Security Token Service）等方式初始化 TOSClient。初始化 TOSClient 时，TOS 还支持设置建立连接超时时间等可选参数，您可以根据业务需求，参考本文进行设置。
初始化 TosClient 时，需要带上 AccessKey、SecretKey 和 Region。

前提条件

配置长期访问凭证

初始化 SDK 前，您需要先配置长期访问凭证。本章节介绍不同操作系统下配置长期访问凭证的操作步骤。

  1. 打开终端并执行以下命令打开文件。
nano ~/.bash_profile
  1. 在文件末尾添加 AKSK 信息。
export TOS_ACCESS_KEY=AKTPYmI1Z****
export TOS_SECRET_KEY=T1dJM01UU****
  1. 保存文件并退出。
  2. 执行以下命令生效配置信息。
source ~/.bash_profile
  1. 执行以下命令验证配置信息。
echo $TOS_ACCESS_KEY
echo $TOS_SECRET_KEY

如果配置成功，则返回如下示例：

AKTPYmI1Z****
T1dJM01UU****

创建 TosClient

注意

  • TosClient 实例是线程安全的，允许多线程使用同一 TosClient 实例。您可以创建一个 TosClient 实例在多线程中调用，也可以创建多个 TosClient 实例，分别使用。
  • InitializeClient() 和 CloseClient() 是全局性接口，在程序生命周期内仅需要调用一次。

设置必选参数

TosClient 用于管理存储桶（Bucket）和文件（Object）等 TOS 资源。仅使用必选参数 AccessKey、SecretKey 和 Region 初始化 TosClient 的示例代码如下。

说明

  • Endpoint 为 TOS 对外服务的访问域名。TOS 支持的 Endpoint 信息，请参见访问域名 Endpoint。
  • AKSK 信息可从环境变量获取，配置方式，请参见配置访问凭证。
#include "TosClientV2.h"
using namespace VolcengineTos;

int main(void){
    // 初始化 TOS 账号信息
    // Your Region 填写 Bucket 所在 Region
    std::string region = "Your Region";
    // 从环境变量中获取访问密钥
    std::string accessKey = std::getenv("TOS_ACCESS_KEY");
    std::string secretKey = std::getenv("TOS_SECRET_KEY");
    
    // 初始化网络等资源
    InitializeClient();
    // 创建交互的 client
    TosClientV2 client(region, accessKey, secretKey);
    // 释放网络等资源
    CloseClient();
    return 0;
}

常见配置场景

ClientConfig 是 TOSClient 的配置类，可配置 endpoint、超时时间、是否进行 CRC 数据校验等参数。使用 C++ SDK 发起请求时，您需要初始化一个 TosClient 实例，并根据需要修改 ClientConfig 的默认配置项。

配置 STS

如果您不希望透露长期使用的密钥信息，您可以通过 STS 服务，创建一个临时访问凭证，使用户能在指定时间内访问 TOS 资源，过期即失效，有效保证您的资源安全。

说明

您可以通过调用 STS 服务的 AssumeRole 接口来获取临时访问凭证。临时访问凭证包括临时访问密钥（AccessKeyId 和 AccessKeySecret）和安全令牌（SecurityToken）。后续您可以使用该信息访问 TOS 服务。关于搭建 STS 服务的具体操作，请参见使用 STS 临时 AK/SK+Token 访问火山引擎 TOS。

以下代码示例用于配置基于 STS Token 初始化 TOS C++ SDK。

#include "TosClientV2.h"
using namespace VolcengineTos;

int main(void){
    // 初始化 TOS 账号信息
    // Your Region 填写 Bucket 所在 Region
    std::string region = "Your Region";
    std::string accessKey = "Your Access Key";
    std::string secretKey = "Your Secret Key";
    // securityToken为临时访问凭证中的安全令牌
    std::string securityToken = "Your Security Token";
    
    // 初始化网络等资源
    InitializeClient();
    // STS 场景下仅使用必选参数创建交互的 client
    TosClientV2 client(region, accessKey,secretKey, securityToken);
    
    // STS 场景下使用自定义参数配置 endpoint、超时时间等创建 client 可以参考如下代码
    // ClientConfig conf;
    // conf.xxx = xxx
    // TosClientV2 client(region, accessKey,secretKey, securityToken, conf);
    
    // 释放网络等资源
    CloseClient();
    return 0;
}

配置超时机制

您可以在初始化 TosClient 时，通过添加可选参数配置网络请求的超时时间，目前 TOS C++ SDK 支持配置建立连接超时 connectionTimeout 和读写请求超时 socketTimeout。以下代码示例用于配置超时机制：

#include "TosClientV2.h"
using namespace VolcengineTos;

int main(void){
    // 初始化 TOS 账号信息
    // Your Region 填写 Bucket 所在 Region
    std::string region = "Your Region";
    // 从环境变量中获取访问密钥
    std::string accessKey = std::getenv("TOS_ACCESS_KEY");
    std::string secretKey = std::getenv("TOS_SECRET_KEY");
    
    // ClientConfig 是 TOSClient 的配置类，可配置 endpoint、超时时间、是否进行 CRC 数据校验等参数。
    ClientConfig conf;
    // 设置建立连接超时时间，单位：毫秒，默认 10000 毫秒。
    conf.connectionTimeout = 10000;
    // 设置一次读写 http 请求超时时间，单位：毫秒，默认 30000 毫秒。
    conf.socketTimeout = 30000;
    
    // 初始化网络等资源
    InitializeClient();
    // 创建交互的 client
    TosClientV2 client(region, accessKey, secretKey,conf);
    // 释放网络等资源
    CloseClient();
    return 0;
}

配置重试策略

TOS C++ SDK 通过初始化参数 maxRetryCount 配置请求失败后的重试次数，以解决网络抖动等问题造成的请求失败，降低用户遭遇偶现错误的概率。对于请求超时，服务端返回 5xx 错误或 429 错误时，会对可幂等语义的场景，依据重试次数指数退避的方式进行重试。
TOS 重试时会以 100ms 为基础进行指数退避直到到达最大重试次数，例如，最大重试次数是 3 次时，重试间隔分别为 100ms、200ms、400ms。

说明

如果要关闭重试机制，可以将 maxRetryCount 配置为 <= 0。

以下代码示例用于配置重试策略。

#include "TosClientV2.h"
using namespace VolcengineTos;

int main(void){
    // 初始化 TOS 账号信息
    // Your Region 填写 Bucket 所在 Region
    std::string region = "Your Region";
    // 从环境变量中获取访问密钥
    std::string accessKey = std::getenv("TOS_ACCESS_KEY");
    std::string secretKey = std::getenv("TOS_SECRET_KEY");
    // ClientConfig 是 TOSClient 的配置类，可配置 endpoint、超时时间、是否进行 CRC 数据校验等参数。
    ClientConfig conf;
    // 请求失败最大重试次数。默认 3 次。
    conf.maxRetryCount = 3;
    // 初始化网络等资源
    InitializeClient();
    // 创建交互的 client
    TosClientV2 client(region, accessKey, secretKey,conf);
    // 释放网络等资源
    CloseClient();
    return 0;
}

配置数据校验

对象上传和下载时 TOS 服务端会返回对象的 Crc64 值，SDK 验证本地计算的 Crc64 和 TOS 返回的 Crc64 是否相等，校验上传和下载数据的完整性。为确保上传和下载过程中数据的完整性，SDK 默认开启 Crc64 数据校验，您可以在初始化 TosClient 时，添加可选参数关闭 Crc64 校验功能。

警告

强烈建议您不要关闭 Crc64 数据校验功能。若关闭此功能，TOS 不保障上传和下载过程中数据完整性。

以下代码示例用于设置 CRC 校验。

#include "TosClientV2.h"
using namespace VolcengineTos;

int main(void){
    // 初始化 TOS 账号信息
    // Your Region 填写 Bucket 所在 Region
    std::string region = "Your Region";
    // 从环境变量中获取访问密钥
    std::string accessKey = std::getenv("TOS_ACCESS_KEY");
    std::string secretKey = std::getenv("TOS_SECRET_KEY");
    // ClientConfig 是 TOSClient 的配置类，可配置 endpoint、超时时间、是否进行 CRC 数据校验等参数。
    ClientConfig conf;
    // 是否开启 CRC 数据校验，默认开启，如果要关闭，指定参数为 false
    conf.enableCRC = true;
    // 初始化网络等资源
    InitializeClient();
    // 创建交互的 client
    TosClientV2 client(region, accessKey, secretKey,conf);
    // 释放网络等资源
    CloseClient();
    return 0;
}

配置 DNS 缓存

由于公网环境中可能出现 TOS 服务域名解析较为耗时或一段时间内域名无法解析的场景，因此在 TOS C++ SDK 支持通过初始化参数 dnsCacheTime 配置 DNS 缓存有效期。默认值为 0，代表关闭域名缓存特性。以下代码示例用于设置 DNS 缓存。

#include "TosClientV2.h"
using namespace VolcengineTos;

int main(void){
    // 初始化 TOS 账号信息
    // Your Region 填写 Bucket 所在 Region
    std::string region = "Your Region";
      // 从环境变量中获取访问密钥
    std::string accessKey = std::getenv("TOS_ACCESS_KEY");
    std::string secretKey = std::getenv("TOS_SECRET_KEY");
    
    // ClientConfig 是 TOSClient 的配置类，可配置 endpoint、超时时间、是否进行 CRC 数据校验等参数。
    ClientConfig conf;
    // DNS 缓存的有效期，单位：分钟，小于等于 0 时代表关闭 DNS 缓存，默认为 0。
    conf.dnsCacheTime = 3;
    
    // 初始化网络等资源
    InitializeClient();
    // 创建交互的 client
    TosClientV2 client(region, accessKey, secretKey,conf);
    // 释放网络等资源
    CloseClient();
    return 0;
}

配置代理服务器

TOS C++ SDK 支持配置代理服务器的方式访问 TOS 服务，您可以在初始化 TosClient 时，添加可选参数配置代理服务器。

说明

目前只支持 HTTP 协议代理。

以下代码用于设置代理服务器。

#include "TosClientV2.h"
using namespace VolcengineTos;

int main(void){
    // 初始化 TOS 账号信息
    // Your Region 填写 Bucket 所在 Region
    std::string region = "Your Region";
      // 从环境变量中获取访问密钥
    std::string accessKey = std::getenv("TOS_ACCESS_KEY");
    std::string secretKey = std::getenv("TOS_SECRET_KEY");
    
    // ClientConfig 是 TOSClient 的配置类，可配置 endpoint、超时时间、是否进行 CRC 数据校验等参数。
    ClientConfig conf;
    // 代理服务器的主机地址，当前只支持 HTTP 协议。
    conf.proxyHost = http::SchemeHTTP;
    // 代理服务器的端口号。
    conf.proxyPort = 80;
    // 连接代理服务器时使用的用户名。
    conf.proxyUsername = "Your Proxy UserName";
    // 连接代理服务器时使用的用户密码
    conf.proxyPassword = "your Proxy Password";
    
    // 初始化网络等资源
    InitializeClient();
    // 创建交互的 client
    TosClientV2 client(region, accessKey, secretKey,conf);
    // 释放网络等资源
    CloseClient();
    return 0;
}

配置连接池

TOS C++ SDK 支持连接池配置，您可以在初始化 TosClient 时，添加可选参数配置连接池大小。
以下代码用于配置连接池。

#include "TosClientV2.h"
using namespace VolcengineTos;

int main(void){
    // 初始化 TOS 账号信息
    // Your Region 填写 Bucket 所在 Region
    std::string region = "Your Region";
      // 从环境变量中获取访问密钥
    std::string accessKey = std::getenv("TOS_ACCESS_KEY");
    std::string secretKey = std::getenv("TOS_SECRET_KEY");
    
    // ClientConfig 是 TOSClient 的配置类，可配置 endpoint、超时时间、是否进行 CRC 数据校验等参数。
    ClientConfig conf;
    // 连接池最大连接数
    conf.maxConnections = 64;
    
    // 初始化网络等资源
    InitializeClient();
    // 创建交互的 client
    TosClientV2 client(region, accessKey, secretKey,conf);
    // 释放网络等资源
    CloseClient();
    return 0;
}

设置自定义域名

TOS C++ SDK 支持设置自定义域名，您可以在初始化 TosClient 时，传入自定义域名作为 Host。指定自定义域名后，使用 SDK 接口中无需传入 Bucket 。

说明

使用自定义域名前需要在服务端配置自定义域名，详情请参见设置自定义域名。

在 SDK 中，可以通过 isCustomDomain 标识当前域名为自定义域名。

#include "TosClientV2.h"
using namespace VolcengineTos;

int main(void){
    // 初始化 TOS 账号信息
    // Your Region 填写 Bucket 所在 Region
    std::string region = "Your Region";
    // 从环境变量中获取访问密钥
    std::string accessKey = std::getenv("TOS_ACCESS_KEY");
    std::string secretKey = std::getenv("TOS_SECRET_KEY");
    
    // ClientConfig 是 TOSClient 的配置类，可配置 endpoint、超时时间、是否进行 CRC 数据校验等参数。
    ClientConfig conf;
    // 使用自定义域名
    conf.endPoint = "your custom endpoint";
    conf.isCustomDomain = true;

    // 初始化网络等资源
    InitializeClient();
    // 创建交互的 client
    TosClientV2 client(region, accessKey, secretKey, conf);
    // 释放网络等资源
    CloseClient();
    return 0;
}

初始化参数列表

初始化 TOSClient 时可选的参数如下。

参数

参数类型

是否必选

示例值

说明

ak

string

必选

AKTPYmI1Z****

Access Key ID，即密钥ID 。

sk

string

必选

T1dJM01UU****

SecretAccess Key ，即私有访问密钥 。

region

string

必选

cn-beijing

TOS 服务端所在地域 。

securityToken

string

可选

STSkeyJBY2NvdW50SW************

临时访问凭证中的安全令牌 。

endPoint

string

可选

tos-cn-beijing.volces.com

TOS 服务端域名，默认为空。 如果没有指定协议，则默认使用 HTTPS 协议，完整格式为 https://{host}:{port}。

enableVerifySSL

bool

可选

true

配置是否开启 SSL 证书校验，默认开启。

autoRecognizeContentType

bool

可选

true

自动识别 MIME 类型，默认开启。

requestTimeout

int

可选

120000

设置一次 http 请求超时时间，单位：毫秒，默认 120000 毫秒。

connectionTimeout

int

可选

10000

设置建立连接超时时间，单位：毫秒，默认 10000 毫秒。

enableCRC

bool

可选

true

是否开启 CRC 数据校验，默认开启。

dnsCacheTime

int

可选

3

DNS 缓存的有效期，单位：分钟，小于等于 0 时代表关闭 DNS 缓存，默认为 0。

proxyHost

string

可选

localhost

代理服务器的主机地址，当前只支持 HTTP 协议。

proxyPort

int

可选

8080

代理服务器的端口号。

proxyUsername

string

可选

Alice

连接代理服务器时使用的用户名。

proxyPassword

string

可选

pwd123

连接代理服务器时使用的用户密码。

maxRetryCount

int

可选

3

请求失败最大重试次数。默认 3 次。

maxConnections

int

可选

25

连接池最大连接数。默认值 25。

socketTimeout

int

可选

30000

请求超时时间。请求超时没有收到数据将会关闭连接，默认为 30000 毫秒。

isCustomDomain

bool

可选

false

是否为自定义域名。默认否。