Overview
This document provides an overview of APIs and SDK code samples for downloading an object.
|
| | Downloads an object to the local file system |
Advanced APIs (Recommended)
The advanced API allows you to suspend, resume (via checkpoint restart), or cancel download tasks.
Note:
When downloading an object, the advanced API directly writes the object into a specified local file. If you need a download stream, see the simple operation section on this page.
Creating a TransferManager instance
Before using the advanced API, first create a TransferManager instance.
TransferManager createTransferManager() {
COSClient cosClient = createCOSClient();
ExecutorService threadPool = Executors.newFixedThreadPool(32);
TransferManager transferManager = new TransferManager(cosClient, threadPool);
return transferManager;
}
Parameter description
The TransferManagerConfiguration class is used to record the configuration of the advanced API. Its main members are described as follows:
|
| | Part size of the multipart upload in bytes. Default: 5 MB | |
| | If a file is greater than or equal to this value, it will be uploaded in concurrent parts. Unit: byte; default: 5 MB | |
| | If a file is greater than or equal to this value, it will be replicated in concurrent parts. Unit: byte; default: 5 GB | |
| | Part size in bytes for multipart replication. Default: 100 MB | |
Closing a TransferManager instance
After confirming that the process does not use the TransferManager instance to call the advanced API anymore, be sure to close it to avoid leaking resources.
void shutdownTransferManager(TransferManager transferManager) {
transferManager.shutdownNow(true);
}
Downloading an object
This API is used to download a COS object to a local file.
Method prototype
public Download download(final GetObjectRequest getObjectRequest, final File file);
Sample request
TransferManager transferManager = createTransferManager();
String bucketName = "examplebucket-1250000000";
String key = "exampleobject";
String localFilePath = "/path/to/localFile";
File downloadFile = new File(localFilePath);
GetObjectRequest getObjectRequest = new GetObjectRequest(bucketName, key);
try {
Download download = transferManager.download(getObjectRequest, downloadFile);
download.waitForCompletion();
} catch (CosServiceException e) {
e.printStackTrace();
} catch (CosClientException e) {
e.printStackTrace();
} catch (InterruptedException e) {
e.printStackTrace();
}
shutdownTransferManager(transferManager);
Parameter description
Description of the Request member:
|
| Constructor or set method | Bucket name in the format of BucketName-APPID. For details, see the bucket naming conventions section in Bucket Overview. | |
| Constructor or set method | The object key is the unique identifier of the object in the bucket. For example, in the object's access domain name examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg, the object key is doc/picture.jpg, see ObjectKey | |
| | | |
| | Traffic limits (in bit/s) on the downloaded object. There is no limit by default. | |
Returned values
Success: returns Download. You can query whether the download is complete, or wait until the download is finished.
-Failure: an error (such as authentication failure) occurs, with a CosClientException or CosServiceException exception. For details, see Troubleshooting. Downloading an object (checkpoint restart)
In this API, an object is downloaded by ranges using multiple threads at the same time, and an integrity check is performed after the download is completed. If there is an exceptional interruption during the download, a range that has been downloaded will not be downloaded again (if the source file has been modified before the restart, it will be downloaded from the beginning).
This API is suitable for downloading large files.
Method prototype
public Download download(final GetObjectRequest getObjectRequest, final File file,
boolean resumableDownload);
public Download download(final GetObjectRequest getObjectRequest, final File file,
boolean resumableDownload, String resumableTaskFile,
int multiThreadThreshold, int partSize);
Sample request
TransferManager transferManager = createTransferManager();
String bucketName = "examplebucket-1250000000";
String key = "exampleobject";
String localFilePath = "/path/to/localFile";
File downloadFile = new File(localFilePath);
GetObjectRequest getObjectRequest = new GetObjectRequest(bucketName, key);
try {
Download download = transferManager.download(getObjectRequest, downloadFile, true);
download.waitForCompletion();
} catch (CosServiceException e) {
e.printStackTrace();
} catch (CosClientException e) {
e.printStackTrace();
} catch (InterruptedException e) {
e.printStackTrace();
}
shutdownTransferManager(transferManager);
Parameter description
|
| | | |
| | | |
| Whether to enable checkpoint restart for the download | | |
| Name of the file that records the checkpoint restart information | | |
| Minimum file size to use multi-thread download with checkpoint restart | | |
| Part size for downloading with checkpoint restart | | |
Description of the Request member:
|
| Constructor or set method | Bucket name in the format of BucketName-APPID. For details, see the bucket naming conventions section in Bucket Overview. | |
| Constructor or set method | The object key is the unique identifier of the object in the bucket. For example, in the object's access domain name examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg, the object key is doc/picture.jpg, see ObjectKey | |
| | | |
| | Traffic limits (in bit/s) on the downloaded object. There is no limit by default. | |
Returned values
Success: returns Download. You can query whether the download is complete, or wait until the download is finished.
-Failure: an error (such as authentication failure) occurs, with a CosClientException or CosServiceException exception. For details, see Troubleshooting. Displaying the download progress
You need to configure a function to display the download progress. The function is supposed to call the API to get the object size that has been successfully downloaded and then calculate the current download progress.
Method prototype
public Download download(final GetObjectRequest getObjectRequest, final File file);
Sample request
void showTransferProgress(Transfer transfer) {
System.out.println(transfer.getDescription());
while (transfer.isDone() == false) {
try {
Thread.sleep(2000);
} catch (InterruptedException e) {
return;
}
TransferProgress progress = transfer.getProgress();
long sofar = progress.getBytesTransferred();
long total = progress.getTotalBytesToTransfer();
double pct = progress.getPercentTransferred();
System.out.printf("upload progress: [%d / %d] = %.02f%%\n", sofar, total, pct);
}
System.out.println(transfer.getState());
}
The sample code for the file download operation is as follows:
TransferManager transferManager = createTransferManager();
String bucketName = "examplebucket-1250000000";
String key = "exampleobject";
String localFilePath = "/path/to/localFile";
File downloadFile = new File(localFilePath);
GetObjectRequest getObjectRequest = new GetObjectRequest(bucketName, key);
try {
Download download = transferManager.download(getObjectRequest, downloadFile);
showTransferProgress(download);
download.waitForCompletion();
} catch (CosServiceException e) {
e.printStackTrace();
} catch (CosClientException e) {
e.printStackTrace();
} catch (InterruptedException e) {
e.printStackTrace();
}
shutdownTransferManager(transferManager);
Description of progress obtaining
You can use the getProgress method of the download class to obtain the TransferProgress class, which has the following three methods to obtain the download progress:
|
| Obtains the number of bytes downloaded | |
| Obtains the total number of bytes of the file | |
| Obtains the percentage of the number of bytes downloaded | |
Parameter description
Description of the Request member:
|
| Constructor or set method | Bucket name in the format of BucketName-APPID. For details, see the bucket naming conventions section in Bucket Overview. | |
| Constructor or set method | The object key is the unique identifier of the object in the bucket. For example, in the object's access domain name examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg, the object key is doc/picture.jpg, see ObjectKey | |
| | | |
| | Traffic limits (in bit/s) on the downloaded object. There is no limit by default. | |
Returned values
Success: returns Download. You can query whether the download is complete, or wait until the download is finished.
-Failure: an error (such as authentication failure) occurs, with a CosClientException or CosServiceException exception. For details, see Troubleshooting. Suspending, resuming, or cancelling a download
This API can be used to suspend, resume, or cancel a download task.
Method prototype
public Download download(final GetObjectRequest getObjectRequest, final File file);
Sample request
TransferManager transferManager = createTransferManager();
String bucketName = "examplebucket-1250000000";
String key = "exampleobject";
String localFilePath = "/path/to/localFile";
File downloadFile = new File(localFilePath);
GetObjectRequest getObjectRequest = new GetObjectRequest(bucketName, key);
try {
Download download = transferManager.download(getObjectRequest, downloadFile);
Thread.sleep(3000L);
PersistableDownload persistableDownload = download.pause();
download = transferManager.resumeDownload(persistableDownload);
download.waitForCompletion();
} catch (CosServiceException e) {
e.printStackTrace();
} catch (CosClientException e) {
e.printStackTrace();
} catch (InterruptedException e) {
e.printStackTrace();
}
shutdownTransferManager(transferManager);
Parameter description
Description of the Request member:
|
| Constructor or set method | Bucket name in the format of BucketName-APPID. For details, see the bucket naming conventions section in Bucket Overview. | |
| Constructor or set method | The object key is the unique identifier of the object in the bucket. For example, in the object's access domain name examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg, the object key is doc/picture.jpg, see ObjectKey | |
| | | |
| | Traffic limits (in bit/s) on the downloaded object. There is no limit by default. | |
Returned values
Success: returns Download. You can query whether the download is complete, or wait until the download is finished.
-Failure: an error (such as authentication failure) occurs, with a CosClientException or CosServiceException exception. For details, see Troubleshooting. Downloading a directory
This API is used to download COS objects that have a specified prefix (a virtual directory) to a specified local directory. The downloaded files are in the same directory structure as in COS.
Method prototype
public MultipleFileDownload downloadDirectory(String bucketName, String keyPrefix,
File destinationDirectory) {
Sample request
TransferManager transferManager = createTransferManager();
String bucketName = "examplebucket-1250000000";
String cos_path = "/prefix";
String dir_path = "/to/mydir";
try {
MultipleFileDownload download = transferManager.downloadDirectory(bucketName, cos_path, new File(dir_path));
showTransferProgress(download);
download.waitForCompletion();
System.out.println("download directory done.");
} catch (CosServiceException e) {
e.printStackTrace();
} catch (CosClientException e) {
e.printStackTrace();
} catch (InterruptedException e) {
e.printStackTrace();
}
shutdownTransferManager(transferManager);
Parameters
|
| Name of the bucket in COS | |
| Prefix of the objects in COS | |
| Absolute path of the destination directory | |
Returned values
Success: returns MultipleFileUpload. You can query whether the download is complete, or wait until the download is finished.
-Failure: an error (such as authentication failure) occurs, with a CosClientException or CosServiceException exception. For details, see Troubleshooting. Simple Operations
Requests for simple operations need to be initiated through COSClient instances. You need to create a COSClient instance before performing simple operations.
COSClient instances are concurrency-safe. You are advised to create only one COSClient instance for a process and then close it when it is no longer used to initiate requests.
Creating a COSClient instance
Before calling the COS API, first create a COSClient instance.
COSClient createCOSClient() {
SecretID: os.Getenv("SECRETID"),
SecretKey: os.Getenv("SECRETKEY"),
COSCredentials cred = new BasicCOSCredentials(secretId, secretKey);
ClientConfig clientConfig = new ClientConfig();
clientConfig.setRegion(new Region("COS_REGION"));
clientConfig.setHttpProtocol(HttpProtocol.https);
clientConfig.setSocketTimeout(30*1000);
clientConfig.setConnectionTimeout(30*1000);
clientConfig.setHttpProxyIp("httpProxyIp");
clientConfig.setHttpProxyPort(80);
return new COSClient(cred, clientConfig);
}
Creating a COSClient instance with a temporary key
If you want to request COS with a temporary key, you need to create a COSClient instance with the temporary key.
This SDK does not generate temporary keys. For details on how to generate a temporary key, see Generating and Using Temporary Keys.
COSClient createCOSClient() {
String tmpSecretId = "TMPSECRETID";
String tmpSecretKey = "TMPSECRETKEY";
String sessionToken = "SESSIONTOKEN";
COSCredentials cred = new BasicSessionCredentials(tmpSecretId, tmpSecretKey, sessionToken);
ClientConfig clientConfig = new ClientConfig();
clientConfig.setRegion(new Region("COS_REGION"));
clientConfig.setHttpProtocol(HttpProtocol.https);
clientConfig.setSocketTimeout(30*1000);
clientConfig.setConnectionTimeout(30*1000);
clientConfig.setHttpProxyIp("httpProxyIp");
clientConfig.setHttpProxyPort(80);
return new COSClient(cred, clientConfig);
}
Downloading an object
This API (GET Object) is used to download an object to the local host.
Note:
The following sample shows how to download an object to a stream. If you want to download an object to a file, use the advanced API described on the current page.
Method prototype
public COSObject getObject(GetObjectRequest getObjectRequest)
throws CosClientException, CosServiceException;
Sample request
COSClient cosClient = createCOSClient();
String bucketName = "examplebucket-1250000000";
String key = "exampleobject";
GetObjectRequest getObjectRequest = new GetObjectRequest(bucketName, key);
COSObjectInputStream cosObjectInput = null;
try {
COSObject cosObject = cosClient.getObject(getObjectRequest);
cosObjectInput = cosObject.getObjectContent();
} catch (CosServiceException e) {
e.printStackTrace();
} catch (CosClientException e) {
e.printStackTrace();
} catch (InterruptedException e) {
e.printStackTrace();
}
byte[] bytes = null;
try {
bytes = IOUtils.toByteArray(cosObjectInput);
} catch (IOException e) {
e.printStackTrace();
} finally {
cosObjectInput.close();
}
cosClient.shutdown();
Parameters
Description of the Request member:
|
| Constructor or set method | | |
| Constructor or set method | Object key, the unique identifier of the object in the bucket. For example, in the object's access domain name examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg, the object key is doc/picture.jpg. For more information, see ObjectKey | |
| | | |
| | Traffic limits (in bit/s) on the downloaded object. The default setting is no limit. | |
Response description
Success: returns the COSObject class, including the input stream and object attributes.
Failure: If an error (such as authentication failure) occurs, the CosClientException or CosServiceException exception will be reported. For more information, see Troubleshooting. Response parameters
The COSObject class is used to return request results. Its main members are described as follows:
|
| | |
| The object key is the unique identifier of the object in the bucket. For example, in the object's access domain name examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/do/picture.jpg, the object key is doc/picture.jpg. For details, see ObjectKey | |
| | |
| Data stream containing COS object content | |
