对象存储
对象存储
对象存储
文档指南
请输入
产品动态
产品公告
产品计费
快速入门
用户指南
存储桶管理
基础设置
容错与容灾
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-豆包大模型最佳实践
校验数据一致性
- 文档首页
对象存储SDK 参考Java快速入门（Java SDK）
复制全文
下载 pdf快速入门（Java SDK）
文档反馈
问问助手本文介绍如何快速使用 TOS Java SDK 完成常见操作，包括客户端通用示例、创建桶、上传对象、下载对象、列举对象和删除对象。
前提条件
示例代码
客户端通用示例
以下代码以上传对象为例，展示使用 TOS Java SDK 的通用代码模版。
import com.volcengine.tos.TOSV2;
import com.volcengine.tos.TOSV2ClientBuilder;
import com.volcengine.tos.TosClientException;
import com.volcengine.tos.TosServerException;
import com.volcengine.tos.model.object.PutObjectInput;
import com.volcengine.tos.model.object.PutObjectOutput;
import java.io.ByteArrayInputStream;
public class TOSV2ClientBasicExample {
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");
// 上传文件之前，需要先初始化 TosClient
TOSV2 tos = new TOSV2ClientBuilder().build(region, endpoint, accessKey, secretKey);
// 上传文件需要指定存储桶名称
String bucketName = "bucket-example";
// 上传文件需要指定唯一的对象名，TOS 以对象名作为唯一标识符，
// 如果同个 objectKey 进行多次上传，则后面上传的文件会覆盖前面的文件数据。
// 因此需要确保 objectKey 的唯一性。
String objectKey = "example_dir/example_object.txt";
// TOSV2 提供的所有接口均会抛出 TosException 异常，需要使用 try-catch 进行捕获并处理。
try{
// 待上传的数据，以下代码以上传一个 ByteArrayInputStream 作为示例
String data = "1234567890abcdefghijklmnopqrstuvwxyz~!@#$%^&*()_+<>?,./ :'1234567890abcdefghijklmnopqrstuvwxyz~!@#$%^&*()_+<>?,./ :'";
ByteArrayInputStream stream = new ByteArrayInputStream(data.getBytes());
// 设置上传的桶名和对象名
PutObjectInput putObjectInput = new PutObjectInput().setBucket(bucketName).setKey(objectKey).setContent(stream);
// 上传对象
PutObjectOutput output = tos.putObject(putObjectInput);
System.out.println("putObject succeed, object's etag is " + output.getEtag());
System.out.println("putObject succeed, object's crc64 is " + output.getHashCrc64ecma());
} catch (TosClientException e) {
// 操作失败，捕获客户端异常，一般情况是请求参数错误，此时请求并未发送
System.out.println("putObject failed");
System.out.println("Message: " + e.getMessage());
if (e.getCause() != null) {
e.getCause().printStackTrace();
}
} catch (TosServerException e) {
// 操作失败，捕获服务端异常，可以获取到从服务端返回的详细错误信息
System.out.println("putObject failed");
System.out.println("StatusCode: " + e.getStatusCode());
System.out.println("Code: " + e.getCode());
System.out.println("Message: " + e.getMessage());
System.out.println("RequestID: " + e.getRequestID());
} catch (Throwable t) {
// 作为兜底捕获其他异常，一般不会执行到这里
System.out.println("putObject failed");
System.out.println("unexpected exception, message: " + t.getMessage());
}
}
}
创建桶
桶（bucket）是 TOS 的全局唯一的命名空间，相当于数据的容器，用来储存对象数据。如下代码展示如何创建一个新的桶。
import com.volcengine.tos.TOSV2;
import com.volcengine.tos.TOSV2ClientBuilder;
import com.volcengine.tos.TosClientException;
import com.volcengine.tos.TosServerException;
import com.volcengine.tos.model.bucket.CreateBucketV2Input;
import com.volcengine.tos.model.bucket.CreateBucketV2Output;
public class CreateBucketBasicExample {
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 bucketName = "your bucket name";
TOSV2 tos = new TOSV2ClientBuilder().build(region, endpoint, accessKey, secretKey);
try{
CreateBucketV2Input input = new CreateBucketV2Input().setBucket(bucketName);
CreateBucketV2Output output = tos.createBucket(input);
System.out.println("bucket created: " + output.getLocation());
} catch (TosClientException e) {
// 操作失败，捕获客户端异常，一般情况是请求参数错误，此时请求并未发送
System.out.println("createBucket failed");
System.out.println("Message: " + e.getMessage());
if (e.getCause() != null) {
e.getCause().printStackTrace();
}
} catch (TosServerException e) {
// 操作失败，捕获服务端异常，可以获取到从服务端返回的详细错误信息
System.out.println("createBucket failed");
System.out.println("StatusCode: " + e.getStatusCode());
System.out.println("Code: " + e.getCode());
System.out.println("Message: " + e.getMessage());
System.out.println("RequestID: " + e.getRequestID());
} catch (Throwable t) {
// 作为兜底捕获其他异常，一般不会执行到这里
System.out.println("createBucket failed");
System.out.println("unexpected exception, message: " + t.getMessage());
}
}
}
上传对象
桶创建成功后，可以往桶中上传对象。以下代码展示如何上传一个对象到已创建的桶中。
import com.volcengine.tos.TOSV2;
import com.volcengine.tos.TOSV2ClientBuilder;
import com.volcengine.tos.TosClientException;
import com.volcengine.tos.TosServerException;
import com.volcengine.tos.model.object.PutObjectInput;
import com.volcengine.tos.model.object.PutObjectOutput;
import java.io.ByteArrayInputStream;
public class PutObjectBasicExample {
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 bucketName = "bucket-example";
String objectKey = "example_dir/example_object.txt";
TOSV2 tos = new TOSV2ClientBuilder().build(region, endpoint, accessKey, secretKey);
try{
String data = "1234567890abcdefghijklmnopqrstuvwxyz~!@#$%^&*()_+<>?,./ :'1234567890abcdefghijklmnopqrstuvwxyz~!@#$%^&*()_+<>?,./ :'";
ByteArrayInputStream stream = new ByteArrayInputStream(data.getBytes());
PutObjectInput putObjectInput = new PutObjectInput().setBucket(bucketName).setKey(objectKey).setContent(stream);
PutObjectOutput output = tos.putObject(putObjectInput);
System.out.println("putObject succeed, object's etag is " + output.getEtag());
System.out.println("putObject succeed, object's crc64 is " + output.getHashCrc64ecma());
} catch (TosClientException e) {
// 操作失败，捕获客户端异常，一般情况是请求参数错误，此时请求并未发送
System.out.println("putObject failed");
System.out.println("Message: " + e.getMessage());
if (e.getCause() != null) {
e.getCause().printStackTrace();
}
} catch (TosServerException e) {
// 操作失败，捕获服务端异常，可以获取到从服务端返回的详细错误信息
System.out.println("putObject failed");
System.out.println("StatusCode: " + e.getStatusCode());
System.out.println("Code: " + e.getCode());
System.out.println("Message: " + e.getMessage());
System.out.println("RequestID: " + e.getRequestID());
} catch (Throwable t) {
// 作为兜底捕获其他异常，一般不会执行到这里
System.out.println("putObject failed");
System.out.println("unexpected exception, message: " + t.getMessage());
}
}
}
说明
- 如您需要上传对象到某个文件夹（对象存储的逻辑概念）下，可以为对象名添加以 / 结尾的前缀，且支持多级文件夹，例如对象名 folder1/folder2/objectName 是指将 objectName 上传到 folder1 文件夹下的 folder2 文件夹下。
- 上传对象到某个文件夹时，由于文件夹只是对象存储的逻辑概念，因此实际上不会在对象存储服务端生成真实的文件夹。
- 下载对象时，必须使用带前缀的全路径，例如下载对象时需要传入的对象名同样为 folder1/folder2/objectName。
下载对象
以下代码展示如何从桶中下载一个已经存在的对象。
import com.volcengine.tos.TOSV2;
import com.volcengine.tos.TOSV2ClientBuilder;
import com.volcengine.tos.TosClientException;
import com.volcengine.tos.TosServerException;
import com.volcengine.tos.model.object.GetObjectV2Input;
import com.volcengine.tos.model.object.GetObjectV2Output;
import java.io.FileOutputStream;
import java.io.IOException;
public class GetObjectBasicExample {
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 bucketName = "your bucket name";
// 需要确保下载的数据已存在
String objectKey = "the object key name";
String filePath = "the file path to download";
TOSV2 tos = new TOSV2ClientBuilder().build(region, endpoint, accessKey, secretKey);
try{
GetObjectV2Input input = new GetObjectV2Input().setBucket(bucketName).setKey(objectKey);
// 以下代码展示如何将数据下载到本地文件
try(FileOutputStream fileOutputStream = new FileOutputStream(filePath);
GetObjectV2Output output = tos.getObject(input)) {
byte[] buffer = new byte[1024];
int length;
while ((length = output.getContent().read(buffer)) != -1) {
fileOutputStream.write(buffer, 0, length);
}
} catch (IOException e) {
System.out.println("write data to file failed");
e.printStackTrace();
}
} catch (TosClientException e) {
// 操作失败，捕获客户端异常，一般情况是请求参数错误，此时请求并未发送
System.out.println("getObject failed");
System.out.println("Message: " + e.getMessage());
if (e.getCause() != null) {
e.getCause().printStackTrace();
}
} catch (TosServerException e) {
// 操作失败，捕获服务端异常，可以获取到从服务端返回的详细错误信息
System.out.println("getObject failed");
System.out.println("StatusCode: " + e.getStatusCode());
System.out.println("Code: " + e.getCode());
System.out.println("Message: " + e.getMessage());
System.out.println("RequestID: " + e.getRequestID());
} catch (Throwable t) {
// 作为兜底捕获其他异常，一般不会执行到这里
System.out.println("getObject failed");
System.out.println("unexpected exception, message: " + t.getMessage());
}
}
}
列举对象
以下代码展示如何从桶中列举已上传的对象。
import com.volcengine.tos.TOSV2;
import com.volcengine.tos.TOSV2ClientBuilder;
import com.volcengine.tos.TosClientException;
import com.volcengine.tos.TosServerException;
import com.volcengine.tos.model.object.*;
public class ListObjectsBasicExample {
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 bucketName = "your bucket name";
TOSV2 tos = new TOSV2ClientBuilder().build(region, endpoint, accessKey, secretKey);
try{
ListObjectsType2Input input = new ListObjectsType2Input().setBucket(bucketName);
ListObjectsType2Output output = tos.listObjectsType2(input);
System.out.printf("listObjectsType2 succeed, is truncated? %b, next continuation token is %s.\n",
output.isTruncated(), output.getNextContinuationToken());
if (output.getContents() != null) {
// 列举结果
for (int i = 0; i < output.getContents().size(); i++) {
ListedObjectV2 object = output.getContents().get(i);
System.out.printf("Listed object, key is %s, size is %d, storageClass is %s, ETag is %s, " +
"last modified is %s, crc64 value is %s.\n", object.getKey(), object.getSize(),
object.getStorageClass(), object.getEtag(), object.getLastModified().toString(), object.getHashCrc64ecma());
}
}
if (output.getCommonPrefixes() != null) {
for (int i = 0; i < output.getCommonPrefixes().size(); i++) {
ListedCommonPrefix commonPrefix = output.getCommonPrefixes().get(i);
System.out.println("Listed commonPrefix is " + commonPrefix.getPrefix());
}
}
if (output.isTruncated()) {
// 单次 listObjects 最多返回 1000 条对象数据
// 可通过返回值的 isTruncated() 判断返回结果是否被截断，
// 是则说明桶中还有未列举的数据，否则说明已经列举完所有数据。
// 以下代码展示第二次列举的用法，您可使用循环列举直至列举完成为止。
// 设置 continuationToken，表示从 continuationToken 处往后列举，取值为上一次列举返回的 nextContinuationToken
input.setContinuationToken(output.getNextContinuationToken());
output = tos.listObjectsType2(input);
System.out.printf("listObjectsType2 succeed, is truncated? %b, next continuation token is %s.\n",
output.isTruncated(), output.getNextContinuationToken());
if (output.getContents() != null) {
for (int i = 0; i < output.getContents().size(); i++) {
ListedObjectV2 object = output.getContents().get(i);
System.out.printf("Listed object, key is %s, size is %d, storageClass is %s, ETag is %s, " +
"last modified is %s, crc64 value is %s.\n", object.getKey(), object.getSize(),
object.getStorageClass(), object.getEtag(), object.getLastModified().toString(), object.getHashCrc64ecma());
}
}
if (output.getCommonPrefixes() != null) {
for (int i = 0; i < output.getCommonPrefixes().size(); i++) {
ListedCommonPrefix commonPrefix = output.getCommonPrefixes().get(i);
System.out.println("Listed commonPrefix is " + commonPrefix.getPrefix());
}
}
}
} catch (TosClientException e) {
// 操作失败，捕获客户端异常，一般情况是请求参数错误，此时请求并未发送
System.out.println("listObjectsType2 failed");
System.out.println("Message: " + e.getMessage());
if (e.getCause() != null) {
e.getCause().printStackTrace();
}
} catch (TosServerException e) {
// 操作失败，捕获服务端异常，可以获取到从服务端返回的详细错误信息
System.out.println("listObjectsType2 failed");
System.out.println("StatusCode: " + e.getStatusCode());
System.out.println("Code: " + e.getCode());
System.out.println("Message: " + e.getMessage());
System.out.println("RequestID: " + e.getRequestID());
} catch (Throwable t) {
// 作为兜底捕获其他异常，一般不会执行到这里
System.out.println("listObjectsType2 failed");
System.out.println("unexpected exception, message: " + t.getMessage());
}
}
}
删除对象
以下代码展示如何从桶中删除一个已经存在的对象。
import com.volcengine.tos.TOSV2;
import com.volcengine.tos.TOSV2ClientBuilder;
import com.volcengine.tos.TosClientException;
import com.volcengine.tos.TosServerException;
import com.volcengine.tos.model.object.DeleteObjectInput;
import com.volcengine.tos.model.object.DeleteObjectOutput;
public class DeleteObjectBasicExample {
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 bucketName = "your bucket name";
String objectKey = "the object key name";
TOSV2 tos = new TOSV2ClientBuilder().build(region, endpoint, accessKey, secretKey);
try{
DeleteObjectInput input = new DeleteObjectInput().setBucket(bucketName).setKey(objectKey);
DeleteObjectOutput output = tos.deleteObject(input);
System.out.println("deleteObject succeed, " + output);
} catch (TosClientException e) {
// 操作失败，捕获客户端异常，一般情况是请求参数错误，此时请求并未发送
System.out.println("deleteObject failed");
System.out.println("Message: " + e.getMessage());
if (e.getCause() != null) {
e.getCause().printStackTrace();
}
} catch (TosServerException e) {
// 操作失败，捕获服务端异常，可以获取到从服务端返回的详细错误信息
System.out.println("deleteObject failed");
System.out.println("StatusCode: " + e.getStatusCode());
System.out.println("Code: " + e.getCode());
System.out.println("Message: " + e.getMessage());
System.out.println("RequestID: " + e.getRequestID());
} catch (Throwable t) {
// 作为兜底捕获其他异常，一般不会执行到这里
System.out.println("deleteObject failed");
System.out.println("unexpected exception, message: " + t.getMessage());
}
}
}
相关操作
- 关于桶名称的约束限制，请参见常用概念。
- 关于创建桶的更多信息，请参见创建桶与 CreateBucket。
- 关于列举对象的更多信息，请参见列举对象与 ListObjects。
- 关于删除对象的更多信息，请参见删除对象与 DeleteBucket。
最近更新时间：2026.07.06 10:39:51
这个页面对您有帮助吗？
有用
有用
无用
无用