文档中心

初始化客户端（Java SDK）

最近更新时间：2024.02.04 18:30:55

首次发布时间：2021.12.27 20:43:29

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

前提条件

配置长期访问凭证

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

macOS

Linux

Windows

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

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****

打开命令行工具，执行以下命令，添加 AKSK 信息。

set TOS_ACCESS_KEY=AKTPYmI1Z****
set TOS_SECRET_KEY=T1dJM01UU****

执行以下命令生效配置信息。

setx TOS_ACCESS_KEY "%TOS_ACCESS_KEY%"
setx TOS_SECRET_KEY "%TOS_SECRET_KEY%"

重启命令行工具，然后执行以下命令验证配置信息。

echo $TOS_ACCESS_KEY
echo $TOS_SECRET_KEY

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

AKTPYmI1Z****
T1dJM01UU****

创建 TosClient

使用必选参数初始化

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

说明

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

import com.volcengine.tos.TOSV2;
import com.volcengine.tos.TOSV2ClientBuilder;

public class CreateTOSV2ClientExample {
    public static void main(String[] args) {
        String endpoint = "your endpoint";
        String region = "your region";
        String accessKey = System.getenv("TOS_ACCESS_KEY");
        String secretKey = System.getenv("TOS_SECRET_KEY");

        TOSV2 tos = new TOSV2ClientBuilder().build(region, endpoint, accessKey, secretKey);
        // do your operation...
    }
}

使用可选参数初始化

TOS Java SDK 提供了多个可选参数来自定义配置 TosClient，如配置 STS，HTTP 请求超时时间，请求重试策略等。以下代码展示如何自定义配置 TosClient 的 HTTP 连接超时时间，具体的配置场景，请参见配置超时机制。

import com.volcengine.tos.TOSClientConfiguration;
import com.volcengine.tos.TOSV2;
import com.volcengine.tos.TOSV2ClientBuilder;
import com.volcengine.tos.auth.StaticCredentials;
import com.volcengine.tos.transport.TransportConfig;

public class CreateTOSV2ClientWithOptionalParamsExample {
    public static void main(String[]  args)  {
        String endpoint = "your endpoint";
        String region = "your region";
        String accessKey = System.getenv("TOS_ACCESS_KEY");
        String secretKey = System.getenv("TOS_SECRET_KEY");
        
        int connectTimeoutMills = 10000;

        TransportConfig config = TransportConfig.builder()
                .connectTimeoutMills(connectTimeoutMills)
                .build();
        TOSClientConfiguration configuration = TOSClientConfiguration.builder()
                .transportConfig(config)
                .region(region)
                .endpoint(endpoint)
                .credentials(new StaticCredentials(accessKey, secretKey))
                .build();

        TOSV2 tos = new TOSV2ClientBuilder().build(configuration);
        // do your operation...
    }
}

常见配置场景

配置 STS

您可以通过 STS 服务向其他用户颁发临时访问凭证，在凭证有效期内，用户可通过访问您的 TOS 资源，而无需透露您的长期密钥，保障您 TOS 资源的安全性。

说明

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

以下代码展示如何使用 STS 的方式初始化 TosClient。

import com.volcengine.tos.TOSV2;
import com.volcengine.tos.TOSV2ClientBuilder;

public class CreateTOSV2ClientWithSTSExample { 
    public static void main(String[] args) {
        String endpoint = "your endpoint";
        String region = "your region";
        // 以下 3 个字段均从 STS 服务中获取
        String accessKeyId = "your access key id";
        String secretAccessKey = "your secret access key";
        String sessionToken = "your secure session token";
    
        TOSV2 tos = new TOSV2ClientBuilder().build(region, endpoint, accessKeyId, secretAccessKey, sessionToken);
        // do your operation...
    }
}

配置超时机制

您可以在初始化 TosClient 时，通过添加可选参数配置网络请求的超时时间。目前 TOS Java SDK 提供了以下超时参数用于 HTTP 请求的超时配置：

readTimeoutMills：HTTP 读请求超时时间，单位毫秒，默认值为 30000，即 30 秒。
writeTimeoutMills：HTTP 写请求超时时间，单位毫秒，默认值为 30000，即 30 秒。
connectTimeoutMills：建立 HTTP 连接的超时时间，单位毫秒，默认值为 10000，即 10 秒。

以下代码展示如何在初始化 TosClient 时配置超时时间。

