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

文档中心

导航

初始化客户端（Android SDK）

最近更新时间：2024.09.05 17:26:15首次发布时间：2022.12.01 16:31:39

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

创建 TosClient

使用 STS 参数创建（指定 SecurityToken，推荐）

Android 移动端是一个不受信任的环境，把 accessKey 和 secretKey 直接保存在移动端用来为请求进行签名，风险较高。强烈建议使用 STS 参数创建 TOSV2Client。
STS (Security Token Service) 是一种授权第三方用户临时访问的服务。通过 STS，您可以为第三方应用或子用户提供自定义过期时间的 Token 访问凭证。
TOS 支持通过 STS 进行临时授权访问，在 Android SDK 提供了相应的访问接口。在 SDK 中设置授权的 Token 可访问 TOS 服务。
以下代码展示如何通过 STS 初始化 TOSV2Client。

String endpoint = "your endpoint";
String region = "your region";
String accessKey = "your access key";
String secretKey = "your secret key";
String securityToken = "your security token";

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

使用必选参数创建（Region + Endpoint + AccessKey/SecretKey，不推荐）

TOS 支持的 Region 及 Endpoint 信息，请参见地域及访问域名。
AKSK 信息可从环境变量获取，您可以参考以下步骤在环境变量中配置 AKSK 信息。

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

初始化 TOSV2Client 的示例代码如下。

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, securityToken);
// do your operation...

常见配置场景

配置超时机制

Android SDK 提供了以下超时参数用于 HTTP 请求的超时配置。

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

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

String endpoint = "your endpoint";
String region = "your region";
String accessKey = "your access key";
String secretKey = "your secret key";
String securityToken = "your security token";

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).withSecurityToken(securityToken))
    .build();

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

配置重试策略

从 2.2.0 版本开始，Android SDK 底层添加了重试机制。在客户端请求超时、服务端返回 5xx 错误或 429 错误时，对于可实现幂等语义的接口，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，则不进行重试。

重试策略

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

示例代码

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

String endpoint = "your endpoint";
String region = "your region";
String accessKey = "your access key";
String secretKey = "your secret key";
String securityToken = "your security token";

// 设置重试次数为 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).withSecurityToken(securityToken))
    .build();

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

如果需要关闭重试策略，可以将以上代码中的 maxRetryCount 设置为 小于 0 的值，如 maxRetryCount = -1。

配置数据校验

TOS Android SDK 支持通过 CRC 计算校验上传下载数据的完整性。对于上传接口，包括 PutObject/AppendObject/UploadPart/PutObjectFromFile/UploadFile 接口，请求完成后服务端会返回上传数据的 Crc64 值，SDK 会将其与本地计算的 Crc64 值进行比较，如果不匹配则抛出 TosClientException。
对于 GetObject/GetObjectToFile/DownloadFile 接口，下载过程中会计算 Crc64 值。在下载完成后，SDK 会将服务端携带返回的 Crc64 值与本地计算的 Crc64 值进行比较，如果不匹配则抛出 TosClientException。
Android SDK 默认开启 CRC 校验，以下代码展示如何设置 CRC 校验的开关。

String endpoint = "your endpoint";
String region = "your region";
String accessKey = "your access key";
String secretKey = "your secret key";
String securityToken = "your security token";

// 设置开启 crc 校验机制
boolean enableCrc = true;

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

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

配置 DNS 缓存

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

String endpoint = "your endpoint";
String region = "your region";
String accessKey = "your access key";
String secretKey = "your secret key";
String securityToken = "your security token";

// 设置 DNS 缓存时间为 10 分钟
int dnsCacheTimeMinutes = 10;

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

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

配置代理服务器

Android SDK 从 2.3.0 版本开始，支持配置访问代理服务器，当前只支持 HTTP 协议代理。
以下代码展示如何配置代理服务器。

String endpoint = "your endpoint";
String region = "your region";
String accessKey = "your access key";
String secretKey = "your secret key";
String securityToken = "your security token";

// 代理服务器地址
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).withSecurityToken(securityToken))
    .build();

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

配置连接池

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

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

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

String endpoint = "your endpoint";
String region = "your region";
String accessKey = "your access key";
String secretKey = "your secret key";
String securityToken = "your security token";

int idleConnectionTimeMills = 10000;
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).withSecurityToken(securityToken))
    .build();

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

初始化参数列表

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