You need to enable JavaScript to run this app.
导航

初始化客户端(C++ SDK)

最近更新时间2024.02.27 18:04:06

首次发布时间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

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