import com.volcengine.tos.TOSClientConfiguration;
import com.volcengine.tos.TOSV2;
import com.volcengine.tos.TOSV2ClientBuilder;
import com.volcengine.tos.auth.StaticCredentials;
import com.volcengine.tos.transport.TransportConfig;

public class CreateTOSV2ClientWithHttpTimeoutConfigExample {
    public static void main(String[]  args)  {
        String endpoint = "your endpoint";
        String region = "your region";
        String accessKey = System.getenv("TOS_ACCESS_KEY");
        String secretKey = System.getenv("TOS_SECRET_KEY");
        
        int readTimeoutMills = 30000;
        int writeTimeoutMills = 30000;
        int connectTimeoutMills = 10000;

        TransportConfig config = TransportConfig.builder()
                .readTimeoutMills(readTimeoutMills)
                .writeTimeoutMills(writeTimeoutMills)
                .connectTimeoutMills(connectTimeoutMills)
                .build();
        TOSClientConfiguration configuration = TOSClientConfiguration.builder()
                .transportConfig(config)
                .region(region)
                .endpoint(endpoint)
                .credentials(new StaticCredentials(accessKey, secretKey))
                .build();

        TOSV2 tos = new TOSV2ClientBuilder().build(configuration);
        // do your operation...
    }
}

配置重试策略

网络波动或短期 TOS 服务异常（返回 500 HTTP 状态码）等场景会导致请求 TOS 服务失败。针对此问题，Java SDK 内部提供了重试机制。幂等操作的接口在失败后会使用指数退避策略进行重试，非幂接口则直接抛出对应异常。您可以在初始化TosClient时，添加可选参数配置重试次数。

重试场景

以下 SDK 接口在客户端请求超时、服务端返回 5xx 错误或 429 错误时进行重试。
- 所有 GET/HEAD 类型的接口，例如 getObject、headObject、headBucket。
- 部分 PUT/DELETE 类型的接口，例如 putObjectACL、deleteObject。
- 对于 putObject/uploadPart 接口，如果上传的 content（InputStream 类型）支持 markSupported()，可认为是幂等语义。如 content 是一个字符串，本地文件，内存数组 ByteArrayInputStream 等。
- putObjectFromFile/uploadPartFromFile/setObjectMeta 接口。
除 appendObject 外，所有的 POST 类型的 HTTP 接口仅在服务端返回 5xx 错误或 429 错误时进行重试，客户端超时则不重试。

说明

getObject 在返回待下载的数据流后，发生了读异常，如 java.io.IOException: unexpected end of stream，则不进行重试。

重试策略

Java SDK 根据设置的重试次数进行指数退避重试，默认重试次数为 3 次。

示例代码

以下代码展示如何设置 SDK 的重试次数。

import com.volcengine.tos.TOSClientConfiguration;
import com.volcengine.tos.TOSV2;
import com.volcengine.tos.TOSV2ClientBuilder;
import com.volcengine.tos.auth.StaticCredentials;
import com.volcengine.tos.transport.TransportConfig;

public class CreateTOSV2ClientWithRetryConfigExample {
    public static void main(String[]  args)  {
        String endpoint = "your endpoint";
        String region = "your region";
        String accessKey = System.getenv("TOS_ACCESS_KEY");
        String secretKey = System.getenv("TOS_SECRET_KEY");

        // 设置最大重试次数为 3 次，可根据实际需要调整
        int maxRetryCount = 3;

        TransportConfig config = TransportConfig.builder()
                .maxRetryCount(maxRetryCount)
                .build();
        TOSClientConfiguration configuration = TOSClientConfiguration.builder()
                .transportConfig(config)
                .region(region)
                .endpoint(endpoint)
                .credentials(new StaticCredentials(accessKey, secretKey))
                .build();

        TOSV2 tos = new TOSV2ClientBuilder().build(configuration);
        // do your operation...
    }
}

配置数据校验

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

警告

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

import com.volcengine.tos.TOSClientConfiguration;
import com.volcengine.tos.TOSV2;
import com.volcengine.tos.TOSV2ClientBuilder;
import com.volcengine.tos.auth.StaticCredentials;

public class CreateTOSV2ClientWithEnableCrcExample {
    public static void main(String[]  args)  {
        String endpoint = "your endpoint";
        String region = "your region";
        String accessKey = System.getenv("TOS_ACCESS_KEY");
        String secretKey = System.getenv("TOS_SECRET_KEY");

        boolean enableCrc = true;
        
        TOSClientConfiguration configuration = TOSClientConfiguration.builder()
                .region(region)
                .endpoint(endpoint)
                .enableCrc(enableCrc)
                .credentials(new StaticCredentials(accessKey, secretKey))
                .build();

        TOSV2 tos = new TOSV2ClientBuilder().build(configuration);
        // do your operation...
    }
}

