全部文档
当前文档
最近更新时间：2025-09-29 18:57:51
使用 uploadFile() 方法上传本地文件到KS3，用户无需关心上传的文件大小，SDK将自动根据文件大小进行分块上传。
1. 支持断点续传，每块上传完成后SDK会记录到断点文件中，如果发生意外使上传中断，再次上传该文件时，会自动恢复上次的上传进度。
2. 支持设置文件的元数据、ACL、存储类型、标签等。
3. 支持进度回调。
4. 支持自动校验CRC64。
5. 支持KS3托管密钥的服务端加密、用户提供密钥的服务端加密。
public void uploadFile() {
// 初始化 Ks3Client，参见“初始化”文档
Ks3Client ks3Client = initKs3Client();
try {
// 初始化上传文件请求，设置 bucket，objectKey
UploadFileRequest request = new UploadFileRequest("my-bucket", "test-key");
// 设置要上传的文件
request.setUploadFile("/data/test-file");
// 设置分块大小
request.setPartSize(5 * 1024 * 1024);
// 设置并发数
request.setTaskNum(10);
// 设置 metadata
ObjectMetadata metadata = new ObjectMetadata();
metadata.setContentType("text/plain");
metadata.setUserMeta("key1", "value1");
request.setObjectMetadata(metadata);
// 设置访问权限
request.setCannedAcl(CannedAccessControlList.Private);
// 或者设置自定义权限
AccessControlList accessControlList = new AccessControlList();
accessControlList.addGrant(new GranteeId("id1"), Permission.Read);
accessControlList.addGrant(new GranteeId("id2"), Permission.Write);
request.setAcl(accessControlList);
// 设置存储类型
request.setStorageClass(StorageClass.Standard);
// 设置标签
ObjectTagging objectTagging = new ObjectTagging();
objectTagging.addObjectTag("key1", "value1");
objectTagging.addObjectTag("key2", "value2");
request.setObjectTagging(objectTagging);
// 设置断点续传开关，默认关闭
request.setEnableCheckpoint(true);
// 设置断点续传文件地址，默认为：<uploadFilePath>.ucp
request.setCheckpointFile("/data/test-file.ucp");
// 设置 KS3 托管密钥的服务端加密
// request.getObjectMetadata().setSseAlgorithm("AES256");
// 设置客户提供密钥的服务端加密
// 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);
// 开始上传文件
UploadFileResult result = ks3Client.uploadFile(request);
System.out.println("ETag: " + result.getETag());
System.out.println("Crc64Ecma: " + result.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();
}
}public void uploadFileFromInputStream() {
// 初始化 Ks3Client，参见“初始化”文档
Ks3Client ks3Client = initKs3Client();
try (final CloseableHttpClient httpClient = HttpClients.createDefault()) {
// 初始化上传文件请求，设置 bucket，objectKey
UploadFileRequest request = new UploadFileRequest("my-bucket", "test-key");
// 设置 fetcher，用于获取要上传的文件块的输入流
FilePartFetcher fetcher = new FilePartFetcher() {
@Override
public InputStream fetch(int partNum, long[] range) throws IOException {
// 例如从网络上获取文件块的输入流
HttpGet httpGet = new HttpGet("http://example.com/file");
httpGet.setHeader("Range", "bytes=" + range[0] + "-" + range[1]);
CloseableHttpResponse response = httpClient.execute(httpGet);
if (response.getStatusLine().getStatusCode() != 206) {
throw new IOException("Failed to fetch file part");
}
return response.getEntity().getContent();
}
};
request.setFilePartFetcher(fetcher);
// 设置要上传的文件大小，单位：字节，使用 fetcher 时必须设置，必须为要上传的文件的真实大小
request.setFileSize(2L * 1024 * 1024 * 1024);
// 设置分块大小
request.setPartSize(5 * 1024 * 1024);
// 设置并发数
request.setTaskNum(10);
// 设置 metadata
ObjectMetadata metadata = new ObjectMetadata();
metadata.setContentType("text/plain");
metadata.setUserMeta("key1", "value1");
request.setObjectMetadata(metadata);
// 设置访问权限
request.setCannedAcl(CannedAccessControlList.Private);
// 或者设置自定义权限
AccessControlList accessControlList = new AccessControlList();
accessControlList.addGrant(new GranteeId("id"), Permission.Write);
accessControlList.addGrant(GranteeUri.AllUsers, Permission.Read);
request.setAcl(accessControlList);
// 设置存储类型
request.setStorageClass(StorageClass.Standard);
// 设置标签
ObjectTagging objectTagging = new ObjectTagging();
objectTagging.addObjectTag("key1", "value1");
objectTagging.addObjectTag("key2", "value2");
request.setObjectTagging(objectTagging);
// 设置断点续传开关，默认关闭
request.setEnableCheckpoint(true);
// 设置断点续传文件地址，默认为：<uploadFilePath>.ucp
request.setCheckpointFile("/data/test-file.ucp");
// 设置 KS3 托管密钥的服务端加密
// request.getObjectMetadata().setSseAlgorithm("AES256");
// 设置客户提供密钥的服务端加密
// 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);
// 开始上传文件
UploadFileResult result = ks3Client.uploadFile(request);
System.out.println("ETag: " + result.getETag());
System.out.println("Crc64Ecma: " + result.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 uploadDir() {
// 初始化 transferManager，自定义线程数和队列大小
TransferManager transferManager = new TransferManager(ks3Client, 5, 10 * 1024 * 1024);
try {
// 初始化上传文件请求提供器，用于设置上传文件的元数据、存储类型、ACL、标签等
// 上传文件请求提供器是可选的，如果不需要设置上传文件的元数据、存储类型、ACL、标签等，可以不设置
UploadFileRequestProvider uploadFileRequestProvider = new UploadFileRequestProvider() {
@Override
public void provide(UploadFileRequest request) {
// 设置上传文件的分块大小
request.setPartSize(50 * 1024 * 1024);
// 设置上传文件的线程数
request.setTaskNum(5);
// 设置上传文件的元数据
ObjectMetadata objectMetadata = new ObjectMetadata();
objectMetadata.setContentType("text/plain");
objectMetadata.setUserMeta("my-meta-key", "my-meta-value");
request.setObjectMetadata(objectMetadata);
// 设置上传文件的存储类型
request.setStorageClass(StorageClass.Standard);
// 设置上传文件的ACL
request.setCannedAcl(CannedAccessControlList.Private);
// 设置上传文件的自定义ACL
// AccessControlList accessControlList = new AccessControlList();
// accessControlList.addGrant(new GranteeId("my-grantee-id"), Permission.Read);
// request.setAcl(accessControlList);
// 设置上传文件的标签
ObjectTagging objectTagging = new ObjectTagging();
objectTagging.addObjectTag("my-tag-key", "my-tag-value");
request.setObjectTagging(objectTagging);
// 设置进度监听器
request.setProgressListener(new ProgressListener() {
@Override
public void progressChanged(ProgressEvent progressEvent) {
System.out.println("ProgressEvent: " + progressEvent);
}
});
// 设置其他...
}
};
// 上传文件夹
TransferResult transferResult = transferManager.uploadDir("my-bucket",
"my-files-prefix/", new File("/data/my-files/"), uploadFileRequestProvider);
for (TaskResult successFile : transferResult.getSuccessFiles()) {
System.out.println("Upload file success, key: " + successFile.getObjectKey() +
", eTag: " + successFile.getETag() + ", crc64Ecma: " + successFile.getCrc64Ecma());
}
for (ErrorFile errorFile : transferResult.getErrorFiles()) {
System.out.println("Upload 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 uploadFileList() {
// 初始化 transferManager，自定义线程数和队列大小
TransferManager transferManager = new TransferManager(ks3Client, 5, 10 * 1024 * 1024);
try {
// 初始化上传文件请求提供器，用于设置上传文件的元数据、存储类型、ACL、标签等
// 上传文件请求提供器是可选的，如果不需要设置上传文件的元数据、存储类型、ACL、标签等，可以不设置
UploadFileRequestProvider uploadFileRequestProvider = new UploadFileRequestProvider() {
@Override
public void provide(UploadFileRequest request) {
// 设置上传文件的分块大小
request.setPartSize(50 * 1024 * 1024);
// 设置上传文件的线程数
request.setTaskNum(5);
// 设置上传文件的元数据
ObjectMetadata objectMetadata = new ObjectMetadata();
objectMetadata.setContentType("text/plain");
objectMetadata.setUserMeta("my-meta-key", "my-meta-value");
request.setObjectMetadata(objectMetadata);
// 设置上传文件的存储类型
request.setStorageClass(StorageClass.Standard);
// 设置上传文件的ACL
request.setCannedAcl(CannedAccessControlList.Private);
// 设置上传文件的自定义ACL
// AccessControlList accessControlList = new AccessControlList();
// accessControlList.addGrant(new GranteeId("my-grantee-id"), Permission.Read);
// request.setAcl(accessControlList);
// 设置上传文件的标签
ObjectTagging objectTagging = new ObjectTagging();
objectTagging.addObjectTag("my-tag-key", "my-tag-value");
request.setObjectTagging(objectTagging);
// 设置进度监听器
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.uploadFileList("my-bucket", keyList, fileList, uploadFileRequestProvider);
for (TaskResult successFile : transferResult.getSuccessFiles()) {
System.out.println("Upload file success, key: " + successFile.getObjectKey() +
", eTag: " + successFile.getETag() + ", crc64Ecma: " + successFile.getCrc64Ecma());
}
for (ErrorFile errorFile : transferResult.getErrorFiles()) {
System.out.println("Upload 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();
}
}纯净模式