全部文档
当前文档
最近更新时间：2025-09-29 18:49:53
KS3支持用户对存储空间配置回收站规则，规则配置成功后，存储空间内的文件被删除时会先进入回收站。用户可设置回收站内文件保留时长，到达指定时间后，KS3会自动彻底删除回收站内的文件。
有关回收站的详细介绍请参见文档：回收站。
以下代码用于启用/禁用回收站。
public void putBucketRetention() {
// 初始化 Ks3Client，参见“初始化”文档
Ks3Client ks3Client = initKs3Client();
try {
// 初始化回收站规则
BucketRetentionConfiguration.Rule rule = new BucketRetentionConfiguration.Rule();
// 设置回收站状态，ENABLED：开启回收站，DISABLED：关闭回收站
rule.setStatus(BucketRetentionConfiguration.Status.ENABLED);
// 设置回收站内文件保留天数
rule.setDays(365);
BucketRetentionConfiguration retentionConfiguration = new BucketRetentionConfiguration(rule);
// 设置是否开启多版本保留，true：开启多版本保留，false：关闭多版本保留
retentionConfiguration.setEnableMultipleVersion(true);
PutBucketRetentionRequest request = new PutBucketRetentionRequest();
request.setBucketName("<your-bucket>");
request.setRetentionConfiguration(retentionConfiguration);
// 发送请求
ks3Client.putBucketRetention(request);
} catch (Ks3ServiceException e) {
System.out.println("Ks3ServiceException occurred, which means the request was made to KS3, but KS3 returned an error response for some reason.");
System.out.println("Error Message: " + e.getErrorMessage());
System.out.println("Error Code: " + e.getErrorCode());
System.out.println("Request ID: " + e.getRequestId());
} catch (Ks3ClientException e) {
System.out.println("Ks3ClientException occurred, which means the client encountered an internal error while trying to communicate with KS3.");
System.out.println("Error Message: " + e.getMessage());
} finally {
// 不再使用时，关闭 Ks3Client
ks3Client.shutdown();
}
}以下代码用于获取回收站规则。
public void getBucketRetention() {
// 初始化 Ks3Client，参见“初始化”文档
Ks3Client ks3Client = initKs3Client();
try {
// 获取桶回收站配置
BucketRetentionConfiguration bucketRetention = ks3Client.getBucketRetention("<your-bucket>");
System.out.println("Status: " + bucketRetention.getRule().getStatus());
System.out.println("Days: " + bucketRetention.getRule().getDays());
System.out.println("EnableMultipleVersion: " + bucketRetention.getEnableMultipleVersion());
} catch (Ks3ServiceException e) {
System.out.println("Ks3ServiceException occurred, which means the request was made to KS3, but KS3 returned an error response for some reason.");
System.out.println("Error Message: " + e.getErrorMessage());
System.out.println("Error Code: " + e.getErrorCode());
System.out.println("Request ID: " + e.getRequestId());
} catch (Ks3ClientException e) {
System.out.println("Ks3ClientException occurred, which means the client encountered an internal error while trying to communicate with KS3.");
System.out.println("Error Message: " + e.getMessage());
} finally {
// 不再使用时，关闭 Ks3Client
ks3Client.shutdown();
}
}以下代码用于列举回收站中的文件。
/**
* 列举回收站中的文件，最多返回 1000 个文件
*/
public void listRetentionObjects() {
// 初始化 Ks3Client，参见“初始化”文档
Ks3Client ks3Client = initKs3Client();
try {
// 列举回收站中的文件
RetentionObjectListing retentionObjectListing = ks3Client.listRetentionObjects("<your-bucket>");
for (RetentionObject retentionObject : retentionObjectListing.getRetentionObjects()) {
System.out.println("Key: " + retentionObject.getKey());
System.out.println("LastModified: " + retentionObject.getLastModified());
System.out.println("Size: " + retentionObject.getSize());
System.out.println("StorageClass: " + retentionObject.getStorageClass());
System.out.println("RetentionId: " + retentionObject.getRetentionId());
System.out.println("RecycleTime: " + retentionObject.getRecycleTime());
System.out.println("EstimatedClearTime: " + retentionObject.getEstimatedClearTime());
}
} catch (Ks3ServiceException e) {
System.out.println("Ks3ServiceException occurred, which means the request was made to KS3, but KS3 returned an error response for some reason.");
System.out.println("Error Message: " + e.getErrorMessage());
System.out.println("Error Code: " + e.getErrorCode());
System.out.println("Request ID: " + e.getRequestId());
} catch (Ks3ClientException e) {
System.out.println("Ks3ClientException occurred, which means the client encountered an internal error while trying to communicate with KS3.");
System.out.println("Error Message: " + e.getMessage());
} finally {
// 不再使用时，关闭 Ks3Client
ks3Client.shutdown();
}
}
/**
* 按前缀列举回收站中的文件，最多返回 1000 个文件
*/
public void listRetentionObjectsWithPrefix() {
// 初始化 Ks3Client，参见“初始化”文档
Ks3Client ks3Client = initKs3Client();
try {
// 列举回收站中的文件
RetentionObjectListing retentionObjectListing = ks3Client.listRetentionObjects("<your-bucket>", "<the-prefix>");
for (RetentionObject retentionObject : retentionObjectListing.getRetentionObjects()) {
System.out.println("Key: " + retentionObject.getKey());
System.out.println("LastModified: " + retentionObject.getLastModified());
System.out.println("Size: " + retentionObject.getSize());
System.out.println("StorageClass: " + retentionObject.getStorageClass());
System.out.println("RetentionId: " + retentionObject.getRetentionId());
System.out.println("RecycleTime: " + retentionObject.getRecycleTime());
System.out.println("EstimatedClearTime: " + retentionObject.getEstimatedClearTime());
}
} catch (Ks3ServiceException e) {
System.out.println("Ks3ServiceException occurred, which means the request was made to KS3, but KS3 returned an error response for some reason.");
System.out.println("Error Message: " + e.getErrorMessage());
System.out.println("Error Code: " + e.getErrorCode());
System.out.println("Request ID: " + e.getRequestId());
} catch (Ks3ClientException e) {
System.out.println("Ks3ClientException occurred, which means the client encountered an internal error while trying to communicate with KS3.");
System.out.println("Error Message: " + e.getMessage());
} finally {
// 不再使用时，关闭 Ks3Client
ks3Client.shutdown();
}
}
/**
* 手动调节列举回收站中的文件的参数
*/
public void listRetentionObjectsWithRequest() {
// 初始化 Ks3Client，参见“初始化”文档
Ks3Client ks3Client = initKs3Client();
try {
// 新建一个ListObjectsRequest
ListRetentionObjectsRequest request = new ListRetentionObjectsRequest("<your-bucket>");
// 指定最多返回条数
request.setMaxKeys(1000);
// 返回以指定前缀开头的 Object
request.setPrefix("<the-prefix>");
// 设置文件分隔符，系统将根据该分隔符组织文件夹结构，一般是"/"
request.setDelimiter("<delimiter>");
// 设置起始标记，从指定标记开始列举文件
request.setMarker("<marker>");
// 列举回收站中的文件
RetentionObjectListing retentionObjectListing = ks3Client.listRetentionObjects(request);
for (RetentionObject retentionObject : retentionObjectListing.getRetentionObjects()) {
System.out.println("Key: " + retentionObject.getKey());
System.out.println("LastModified: " + retentionObject.getLastModified());
System.out.println("Size: " + retentionObject.getSize());
System.out.println("StorageClass: " + retentionObject.getStorageClass());
System.out.println("RetentionId: " + retentionObject.getRetentionId());
System.out.println("RecycleTime: " + retentionObject.getRecycleTime());
System.out.println("EstimatedClearTime: " + retentionObject.getEstimatedClearTime());
}
} catch (Ks3ServiceException e) {
System.out.println("Ks3ServiceException occurred, which means the request was made to KS3, but KS3 returned an error response for some reason.");
System.out.println("Error Message: " + e.getErrorMessage());
System.out.println("Error Code: " + e.getErrorCode());
System.out.println("Request ID: " + e.getRequestId());
} catch (Ks3ClientException e) {
System.out.println("Ks3ClientException occurred, which means the client encountered an internal error while trying to communicate with KS3.");
System.out.println("Error Message: " + e.getMessage());
} finally {
// 不再使用时，关闭 Ks3Client
ks3Client.shutdown();
}
}
/**
* 使用循环列举回收站中的所有文件
*/
public void listAllRetentionObjects() {
// 初始化 Ks3Client，参见“初始化”文档
Ks3Client ks3Client = initKs3Client();
try {
// 新建一个ListObjectsRequest
ListRetentionObjectsRequest request = new ListRetentionObjectsRequest("<your-bucket>");
// 指定最多返回条数
request.setMaxKeys(1000);
// 返回以指定前缀开头的 Object
request.setPrefix("<the-prefix>");
// 设置文件分隔符，系统将根据该分隔符组织文件夹结构，一般是"/"
request.setDelimiter("<delimiter>");
boolean isTruncated = true;
String marker = null;
while (isTruncated) {
// 设置起始标记，从指定标记开始列举文件
request.setMarker(marker);
// 列举回收站中的文件
RetentionObjectListing retentionObjectListing = ks3Client.listRetentionObjects(request);
for (RetentionObject retentionObject : retentionObjectListing.getRetentionObjects()) {
System.out.println("Key: " + retentionObject.getKey());
System.out.println("LastModified: " + retentionObject.getLastModified());
System.out.println("Size: " + retentionObject.getSize());
System.out.println("StorageClass: " + retentionObject.getStorageClass());
System.out.println("RetentionId: " + retentionObject.getRetentionId());
System.out.println("RecycleTime: " + retentionObject.getRecycleTime());
System.out.println("EstimatedClearTime: " + retentionObject.getEstimatedClearTime());
}
// 判断是否还有文件未列举
isTruncated = retentionObjectListing.isTruncated();
// 获取下一批文件的起始标记
marker = retentionObjectListing.getNextMarker();
}
} catch (Ks3ServiceException e) {
System.out.println("Ks3ServiceException occurred, which means the request was made to KS3, but KS3 returned an error response for some reason.");
System.out.println("Error Message: " + e.getErrorMessage());
System.out.println("Error Code: " + e.getErrorCode());
System.out.println("Request ID: " + e.getRequestId());
} catch (Ks3ClientException e) {
System.out.println("Ks3ClientException occurred, which means the client encountered an internal error while trying to communicate with KS3.");
System.out.println("Error Message: " + e.getMessage());
} finally {
// 不再使用时，关闭 Ks3Client
ks3Client.shutdown();
}
}
/**
* 使用迭代器列举回收站中的所有文件
* @since 1.4.0
*/
public void listAllRetentionObjectsByIterator() {
// 初始化 Ks3Client，参见“初始化”文档
Ks3Client ks3Client = initKs3Client();
try {
// 新建一个ListObjectsRequest
ListRetentionObjectsRequest request = new ListRetentionObjectsRequest("<your-bucket>");
// 指定最多返回条数
request.setMaxKeys(1000);
// 返回以指定前缀开头的 Object
request.setPrefix("<the-prefix>");
// 设置文件分隔符，系统将根据该分隔符组织文件夹结构，一般是"/"
request.setDelimiter("<delimiter>");
// 新建一个迭代器
RetentionObjectListIterator iterator = ks3Client.newRetentionObjectListIterator(request);
// 设置请求间隔，用于控制请求频率，单位为毫秒，默认为 10
iterator.setRequestInterval(10);
// 使用迭代器列举回收站中的文件
while (iterator.hasNext()) {
RetentionObjectListing retentionObjectListing = iterator.next();
for (RetentionObject retentionObject : retentionObjectListing.getRetentionObjects()) {
System.out.println("Key: " + retentionObject.getKey());
System.out.println(" LastModified: " + retentionObject.getLastModified());
System.out.println(" Size: " + retentionObject.getSize());
System.out.println(" StorageClass: " + retentionObject.getStorageClass());
System.out.println(" RetentionId: " + retentionObject.getRetentionId());
System.out.println(" RecycleTime: " + retentionObject.getRecycleTime());
System.out.println(" EstimatedClearTime: " + retentionObject.getEstimatedClearTime());
}
}
} catch (Ks3ServiceException e) {
System.out.println("Ks3ServiceException occurred, which means the request was made to KS3, but KS3 returned an error response for some reason.");
System.out.println("Error Message: " + e.getErrorMessage());
System.out.println("Error Code: " + e.getErrorCode());
System.out.println("Request ID: " + e.getRequestId());
} catch (Ks3ClientException e) {
System.out.println("Ks3ClientException occurred, which means the client encountered an internal error while trying to communicate with KS3.");
System.out.println("Error Message: " + e.getMessage());
} finally {
// 不再使用时，关闭 Ks3Client
ks3Client.shutdown();
}
}以下代码用于恢复回收站中的文件。
public void recoverRetentionObject() {
// 初始化 Ks3Client，参见“初始化”文档
Ks3Client ks3Client = initKs3Client();
try {
// 恢复回收站中的文件，retentionId 为回收站文件的唯一标识，可通过列举回收站文件获取，为空时表示恢复该文件的最新版本
ks3Client.recoverObject("<your-bucket>", "<your-key>", "<your-retention-id>");
} catch (Ks3ServiceException e) {
System.out.println("Ks3ServiceException occurred, which means the request was made to KS3, but KS3 returned an error response for some reason.");
System.out.println("Error Message: " + e.getErrorMessage());
System.out.println("Error Code: " + e.getErrorCode());
System.out.println("Request ID: " + e.getRequestId());
} catch (Ks3ClientException e) {
System.out.println("Ks3ClientException occurred, which means the client encountered an internal error while trying to communicate with KS3.");
System.out.println("Error Message: " + e.getMessage());
} finally {
// 不再使用时，关闭 Ks3Client
ks3Client.shutdown();
}
}以下代码用于彻底删除回收站中的文件。
public void deleteRetentionObject() {
// 初始化 Ks3Client，参见“初始化”文档
Ks3Client ks3Client = initKs3Client();
try {
// 删除回收站中的文件，retentionId 为回收站文件的唯一标识，可通过列举回收站文件获取，不可为空
ks3Client.clearObject("<your-bucket>", "<your-key>", "<your-retention-id>");
} catch (Ks3ServiceException e) {
System.out.println("Ks3ServiceException occurred, which means the request was made to KS3, but KS3 returned an error response for some reason.");
System.out.println("Error Message: " + e.getErrorMessage());
System.out.println("Error Code: " + e.getErrorCode());
System.out.println("Request ID: " + e.getRequestId());
} catch (Ks3ClientException e) {
System.out.println("Ks3ClientException occurred, which means the client encountered an internal error while trying to communicate with KS3.");
System.out.println("Error Message: " + e.getMessage());
} finally {
// 不再使用时，关闭 Ks3Client
ks3Client.shutdown();
}
}纯净模式