配置 DNS 缓存

TOS 服务域名在公网环境下可能出现域名解析耗时或一段时间内无法解析的场景。Java SDK 针对此问题，提供了域名 DNS 缓存机制，将域名解析到的 IP 地址缓存在 SDK 中，无需每次请求都进行域名解析。
SDK 的 DNS 缓存机制默认关闭。以下代码展示如何配置 DNS 缓存时间，默认单位为分钟。

import com.volcengine.tos.TOSClientConfiguration;
import com.volcengine.tos.TOSV2;
import com.volcengine.tos.TOSV2ClientBuilder;
import com.volcengine.tos.auth.StaticCredentials;
import com.volcengine.tos.transport.TransportConfig;

public class CreateTOSV2ClientWitDNSCacheExample {
    public static void main(String[]  args)  {
        String endpoint = "your endpoint";
        String region = "your region";
        String accessKey = System.getenv("TOS_ACCESS_KEY");
        String secretKey = System.getenv("TOS_SECRET_KEY");

        int dnsCacheTimeMinutes = 0;

        TransportConfig config = TransportConfig.builder()
                .dnsCacheTimeMinutes(dnsCacheTimeMinutes)
                .build();
        TOSClientConfiguration configuration = TOSClientConfiguration.builder()
                .transportConfig(config)
                .region(region)
                .endpoint(endpoint)
                .credentials(new StaticCredentials(accessKey, secretKey))
                .build();

        TOSV2 tos = new TOSV2ClientBuilder().build(configuration);
        // do your operation...
    }
}

配置代理服务器

TOS Java SDK 支持通过配置代理服务器的方式访问 TOS 服务。您可以在初始化 TosClient 时，添加可选参数配置代理服务器。
以下代码展示如何配置代理服务器。

import com.volcengine.tos.TOSClientConfiguration;
import com.volcengine.tos.TOSV2;
import com.volcengine.tos.TOSV2ClientBuilder;
import com.volcengine.tos.auth.StaticCredentials;
import com.volcengine.tos.transport.TransportConfig;

public class CreateTOSV2ClientWithProxyExample {
    public static void main(String[]  args)  {
        String endpoint = "your endpoint";
        String region = "your region";
        String accessKey = System.getenv("TOS_ACCESS_KEY");
        String secretKey = System.getenv("TOS_SECRET_KEY");
        
        // 代理服务器地址
        String proxyHost = "your proxy host";
        // 代理服务器端口，请填写您的代理服务器端口，此处仅为示例
        int proxyPort = 8080;
        // 代理服务器用户名
        String proxyUserName = "your proxy user name";
        // 代理服务器密码
        String proxyPassword = "your proxy password";
        
        TransportConfig config = TransportConfig.builder()
                .proxyHost(proxyHost)
                .proxyPort(proxyPort)
                .proxyUserName(proxyUserName)
                .proxyPassword(proxyPassword)
                .build();
        TOSClientConfiguration configuration = TOSClientConfiguration.builder()
                .transportConfig(config)
                .region(region)
                .endpoint(endpoint)
                .credentials(new StaticCredentials(accessKey, secretKey))
                .build();

        TOSV2 tos = new TOSV2ClientBuilder().build(configuration);
        // do your operation...
    }
}

配置连接池

Java SDK 提供了以下参数用于 SDK HTTP 连接池的配置。

idleConnectionTimeMills：HTTP 连接池中连接的空闲时间，超过则关闭该连接，单位毫秒，默认值为 60000，即 60 秒。
maxConnections：HTTP 连接池最大连接数，默认值为 1024。

以下代码展示如何设置以上参数。

import com.volcengine.tos.TOSClientConfiguration;
import com.volcengine.tos.TOSV2;
import com.volcengine.tos.TOSV2ClientBuilder;
import com.volcengine.tos.auth.StaticCredentials;
import com.volcengine.tos.transport.TransportConfig;

