全部文档
当前文档
最近更新时间：2025-09-29 15:53:20
使用downloadFile()方法从KS3下载文件，用户无需关心下载的文件大小，SDK将自动根据文件大小进行分块下载。
1. 支持断点续传，每块下载完成后SDK会记录到断点文件中，如果发生意外使下载中断，再次下载该文件时，将自动恢复上次的下载进度。
2. 支持进度回调。
3. 支持自动校验CRC64。
4. 支持按Range下载。
5. 支持下载KS3托管密钥的服务端加密文件（SSE-S3）、用户提供密钥的服务端加密文件（SSE-C）。
使用方法如下所示：
public void downloadFile() {
// 初始化 Ks3Client，参见“初始化”文档
Ks3Client ks3Client = initKs3Client();
try {
// 初始化下载文件请求，设置 bucket，objectKey
DownloadFileRequest request = new DownloadFileRequest("my-bucket", "test-key");
// 设置保存位置
request.setDownloadFile("/data/test-file");
// 设置分块大小
request.setPartSize(5 * 1024 * 1024);
// 设置并发数
request.setTaskNum(10);
// 设置断点续传开关，默认关闭
request.setEnableCheckpoint(true);
// 设置断点续传文件地址，默认为：<downloadFilePath>.dcp
request.setCheckpointFile("/data/test-file.dcp");
// KS3 托管密钥的服务端加密无需设置
// 设置客户提供密钥的服务端加密
// request.setSseCustomerKey(getCustomerKey());
// 设置进度回调
ProgressListener listener = new ProgressListener() {
@Override
public void progressChanged(ProgressEvent progressEvent) {
System.out.println("Event Type: " + progressEvent.getEventType());
System.out.println("Event Bytes: " + progressEvent.getBytes());
}
};
request.setProgressListener(listener);
// 启用 CRC64 校验
ks3Client.getKs3config().setCrcCheckEnabled(true);
// 开始下载文件
DownloadFileResult result = ks3Client.downloadFile(request);
System.out.println("ETag: " + result.getObjectMetadata().getETag());
System.out.println("Crc64Ecma: " + result.getObjectMetadata().getCrc64Ecma());
} 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());
} catch (Throwable t) {
System.out.println("Throwable occurred: " + t.getMessage());
} finally {
// 不再使用时，关闭 Ks3Client
ks3Client.shutdown();
}
}
/**
* 客户提供密钥的服务端加密
* 密钥长度要求为 16/24/32 字节
* 请妥善保存您的密钥，上传、下载文件均需要该密钥！
*/
private SSECustomerKey customerKey;
private SSECustomerKey getCustomerKey() {
if (customerKey == null) {
String sseCustomerKeyStr = "this is my sse customer key abcd";
customerKey = new SSECustomerKey(sseCustomerKeyStr.getBytes(StandardCharsets.UTF_8));
}
return customerKey;
}public void downloadDir() {
// 初始化 transferManager，自定义线程数和队列大小
TransferManager transferManager = new TransferManager(ks3Client, 5, 10 * 1024 * 1024);
try {
// 初始化下载文件请求提供器，用于设置下载文件的分块大小、线程数、进度监听器等
// 下载文件请求提供器是可选的
DownloadFileRequestProvider downloadFileRequestProvider = new DownloadFileRequestProvider() {
@Override
public void provide(DownloadFileRequest request) {
// 设置下载文件的分块大小
request.setPartSize(50 * 1024 * 1024);
// 设置下载文件的线程数
request.setTaskNum(5);
// 设置下载文件的进度监听器
request.setProgressListener(new ProgressListener() {
@Override
public void progressChanged(ProgressEvent progressEvent) {
System.out.println("ProgressEvent: " + progressEvent);
}
});
// 设置其他...
}
};
// 下载文件夹
TransferResult transferResult = transferManager.downloadDir("my-bucket", "my-files-prefix/",
new File("/data/my-files/"), downloadFileRequestProvider);
for (TaskResult successFile : transferResult.getSuccessFiles()) {
System.out.println("Download file success, key: " + successFile.getObjectKey() +
", eTag: " + successFile.getETag() + ", crc64Ecma: " + successFile.getCrc64Ecma());
}
for (ErrorFile errorFile : transferResult.getErrorFiles()) {
System.out.println("Download file failed, key: " + errorFile.getObjectKey() + ", error message: " + errorFile.getErrorMessage());
}
} 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());
} catch (Throwable t) {
System.out.println("Throwable occurred: " + t.getMessage());
} finally {
transferManager.shutdown();
}
}public void downloadFileList() {
// 初始化 transferManager，自定义线程数和队列大小
TransferManager transferManager = new TransferManager(ks3Client, 5, 10 * 1024 * 1024);
try {
// 初始化下载文件请求提供器，用于设置下载文件的分块大小、线程数、进度监听器等
// 下载文件请求提供器是可选的
DownloadFileRequestProvider downloadFileRequestProvider = new DownloadFileRequestProvider() {
@Override
public void provide(DownloadFileRequest request) {
// 设置下载文件的分块大小
request.setPartSize(50 * 1024 * 1024);
// 设置下载文件的线程数
request.setTaskNum(5);
// 设置下载文件的进度监听器
request.setProgressListener(new ProgressListener() {
@Override
public void progressChanged(ProgressEvent progressEvent) {
System.out.println("ProgressEvent: " + progressEvent);
}
});
// 设置其他...
}
};
// 要下载的 key 列表
List<String> keyList = Arrays.asList("my-files-prefix/file1.txt", "my-files-prefix/file2.txt", "my-files-prefix/file3.txt");
// 文件下载后的存储地址列表
List<File> fileList = Arrays.asList(new File("/data/my-files/file1.txt"),
new File("/data/my-files/file2.txt"),
new File("/data/my-files/file3.txt"));
// 下载文件列表
TransferResult transferResult = transferManager.downloadFileList("my-bucket", keyList, fileList, downloadFileRequestProvider);
for (TaskResult successFile : transferResult.getSuccessFiles()) {
System.out.println("Download file success, key: " + successFile.getObjectKey() +
", eTag: " + successFile.getETag() + ", crc64Ecma: " + successFile.getCrc64Ecma());
}
for (ErrorFile errorFile : transferResult.getErrorFiles()) {
System.out.println("Download file failed, key: " + errorFile.getObjectKey() + ", error message: " + errorFile.getErrorMessage());
}
} 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());
} catch (Throwable t) {
System.out.println("Throwable occurred: " + t.getMessage());
} finally {
transferManager.shutdown();
}
}纯净模式