对象存储
对象存储
对象存储
文档指南
请输入
产品动态
产品公告
产品计费
快速入门
用户指南
存储桶管理
基础设置
容错与容灾
ObjectSet
文件管理
监控与告警
权限配置
IAM 策略管理
典型配置场景
IAM 子用户授权
使用工具及 SDK 的授权说明
接入点
单区域接入点（SRAP）
内容感知与处理（SenseFlow）
TOS Agent
数据处理
分层命名空间（HNS）
TOS Vectors
API 参考
向量桶
SDK 参考
Python-Vectors
向量桶
向量索引
Java-Vectors
向量桶
向量索引
Node.js-Vectors
向量桶
向量索引
工具指南
tosutil
常用命令
辅助命令
TOS Browser
FSX
TOS PyTorch Connector
tosfsspec
API 参考
签名机制
存储桶
桶基础操作
自定义域名
数据处理
媒体处理
视频转码
音频转码
ObjectSet
生命周期
对象
基础操作
分片上传
SDK 参考
Java
存储桶接口
管理桶配置
ObjectSet
对象接口
下载对象
数据处理
视频处理
日志配置
分层命名空间
Python
数据处理
存储桶接口
对象接口
上传对象
C++
存储桶接口
对象接口
Go
对象接口
存储桶接口
管理桶配置
ObjectSet
数据处理
日志配置
Node.js
存储桶接口
对象接口
上传对象
数据处理
Browser.js
上传对象
.NET
对象接口
PHP
对象接口
异常处理
Android
对象接口
iOS
对象接口
Harmony
存储桶接口
对象接口
上传对象
Rust
存储桶接口
桶基础操作
桶清单
自定义域名
对象接口
基础操作
错误码
01-SERVICE_ERROR
02-AUTH
03-ACCESS_CONTROL
04-QOS
05-REQUEST
06-BUCKET
07-LIFECYCLE
08-ACL
09-CORS
10-POLICY
11-MIRROR
12-REPLICATION
13-WEBSITE
14-NOTIFICATION
15-ENCRYPT
16-CUSTOMDOMAIN
17-OBJECT
18-TAG
19-MULTIPART
20-STORAGE_CLASS
21-CALLBACK
22-DATA_PROCESS
23-BATCH
24-STORAGE_LENS
25-INVENTORY
26-DIRECTORY_BUCKET
32-WORM
常见问题
最佳实践
AIGC-豆包大模型最佳实践
校验数据一致性
- 文档首页
对象存储TOS VectorsSDK 参考Java-Vectors初始化客户端（TOS Vectors Java SDK）
复制全文
下载 pdf初始化客户端（TOS Vectors Java SDK）
文档反馈
问问助手本文介绍如何初始化 TOS Vectors Java SDK。
背景信息
TOSVectorsClient 提供了一系列接口用于与 TOS Vectors 服务进行交互，以管理存储桶和对象等 TOS Vectors 服务上的资源。可通过 AccessKey/SecretKey、STS (Security Token Service）等方式初始化 TOSVectorsClient。在初始化时，您可设置建立连接超时时间、超时重试次数和最大空闲连接数量等可选参数。
前提条件
配置长期访问凭证
初始化 SDK 前，您需要先配置长期访问凭证。本章节介绍不同操作系统下配置长期访问凭证的操作步骤。
macOS
Linux
Windows
- 打开终端并执行以下命令打开文件。
- nano ~/.bash_profile
- 在文件末尾添加 AKSK 信息。
- export TOS_ACCESS_KEY=AKTPYmI1Z****export TOS_SECRET_KEY=T1dJM01UU****
- 保存文件并退出。
- 执行以下命令生效配置信息。
- source ~/.bash_profile
- 执行以下命令验证配置信息。
- echo $TOS_ACCESS_KEYecho $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_KEYecho $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****
创建 TOSVectorsClient
使用必选参数初始化
以下代码展示如何使用 TOS Vectors 域名等必选参数初始化 TOSVectorsClient，包括 AccessKey、SecretKey、Endpoint 和 Region。
说明
- Endpoint 为 TOS 对外服务的访问域名。TOS 支持的 Endpoint 信息，请参见地域和访问域名（Endpoint）。
- AK/SK 信息可从环境变量获取，配置方式，请参见配置长期访问凭证。
import com.volcengine.tos.TOSVectors;
import com.volcengine.tos.TOSVectorsClientBuilder;
public class CreateTOSVectorsClientExample {
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");
TOSVectors client = new TOSVectorsClientBuilder().build(region, endpoint, accessKey, secretKey);
// do your operation...
}
}
使用可选参数初始化
TOS Vectors Java SDK 提供了多个可选参数来自定义配置 TOSVectorsClient，如配置 STS，HTTP 请求超时时间，请求重试策略等。以下代码展示如何自定义配置 TOSVectorsClient 的 HTTP 连接超时时间，具体的配置场景，请参见配置超时机制。
import com.volcengine.tos.TOSVectorsClientConfiguration;
import com.volcengine.tos.TOSVectors;
import com.volcengine.tos.TOSVectorsClientBuilder;
import com.volcengine.tos.credential.StaticCredentialsProvider;
import com.volcengine.tos.transport.TransportConfig;
public class CreateTOSVectorsClientWithOptionalParamsExample {
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();
TOSVectorsClientConfiguration configuration = TOSVectorsClientConfiguration.builder()
.transportConfig(config)
.region(region)
.endpoint(endpoint)
.credentialsProvider(new StaticCredentialsProvider(accessKey, secretKey))
.build();
TOSVectors tos = new TOSVectorsClientBuilder().build(configuration);
// do your operation...
}
}
常见配置场景
配置 STS
您可以通过 STS 服务向其他用户颁发临时访问凭证，在凭证有效期内，用户可通过访问您的 TOS 资源，而无需透露您的长期密钥，保障您 TOS 资源的安全性。
说明
您可以通过 STS 服务的 AssumeRole 接口获取临时访问凭证，临时访问凭证中包含安全密钥（AccessKeyId、SecretAccessKey）和安全令牌（SessionToken），后续您可以使用该信息访问 TOS 服务。关于搭建 STS 服务的基本操作，请参见使用 STS 临时 AK/SK+Token 访问火山引擎 TOS。
以下代码展示如何使用 STS 的方式初始化 TOSVectorsClient。
import com.volcengine.tos.TOSVectors;
import com.volcengine.tos.TOSVectorsClientBuilder;
public class CreateTOSVectorsClientWithSTSExample {
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";
TOSVectors tos = new TOSVectorsClientBuilder().build(region, endpoint, accessKeyId, secretAccessKey, sessionToken);
// do your operation...
}
}
配置超时机制
您可以在初始化 TOSVectorsClient 时，通过添加可选参数配置网络请求的超时时间。目前 TOS Vectors Java SDK 提供了以下超时参数用于 HTTP 请求的超时配置：
- readTimeoutMills：HTTP 读请求超时时间，单位毫秒，默认值为 30000，即 30 秒。
- writeTimeoutMills：HTTP 写请求超时时间，单位毫秒，默认值为 30000，即 30 秒。
- connectTimeoutMills：建立 HTTP 连接的超时时间，单位毫秒，默认值为 10000，即 10 秒。
以下代码展示如何在初始化 TOSVectorsClient 时配置超时时间。
import com.volcengine.tos.TOSVectorsClientConfiguration;
import com.volcengine.tos.TOSVectors;
import com.volcengine.tos.TOSVectorsClientBuilder;
import com.volcengine.tos.credential.StaticCredentialsProvider;
import com.volcengine.tos.transport.TransportConfig;
public class CreateTOSVectorsClientWithHttpTimeoutConfigExample {
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();
TOSVectorsClientConfiguration configuration = TOSVectorsClientConfiguration.builder()
.transportConfig(config)
.region(region)
.endpoint(endpoint)
.credentialsProvider(new StaticCredentialsProvider(accessKey, secretKey))
.build();
TOSVectors tos = new TOSVectorsClientBuilder().build(configuration);
// do your operation...
}
}
配置重试策略
网络波动或短期 TOS Vectors 服务异常（返回 500 HTTP 状态码）等场景会导致请求 TOS Vectors 服务失败。针对此问题，Java SDK 内部提供了重试机制。幂等操作的接口在失败后会使用指数退避策略进行重试，非幂接口则直接抛出对应异常。您可以在初始化 TOSVectorsClient 时，添加可选参数配置重试次数。
重试策略
Java SDK 根据设置的重试次数进行指数退避重试，默认重试次数为 3 次。
示例代码
以下代码展示如何设置 SDK 的重试次数。
import com.volcengine.tos.TOSVectorsClientConfiguration;
import com.volcengine.tos.TOSVectors;
import com.volcengine.tos.TOSVectorsClientBuilder;
import com.volcengine.tos.credential.StaticCredentialsProvider;
import com.volcengine.tos.transport.TransportConfig;
public class CreateTOSVectorsClientWithRetryConfigExample {
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();
TOSVectorsClientConfiguration configuration = TOSVectorsClientConfiguration.builder()
.transportConfig(config)
.region(region)
.endpoint(endpoint)
.credentialsProvider(new StaticCredentialsProvider(accessKey, secretKey))
.build();
TOSVectors tos = new TOSVectorsClientBuilder().build(configuration);
// do your operation...
}
}
配置 DNS 缓存
TOS Vectors 服务域名在公网环境下可能出现域名解析耗时或一段时间内无法解析的场景。Java SDK 针对此问题，提供了域名 DNS 缓存机制，将域名解析到的 IP 地址缓存在 SDK 中，无需每次请求都进行域名解析。
SDK 的 DNS 缓存机制默认关闭。以下代码展示如何配置 DNS 缓存时间，默认单位为分钟。
import com.volcengine.tos.TOSVectorsClientConfiguration;
import com.volcengine.tos.TOSVectors;
import com.volcengine.tos.TOSVectorsClientBuilder;
import com.volcengine.tos.credential.StaticCredentialsProvider;
import com.volcengine.tos.transport.TransportConfig;
public class CreateTOSVectorsClientWitDNSCacheExample {
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();
TOSVectorsClientConfiguration configuration = TOSVectorsClientConfiguration.builder()
.transportConfig(config)
.region(region)
.endpoint(endpoint)
.credentialsProvider(new StaticCredentialsProvider(accessKey, secretKey))
.build();
TOSVectors tos = new TOSVectorsClientBuilder().build(configuration);
// do your operation...
}
}
配置代理服务器
TOS Vectors Java SDK 支持通过配置代理服务器的方式访问 TOS Vectors 服务。您可以在初始化 TOSVectorsClient 时，添加可选参数配置代理服务器。
以下代码展示如何配置代理服务器。
import com.volcengine.tos.TOSVectorsClientConfiguration;
import com.volcengine.tos.TOSVectors;
import com.volcengine.tos.TOSVectorsClientBuilder;
import com.volcengine.tos.credential.StaticCredentialsProvider;
import com.volcengine.tos.transport.TransportConfig;
public class CreateTOSVectorsClientWithProxyExample {
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();
TOSVectorsClientConfiguration configuration = TOSVectorsClientConfiguration.builder()
.transportConfig(config)
.region(region)
.endpoint(endpoint)
.credentialsProvider(new StaticCredentialsProvider(accessKey, secretKey))
.build();
TOSVectors tos = new TOSVectorsClientBuilder().build(configuration);
// do your operation...
}
}
配置连接池
Java SDK 提供了以下参数用于 SDK HTTP 连接池的配置。
- idleConnectionTimeMills：HTTP 连接池中连接的空闲时间，超过则关闭该连接，单位毫秒，默认值为 60000，即 60 秒。
- maxConnections：HTTP 连接池最大连接数，默认值为 1024。
以下代码展示如何设置以上参数。
import com.volcengine.tos.TOSVectorsClientConfiguration;
import com.volcengine.tos.TOSVectors;
import com.volcengine.tos.TOSVectorsClientBuilder;
import com.volcengine.tos.credential.StaticCredentialsProvider;
import com.volcengine.tos.transport.TransportConfig;
public class CreateTOSVectorsClientWithIdlegExample {
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();
TOSVectorsClientConfiguration configuration = TOSVectorsClientConfiguration.builder()
.transportConfig(config)
.region(region)
.endpoint(endpoint)
.credentialsProvider(new StaticCredentialsProvider(accessKey, secretKey))
.build();
TOSVectors tos = new TOSVectorsClientBuilder().build(configuration);
// do your operation...
}
}
配置 User-Agent 拓展信息
TOS Vectors Java SDK 支持客户配置自定义业务信息到 User-Agent 中。您可以在初始化 TOSVectorsClient 时，添加可选参数配置 User-Agent 拓展信息。
User-Agent 拓展信息规范如下：
// 扩展模版
ve-tos-{sdk_type}-sdk/{sdk_version} ({os_type}/{cpu_arch};{language_version}) -- {product_name}/{soft_name}/{soft_version} ({custom_key1}/{custom_value1};{custom_key2}/{custom_value2};{custom_key3}/{custom_value3})
// 扩展后示例
ve-tos-java-sdk/v2.8.1 (linux/amd64;11.0.19) -- EMR/Hadoop/v3.0.0 (cloud_type/volc;cloud_region/cn-beijing)
以下代码展示如何配置 User-Agent 拓展信息。
import com.volcengine.tos.TOSVectorsClientConfiguration;
import com.volcengine.tos.TOSVectors;
import com.volcengine.tos.TOSVectorsClientBuilder;
import com.volcengine.tos.credential.StaticCredentialsProvider;
import com.volcengine.tos.transport.TransportConfig;
import java.util.HashMap;
import java.util.Map;
public class CreateTOSVectorsClientWithProxyExample {
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");
Map<String, String> customInfo = new HashMap<>();
customInfo.put("cloud_type", "volc");
customInfo.put("cloud_region", "cn-beijing");
TOSVectorsClientConfiguration configuration = TOSVectorsClientConfiguration.builder()
.region(region)
.endpoint(endpoint)
.credentialsProvider(new StaticCredentialsProvider(accessKey, secretKey))
.userAgentProductName("EMR")
.userAgentSoftName("Spark")
.userAgentSoftVersion("v3.1.2")
.userAgentCustomizedKeyValues(customInfo)
.build();
TOSVectors tos = new TOSVectorsClientBuilder().build(configuration);
// do your operation...
}
}
初始化参数列表
参数 | 参数类型 | 是否必选 | 示例值 | 说明 |
参数 | 参数类型 | 是否必选 | 示例值 | 说明 |
accessKey | String | 必选 | AKTPYmI1Z**** | Access Key ID ，即密钥 ID。 |
secretKey | String | 必选 | T1dJM01UU**** | SecretAccess Key，即私有访问密钥。 |
endpoint | String | 可选，为空时由 region 参数决定 | tosvectors-cn-beijing.volces.com | 访问域名。 |
region | String | 必选 | cn-beijing | TOS Vectors 服务端所在地域。 |
securityToken | String | 可选 | STSkeyJBY2NvdW50SW************ | 临时访问凭证中的安全令牌。 |
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 协议。 |
proxyPort | int | 可选 | 8080 | 代理服务器的端口号，默认值为 0。 |
proxyUserName | String | 可选 | Alice | 连接代理服务器的用户名。 |
proxyPassword | String | 可选 | pwd123 | 连接代理服务器使用的用户密码。 |
enableVerifySSL | boolean | 可选 | true | 是否开启 SSL 证书校验，默认值为 true。 |
最近更新时间：2026.07.31 10:31:30
这个页面对您有帮助吗？
有用
有用
无用
无用