public class CreateTOSV2ClientWithIdlegExample {
    public static void main(String[]  args)  {
        String endpoint = "your endpoint";
        String region = "your region";
        String accessKey = System.getenv("TOS_ACCESS_KEY");
        String secretKey = System.getenv("TOS_SECRET_KEY");

        int idleConnectionTimeMills = 60000;
        int maxConnections = 1024;

        TransportConfig config = TransportConfig.builder()
                .idleConnectionTimeMills(idleConnectionTimeMills)
                .maxConnections(maxConnections)
                .build();
        TOSClientConfiguration configuration = TOSClientConfiguration.builder()
                .transportConfig(config)
                .region(region)
                .endpoint(endpoint)
                .credentials(new StaticCredentials(accessKey, secretKey))
                .build();

        TOSV2 tos = new TOSV2ClientBuilder().build(configuration);
        // do your operation...
    }
}

设置自定义域名

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

说明

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

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

import com.volcengine.tos.TOSClientConfiguration;
import com.volcengine.tos.TOSV2;
import com.volcengine.tos.TOSV2ClientBuilder;
import com.volcengine.tos.auth.StaticCredentials;
import com.volcengine.tos.transport.TransportConfig;

public class CreateTOSV2ClientWithCustomDomainExample {
    public static void main(String[] args) {
        // endpoint填写自定义域名
        String endpoint = "your custom domain";
        String region = "your region";
        String accessKey = System.getenv("TOS_ACCESS_KEY");
        String secretKey = System.getenv("TOS_SECRET_KEY");

        TOSClientConfiguration configuration = TOSClientConfiguration.builder()
                .region(region)
                .endpoint(endpoint)
                .isCustomDomain(true)   // 标识当前域名为自定义域名
                .credentials(new StaticCredentials(accessKey, secretKey))
                .build();

        TOSV2 tos = new TOSV2ClientBuilder().build(configuration);
        // do your operation...
    }
}

初始化参数列表

参数	参数类型	是否必选	示例值	说明
accessKey	String	必选	AKTPYmI1Z****	Access Key ID ，即密钥 ID，默认值 null。
secretKey	String	必选	T1dJM01UU****	SecretAccess Key，即私有访问密钥，默认值 null。
endpoint	String	可选，为空时由 region 参数决定	tos-cn-beijing.volces.com	访问域名，默认值 null。
region	String	必选	cn-beijing	TOS 服务端所在地域，默认值 null。
securityToken	String	可选	STSkeyJBY2NvdW50SW************	临时访问凭证中的安全令牌，默认值 null。
writeTimeoutMills	int	可选	30000	HTTP 写请求超时时间，单位毫秒，默认值 30000。
connectTimeoutMills	int	可选	10000	建立连接超时时间，单位毫秒，默认值 10000。
idleConnectionTimeMills	int	可选	60000	连接池中空闲 HTTP 连接时间超过此参数的设定值，则关闭 HTTP 连接，单位：毫秒，默认值 60000。
maxConnections	int	可选	1024	HTTP 连接池最大连接数，默认值 1024。
maxRetryCount	int	可选	3	请求失败后的最大重试次数，默认值 3。
dnsCacheTimeMinutes	int	可选	0	DNS 缓存有效期，单位分钟，小于等于 0 代表关闭 DNS 缓存，默认值 0。
proxyHost	String	可选	"localhost"	代理服务器的主机地址，当前只支持 HTTP 协议，默认值 null。
proxyPort	int	可选	8080	代理服务器的端口号，默认值 0。
proxyUserName	String	可选	"Alice"	连接代理服务器的用户名，默认值 null。
proxyPassword	String	可选	"pwd123"	连接代理服务器使用的用户密码，默认值 null。
enableVerifySSL	boolean	可选	true	是否开启 SSL 证书校验，默认值 true。
enableCrc	boolean	可选	true	是否开启 CRC 校验，默认值 true。
clientAutoRecognizeContentType	boolean	可选	true	是否开启根据对象名扩展名识别 Content-Type，默认值 true。
isCustomDomain	boolean	可选	false	是否为自定义域名。

前提条件

配置长期访问凭证

创建 TosClient

使用必选参数初始化

使用可选参数初始化

常见配置场景

配置 STS

配置超时机制

配置重试策略

配置数据校验

配置 DNS 缓存

配置代理服务器

配置连接池

设置自定义域名

初始化参数列表

对象存储

初始化客户端（Java SDK）

前提条件

配置长期访问凭证

创建 TosClient

使用必选参数初始化

使用可选参数初始化

常见配置场景

配置 STS

配置超时机制

配置重试策略

重试场景

重试策略

示例代码

配置数据校验

配置 DNS 缓存

配置代理服务器

配置连接池

设置自定义域名

初始化参数列表