全部文档
当前文档
最近更新时间：2026-06-03 21:32:13
当下载的文件太大或者一次性下载耗时太长时，您可以通过流式下载，一次处理部分内容，直到完成文件的下载。
Ks3Object 对象使用完毕后必须关闭，否则会造成连接泄漏，导致请求无连接可用，程序无法正常工作。
关闭方法如下：
GetObjectResult getObjectResult = ks3Client.getObject(bucketName, objectName);
getObjectResult.getObject().close();
// 或者
getObjectResult.getObject().getObjectContent().close();
流式下载文件的示例代码如下：
/**
* 流式下载
* 用户可以使用这种方式获取对象的数据流，并将其写入到文件或其他输出流中。
* 如需下载对象到本地文件，建议使用下载到本地文件、高级下载等方法。
*/
public void getObject() {
// 初始化 Ks3Client，参见“初始化”文档
Ks3Client ks3Client = initKs3Client();
// 定义一个输入流来接收对象内容，必须在 finally 块中关闭该流，否则会导致连接泄漏。
InputStream inputStream = null;
// 定义一个输出流，可以替换为其他输出流，例如文件输出流
OutputStream outputStream = System.out;
try {
// 创建获取对象请求
GetObjectRequest request = new GetObjectRequest("bucketName", "objectKey");
// 只接受数据的0-10字节。通过控制该项可以实现分块下载
// request.setRange(0,10);
// 可以重写返回的header
// ResponseHeaderOverrides overrides = new ResponseHeaderOverrides();
// overrides.setContentType("text/html");
// .......
// request.setOverrides(overrides);
// 如果文件是用户提供key的方式进行服务端加密的
// SecretKey sourceKey= ??//当初加密时用的密钥
// request.setSseCustomerKey(new SSECustomerKey(sourceKey));
// 获取对象
GetObjectResult result = ks3Client.getObject(request);
// 获取对象内容
inputStream = result.getObject().getObjectContent();
// 读取对象内容，用户可以将其写入到文件或其他输出流中
byte[] buffer = new byte[1024 * 1024];
int bytesRead;
// 循环获取数据，并写入到输出流中
while ((bytesRead = inputStream.read(buffer)) != -1) {
outputStream.write(buffer, 0, bytesRead);
}
} 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 (IOException e) {
System.out.println("IOException occurred, which means an I/O error occurred while reading the object content.");
System.out.println("Error Message: " + e.getMessage());
} finally {
// 确保输入流被关闭，避免资源泄漏，否则会导致请求无连接可用，程序无法正常工作。
CommonUtils.closeQuietly(inputStream);
CommonUtils.closeQuietly(outputStream);
// 不再使用时，关闭 Ks3Client
ks3Client.shutdown();
}
}本文介绍如何将存储空间（Bucket）中的文件（Object）下载到本地文件。
示例代码如下：
/**
* 下载到本地文件
* @since 1.6.0
* 注意：
* 此方法适用于下载小文件，对于大文件更推荐使用高级下载。
*/
public void getObjectToFile() {
// 初始化 Ks3Client，参见“初始化”文档
Ks3Client ks3Client = initKs3Client();
String fileName = "/path/to/file";
try {
// 创建获取对象请求
GetObjectRequest request = new GetObjectRequest("bucketName", "objectKey");
// 只接受数据的0-10字节。通过控制该项可以实现分块下载
// request.setRange(0,10);
// 可以重写返回的header
// ResponseHeaderOverrides overrides = new ResponseHeaderOverrides();
// overrides.setContentType("text/html");
// .......
// request.setOverrides(overrides);
// 如果文件是用户提供key的方式进行服务端加密的
// SecretKey sourceKey= ??//当初加密时用的key
// request.setSseCustomerKey(new SSECustomerKey(sourceKey));
// 获取对象并下载到本地文件，这种方法 SDK 会自动处理对象内容的流式读取和文件写入，关闭流等操作。
ObjectMetadata objectMetadata = ks3Client.getObjectToFile(request, new File(fileName));
System.out.println("Object downloaded successfully to: " + fileName);
System.out.println("Object size: " + objectMetadata.getContentLength() + " bytes");
System.out.println("Content Type: " + objectMetadata.getContentType());
System.out.println("Last Modified: " + objectMetadata.getLastModified());
System.out.println("Crc64: " + objectMetadata.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 (IOException e) {
System.out.println("IOException occurred, which means an I/O error occurred while reading the object content.");
System.out.println("Error Message: " + e.getMessage());
} finally {
// 不再使用时，关闭 Ks3Client
ks3Client.shutdown();
}
}
以下示例代码用于获取 ks3 对象的字符串形式内容，适用于文本类型的小文件。
/**
* 获取对象内容的字符串表示
* @since 1.6.0
* 注意：
* 此方法适用于获取文本内容，对于二进制文件不建议使用，因为可能会导致编码问题。
* 此方法适用于获取小文件的文本内容，对于大文件不建议使用，因为会将整个对象内容加载到内存中。
* 如果对象内容较大，建议使用流式下载、下载到文件、高级下载的方式。
*/
public void getObjectAsString() {
// 初始化 Ks3Client，参见“初始化”文档
Ks3Client ks3Client = initKs3Client();
String bucketName = "bucketName";
String objectKey = "objectKey";
try {
// 创建获取对象请求
GetObjectRequest request = new GetObjectRequest(bucketName, objectKey);
// 获取对象内容的字符串表示
String objectContent = ks3Client.getObjectAsString(request);
System.out.println("Object content as string: " + objectContent);
} 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 (IOException e) {
System.out.println("IOException occurred, which means an I/O error occurred while reading the object content.");
System.out.println("Error Message: " + e.getMessage());
} finally {
// 不再使用时，关闭 Ks3Client
ks3Client.shutdown();
}
}
以下示例代码用于获取 ks3 对象的二进制形式的内容，适用于小文件。
/**
* 获取对象内容的字节数组表示
* @since 1.6.0
* 注意：
* 此方法适用于小文件的获取，对于大文件不建议使用，因为会将整个对象内容加载到内存中。
* 如果对象内容较大，建议使用流式下载、下载到文件、高级下载的方式。
*/
public void getObjectAsBytes() {
// 初始化 Ks3Client，参见“初始化”文档
Ks3Client ks3Client = initKs3Client();
String bucketName = "bucketName";
String objectKey = "objectKey";
try {
// 创建获取对象请求
GetObjectRequest request = new GetObjectRequest(bucketName, objectKey);
// 获取对象内容的字节数组表示
byte[] objectContent = ks3Client.getObjectAsBytes(request);
System.out.println("Object content as bytes: " + new String(objectContent));
} 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 (IOException e) {
System.out.println("IOException occurred, which means an I/O error occurred while reading the object content.");
System.out.println("Error Message: " + e.getMessage());
} finally {
// 不再使用时，关闭 Ks3Client
ks3Client.shutdown();
}
}
纯净模式