初始化客户端（C SDK）--对象存储-火山引擎

文档中心

导航

对象存储

初始化客户端（C SDK）

最近更新时间：2024.12.26 14:43:04首次发布时间：2024.12.25 16:21:33

TosClient 提供了一系列接口用与 TOS 服务进行交互，以管理存储桶和对象等 TOS 服务上的资源。可通过 AccessKey/SecretKey、STS (Security Token Service）等方式初始化 TosClient。在初始化时，您可设置建立连接超时时间、最大空闲连接数量等可选参数。本文介绍如何初始化 TOS C SDK。

前提条件

配置长期访问凭证

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

说明

暂不支持在 Windows 系统中使用 C SDK。

macOS

Linux

打开终端并执行以下命令打开文件。

nano ~/.bash_profile

在文件末尾添加 AKSK 信息。

export TOS_ACCESS_KEY=AKTPYmI1Z****
export TOS_SECRET_KEY=T1dJM01UU****

保存文件并退出。
执行以下命令生效配置信息。

source ~/.bash_profile

执行以下命令验证配置信息。

echo $TOS_ACCESS_KEY
echo $TOS_SECRET_KEY

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

AKTPYmI1Z****
T1dJM01UU****

打开终端并执行以下命令打开文件。

sudo vim /etc/profile

在文件末尾添加 AKSK 信息。

export TOS_ACCESS_KEY=AKTPYmI1Z****
export TOS_SECRET_KEY=T1dJM01UU****

保存文件并退出。
执行以下命令生效配置信息。

source /etc/profile

执行以下命令验证配置信息。

echo $TOS_ACCESS_KEY
echo $TOS_SECRET_KEY

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

AKTPYmI1Z****
T1dJM01UU****

创建 TosClient

使用必选参数初始化

以下代码展示如何使用 TOS 域名等必选参数初始化 TosClient，包括 AK、SK、Endpoint 和 Region。

说明

Endpoint 为 TOS 对外服务的访问域名。TOS 支持的 Endpoint 信息，请参见访问域名 Endpoint。
AKSK 信息可从环境变量获取，配置方式，请参见配置访问凭证。

char* ak = getenv("TOS_ACCESS_KEY");
char* sk = getenv("TOS_SECRET_KEY");

void init_client_demo()
{
    /* 等价于 apr_pool_t，用于内存管理的内存池，实现代码在 apr 库中 */
    tos_pool_t *pool;
    tos_client_t *client;
    
    /* 重新创建一个新的内存池，第二个参数是 NULL，表示没有继承自其它内存池 */
    tos_pool_create(&pool, NULL);
    
    /* 创建并初始化 client，这个参数内部主要包括 endpoint,access_key_id,acces_key_secret, curl 参数等全局配置信息
     * client 的内存是由 pool 分配的，后续释放掉 pool 后，client 的内存也相当于释放掉了，不再需要单独释放内存
     */
    client = tos_client_create(pool);
    client->config = tos_config_create(client->pool);
    
    /* tos_str_set 是用 char* 类型的字符串初始化 tos_string_t 类型 */
    /* endpoint 若没有指定HTTP协议（HTTP/HTTPS），默认使用 HTTPS */
    tos_str_set(&client->config->endpoint, "*** Provide your endpoint ***");
    tos_str_set(&client->config->region, "*** Provide your region ***");
    tos_str_set(&client->config->access_key_id, ak);
    tos_str_set(&client->config->access_key_secret, sk);

    tos_pool_destroy(pool);
}

使用可选参数初始化

TOS C SDK 提供了多个可选参数来自定义配置 TosClient。以下代码展示如何自定义配置 TosClient 的建立连接超时时间和读写超时时间。

char* ak = getenv("TOS_ACCESS_KEY");
char* sk = getenv("TOS_SECRET_KEY");

void init_client_demo()
{
    /* 等价于 apr_pool_t，用于内存管理的内存池，实现代码在 apr 库中 */
    tos_pool_t *pool;
    tos_client_t *client;
    
    /* 重新创建一个新的内存池，第二个参数是 NULL，表示没有继承自其它内存池 */
    tos_pool_create(&pool, NULL);
    
    /* 创建并初始化 client，这个参数内部主要包括 endpoint,access_key_id,acces_key_secret, curl 参数等全局配置信息
     * client 的内存是由 pool 分配的，后续释放掉 pool 后，client 的内存也相当于释放掉了，不再需要单独释放内存
     */
    client = tos_client_create(pool);
    client->config = tos_config_create(client->pool);
    
    /* tos_str_set 是用 char* 类型的字符串初始化 tos_string_t 类型 */
    /* endpoint 若没有指定HTTP协议（HTTP/HTTPS），默认使用 HTTPS */
    tos_str_set(&client->config->endpoint, "*** Provide your endpoint ***");
    tos_str_set(&client->config->region, "*** Provide your region ***");
    tos_str_set(&client->config->access_key_id, ak);
    tos_str_set(&client->config->access_key_secret, sk);

    /* 示例中通过 connect_timeout 设置建立连接超时时间(单位为秒)
     * 通过 socket_timeout 设置一次读写连接超时时间(单位为秒)
     */
    client->ctl->options->connect_timeout = 5; 
    client->ctl->options->socket_timeout = 60; 
    tos_pool_destroy(pool);
}

常见配置场景

配置超时机制

在 SDK 中可以通过可选参数调整超时时间，可以通过下列函数对超时参数进行配置：

connect_timeout：设置连接超时，表示在建立连接阶段最长等待时间，单位秒，默认值为 10，即 10 秒。
SetSocketTimeout：设置读写网络流的超时，表示一次 Read/Write 最长等待时间，单位秒，默认值为 120，即 120 秒。

以下代码展示如何设置 SDK 的超时时间。

char* ak = getenv("TOS_ACCESS_KEY");
char* sk = getenv("TOS_SECRET_KEY");

void init_client_demo()
{
    /* 等价于 apr_pool_t，用于内存管理的内存池，实现代码在 apr 库中 */
    tos_pool_t *pool;
    tos_client_t *client;
    
    /* 重新创建一个新的内存池，第二个参数是 NULL，表示没有继承自其它内存池 */
    tos_pool_create(&pool, NULL);
    
    /* 创建并初始化 client，这个参数内部主要包括 endpoint,access_key_id,acces_key_secret, curl 参数等全局配置信息
     * client 的内存是由 pool 分配的，后续释放掉 pool 后，client 的内存也相当于释放掉了，不再需要单独释放内存
     */
    client = tos_client_create(pool);
    client->config = tos_config_create(client->pool);
    
    /* tos_str_set 是用 char* 类型的字符串初始化 tos_string_t 类型 */
    /* endpoint 若没有指定HTTP协议（HTTP/HTTPS），默认使用 HTTPS */
    tos_str_set(&client->config->endpoint, "*** Provide your endpoint ***");
    tos_str_set(&client->config->region, "*** Provide your region ***");
    tos_str_set(&client->config->access_key_id, ak);
    tos_str_set(&client->config->access_key_secret, sk);

    /* 示例中通过 connect_timeout 设置建立连接超时时间(单位为秒)
     * 通过 socket_timeout 设置一次读写连接超时时间(单位为秒)
     */
    client->ctl->options->connect_timeout = 5; 
    client->ctl->options->socket_timeout = 60; 
    tos_pool_destroy(pool);
}

初始化参数列表

参数名	参数类型	是否必选	示例值	说明
access_key_id	String	必选	AKTPYmI1ZGQwMDA0NjlhNGFkMzhjNzM0N2Q0OTQ3ZTV****	Access Key ID ，即密钥 ID。
access_key_secret	String	必选	T1dJM01UUXpOak0wTVdWak5E0poWldJNU1HWmxaV1V5TkdReVl6****	SecretAccess Key，即私有访问密钥。
endpoint	String	可选，为空时由 Region 参数决定	tos-cn-beijing.volces.com	TOS 服务端访问域名。
region	String	可选，Endpoint 为空时必选	cn-beijing	TOS 服务端所在地域。
sts_token	String	可选	STSeyJBY2NvdW50SWQiOjIxMDAwMDUyMjQsIklkZW50aXR5VHlwZSI6NCwiSWRlbnRpdHlJZCI6MTE3MjI5NiwiQ2hhbm5lbCI6IlVzZXIiLCJBY2Nlc3NLZXlJZCI6IkFLVFBZbUkxWkdRd01mxoTkdGa016aGpOek0wTjJRME9UUTNaVFZqTXpFIiwiU2l****	临时访问凭证中的安全令牌。
socket_timeout	Int	可选	120	Socket 读写超时时间，单位毫秒，默认值为 30000ms，即 30s。
connect_timeout	Int	可选	10	设置建立连接超时时间，单位毫秒，默认值为 10000ms，即 10s。