tencent cloud

masukan

Downloading Objects

Terakhir diperbarui:2022-05-23 11:50:02

    Overview

    This document provides an overview of APIs and SDK code samples for downloading an object.

    API Operation Description
    GET Object Downloading object Downloads object.

    Advanced API (Recommended)

    The advanced API allows you to pause, resume (via checkpoint restart), or cancel a download task.

    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 Operations section on this page.

    Creating TransferManager instance

    Before using the advanced API, you must create a TransferManager instance first.

    // Create a TransferManager instance, which is used to call the advanced API later.
    TransferManager createTransferManager() {
      // Create a COSClient client, which is the basic instance for accessing the COS service.
      // For the detailed code, see **Simple Operations** -> **Creating COSClient instance** on this page.
      COSClient cosClient = createCOSClient();
       // Set the thread pool size. We recommend you set the size of your thread pool to 16 or 32 to maximize network resource utilization, provided your client and COS networks are sufficient (for example, uploading a file to a COS bucket from a CVM instance in the same region).
      // We recommend you use a smaller value to avoid timeout caused by slow network speed if you are transferring data over a public network with poor bandwidth quality.
      ExecutorService threadPool = Executors.newFixedThreadPool(32);
       // Pass a `threadpool`; otherwise, a single-thread pool will be generated in `TransferManager` by default.
      TransferManager transferManager = new TransferManager(cosClient, threadPool);
       return transferManager;
    }
    

    Parameter description

    The TransferManagerConfiguration class is used to record the configuration information of the advanced API. Its main members are as described below:

    Member Name Configuration Method Description Type
    minimumUploadPartSize set method Part size of the multipart upload in bytes. Default value: 5 MB. long
    multipartUploadThreshold set method If a file is greater than or equal to this value in bytes, it will be uploaded in concurrent parts. Default value: 5 MB. long
    multipartCopyThreshold set method If a file is greater than or equal to this value in bytes, it will be replicated in concurrent parts. Default value: 5 GB. long
    multipartCopyPartSize set method Part size in bytes for multipart replication. Default value: 100 MB. long

    Shutting down TransferManager instance

    After confirming that the process no longer uses the TransferManager instance to call the advanced API, be sure to shut it down to avoid resource leakage.

    void shutdownTransferManager(TransferManager transferManager) {
      // If the parameter is set to `true`, the COSClient instance in the TransferManager instance will also be shut down at the same time.
      // If the parameter is set to `false`, the COSClient instance in the TransferManager instance will not be shut down.
      transferManager.shutdownNow(true);
    }
    

    Downloading 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

    // Before using the advanced API, you must make sure that the process contains a TransferManager instance; if not, then create one.
    // For the detailed code, see **Advanced API** -> **Creating TransferManager instance** on this page.
    TransferManager transferManager = createTransferManager();
    // Enter the bucket name in the format of `BucketName-APPID`.
    String bucketName = "examplebucket-1250000000";
    // Object key, which is the unique identifier of the object in the bucket. For more information, see [Object Overview](https://intl.cloud.tencent.com/document/product/436/13324).
    String key = "exampleobject";
    // Local file path.
    String localFilePath = "/path/to/localFile";
    File downloadFile = new File(localFilePath);
    GetObjectRequest getObjectRequest = new GetObjectRequest(bucketName, key);
    try {
      // Return an async result `Download`. You can synchronously call `waitForCompletion` to wait for the download to complete. If the download is successful, `void` will be returned; otherwise, an exception will be thrown.
      Download download = transferManager.download(getObjectRequest, downloadFile);
      download.waitForCompletion();
    } catch (CosServiceException e) {
      e.printStackTrace();
    } catch (CosClientException e) {
      e.printStackTrace();
    } catch (InterruptedException e) {
      e.printStackTrace();
    }
    // After confirming that the process no longer uses the TransferManager instance, shut it down.
    // For the detailed code, see **Advanced API** -> **Shutting down TransferManager instance** on this page.
    shutdownTransferManager(transferManager);
    

    Parameter description

    Parameter Description Type Default Value
    getObjectRequest Object download request. GetObjectRequest None
    file Destination file. File None

    The request members are as described below:

    Request Member Configuration Method Description Type
    bucketName Constructor or set method Bucket name in the format of BucketName-APPID. For more information, see Bucket Overview. String
    key Constructor or set method Unique identifier of the object in the bucket. For example, if an object's access endpoint is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg, its key is doc/picture.jpg. For more information, see Object Overview. String
    range set method Download range. Long[]
    trafficLimit set method Traffic limit on the downloaded object in bit/s. There is no limit by default. int

    Returned values

    • Success: Download is returned. You can query whether the download is complete, or wait for the download to complete.
    • Failure: If an error (such as authentication failure) occurs, the CosClientException or CosServiceException exception will be thrown. For more information, see Troubleshooting.

    Downloading object via checkpoint restart

    This API is used to download an object by range by using multiple threads at the same time and perform an integrity check after the download is complete. If an abnormal interruption occurs 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

    // Before using the advanced API, you must make sure that the process contains a TransferManager instance; if not, then create one.
    // For the detailed code, see **Advanced API** -> **Creating TransferManager instance** on this page.
    TransferManager transferManager = createTransferManager();
    // Enter the bucket name in the format of `BucketName-APPID`.
    String bucketName = "examplebucket-1250000000";
    // Object key, which is the unique identifier of the object in the bucket. For more information, see [Object Overview](https://intl.cloud.tencent.com/document/product/436/13324).
    String key = "exampleobject";
    // Local file path.
    String localFilePath = "/path/to/localFile";
    File downloadFile = new File(localFilePath);
    GetObjectRequest getObjectRequest = new GetObjectRequest(bucketName, key);
    try {
      // Return an async result `Download`. You can synchronously call `waitForCompletion` to wait for the download to complete. If the download is successful, `void` will be returned; otherwise, an exception will be thrown.
      Download download = transferManager.download(getObjectRequest, downloadFile, true);
      download.waitForCompletion();
    } catch (CosServiceException e) {
      e.printStackTrace();
    } catch (CosClientException e) {
      e.printStackTrace();
    } catch (InterruptedException e) {
      e.printStackTrace();
    }
    // After confirming that the process no longer uses the TransferManager instance, shut it down.
    // For the detailed code, see **Advanced API** -> **Shutting down TransferManager instance** on this page.
    shutdownTransferManager(transferManager);
    

    Parameter description

    Parameter Description Type Default Value
    getObjectRequest Object download request. GetObjectRequest None
    file Destination file. File None
    resumableDownload Whether to enable checkpoint restart for the download. boolean false
    resumableTaskFile Name of the file that records the checkpoint restart information. boolean file.cosresumabletask
    multiThreadThreshold Minimum file size for multi-thread download with checkpoint restart. int 20 * 1024 * 1024
    partSize Part size for downloading with checkpoint restart. int 8 * 1024 * 1024

    The request members are as described below:

    Request Member Configuration Method Description Type
    bucketName Constructor or set method Bucket name in the format of BucketName-APPID. For more information, see Bucket Overview. String
    key Constructor or set method Unique identifier of the object in the bucket. For example, if an object's access endpoint is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg, its key is doc/picture.jpg. For more information, see Object Overview. String
    range set method Download range. Long[]
    trafficLimit set method Traffic limit on the downloaded object in bit/s. There is no limit by default. int

    Returned values

    • Success: Download is returned. You can query whether the download is complete, or wait for the download to complete.
    • Failure: If an error (such as authentication failure) occurs, the CosClientException or CosServiceException exception will be thrown. For more information, see Troubleshooting.

    Displaying download progress

    This API is used to display the download progress. You need to configure a function to print the download progress and use it 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

    // You can adjust the following sample code as needed to form your own code.
    void showTransferProgress(Transfer transfer) {
      // Here, `Transfer` is the parent class of the async upload result `Upload`.
      System.out.println(transfer.getDescription());
       // Use `transfer.isDone()` to check whether the upload is complete.
      while (transfer.isDone() == false) {
          try {
              // Get the progress every two seconds.
              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);
      }
       // If the upload is complete, `Completed` will be returned; otherwise, `Failed` will be returned.
      System.out.println(transfer.getState());
    }
    

    The sample code combined with the file upload operation is as follows:

    // Before using the advanced API, you must make sure that the process contains a TransferManager instance; if not, then create one.
    // For the detailed code, see **Advanced API** -> **Creating TransferManager instance** on this page.
    TransferManager transferManager = createTransferManager();
    // Enter the bucket name in the format of `BucketName-APPID`.
    String bucketName = "examplebucket-1250000000";
    // Object key, which is the unique identifier of the object in the bucket. For more information, see [Object Overview](https://intl.cloud.tencent.com/document/product/436/13324).
    String key = "exampleobject";
    // Local file path.
    String localFilePath = "/path/to/localFile";
    File downloadFile = new File(localFilePath);
    GetObjectRequest getObjectRequest = new GetObjectRequest(bucketName, key);
    try {
      // Return an async result `Download`. You can synchronously call `waitForCompletion` to wait for the download to complete. If the download is successful, `void` will be returned; otherwise, an exception will be thrown.
      Download download = transferManager.download(getObjectRequest, downloadFile);
      // Print the upload progress until the upload is complete.
      showTransferProgress(download);
      // Capture possible exceptions.
      download.waitForCompletion();
    } catch (CosServiceException e) {
      e.printStackTrace();
    } catch (CosClientException e) {
      e.printStackTrace();
    } catch (InterruptedException e) {
      e.printStackTrace();
    }
    // After confirming that the process no longer uses the TransferManager instance, shut it down.
    // For the detailed code, see **Advanced API** -> **Shutting down TransferManager instance** on this page.
    shutdownTransferManager(transferManager);
    

    Progress acquisition description

    You can use the getProgress method of the Upload class to get the TransferProgress class, which has the following three methods to get the upload progress:

    Method Description Type
    getBytesTransferred Gets the number of uploaded bytes. long
    getTotalBytesToTransfer Gets the total number of bytes of the file. long
    getPercentTransferred Gets the percentage of the number of uploaded bytes. double

    Parameter description

    Parameter Description Type Default Value
    getObjectRequest Object download request. GetObjectRequest None
    file Destination file. File None

    The request members are as described below:

    Request Member Configuration Method Description Type
    bucketName Constructor or set method Bucket name in the format of BucketName-APPID. For more information, see Bucket Overview. String
    key Constructor or set method Unique identifier of the object in the bucket. For example, if an object's access endpoint is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg, its key is doc/picture.jpg. For more information, see Object Overview. String
    range set method Download range. Long[]
    trafficLimit set method Traffic limit on the downloaded object in bit/s. There is no limit by default. int

    Returned values

    • Success: Download is returned. You can query whether the download is complete, or wait for the download to complete.
    • Failure: If an error (such as authentication failure) occurs, the CosClientException or CosServiceException exception will be thrown. For more information, see Troubleshooting.

    Pausing, resuming, or canceling download

    This API can be used to pause, resume, or cancel a download task.

    Method prototype

    public Download download(final GetObjectRequest getObjectRequest, final File file);
    

    Sample request

    // Before using the advanced API, you must make sure that the process contains a TransferManager instance; if not, then create one.
    // For the detailed code, see **Advanced API** -> **Creating TransferManager instance** on this page.
    TransferManager transferManager = createTransferManager();
    // Enter the bucket name in the format of `BucketName-APPID`.
    String bucketName = "examplebucket-1250000000";
    // Object key, which is the unique identifier of the object in the bucket. For more information, see [Object Overview](https://intl.cloud.tencent.com/document/product/436/13324).
    String key = "exampleobject";
    // Local file path.
    String localFilePath = "/path/to/localFile";
    File downloadFile = new File(localFilePath);
    GetObjectRequest getObjectRequest = new GetObjectRequest(bucketName, key);
    try {
      // Return an async result `copy`. You can synchronously call `waitForCompletion` to wait for the download to complete. If the download is successful, `void` is returned; otherwise, an exception will be thrown.
      Download download = transferManager.download(getObjectRequest, downloadFile);
      // Wait three seconds for part of the file to be downloaded.
      Thread.sleep(3000L);
      // Pause the download and get a `PersistableUpload` instance for resuming the download later.
      PersistableDownload persistableDownload = download.pause();
      // Complex pausing and resuming:
      // `PersistableDownload` instance can be used to serialize the file content and store it and then deserialize it to resume the upload.
      // persistableDownload.serialize(out);
      // Resume download.
      download = transferManager.resumeDownload(persistableDownload);
      // Capture possible exceptions.
      download.waitForCompletion();
       // Or directly cancel the download.
      // upload.abort();
    } catch (CosServiceException e) {
      e.printStackTrace();
    } catch (CosClientException e) {
      e.printStackTrace();
    } catch (InterruptedException e) {
      e.printStackTrace();
    }
    // After confirming that the process no longer uses the TransferManager instance, shut it down.
    // For the detailed code, see **Advanced API** -> **Shutting down TransferManager instance** on this page.
    shutdownTransferManager(transferManager);
    

    Parameter description

    Parameter Description Type Default Value
    getObjectRequest Object download request. GetObjectRequest None
    file Destination file. File None

    The request members are as described below:

    Request Member Configuration Method Description Type
    bucketName Constructor or set method Bucket name in the format of BucketName-APPID. For more information, see Bucket Overview. String
    key Constructor or set method Unique identifier of the object in the bucket. For example, if an object's access endpoint is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg, its key is doc/picture.jpg. For more information, see Object Overview. String
    range set method Download range. Long[]
    trafficLimit set method Traffic limit on the downloaded object in bit/s. There is no limit by default. int

    Returned values

    • Success: Download is returned. You can query whether the download is complete, or wait for the download to complete.
    • Failure: If an error (such as authentication failure) occurs, the CosClientException or CosServiceException exception will be thrown. For more information, see Troubleshooting.

    Downloading 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 those in COS.

    Method prototype

    public MultipleFileDownload downloadDirectory(String bucketName, String keyPrefix,
          File destinationDirectory) {
    

    Sample request

    // Before using the advanced API, you must make sure that the process contains a TransferManager instance; if not, then create one.
    // For the detailed code, see **Advanced API** -> **Creating TransferManager instance** on this page.
    TransferManager transferManager = createTransferManager();
    // Enter the bucket name in the format of `BucketName-APPID`.
    String bucketName = "examplebucket-1250000000";
    // Set the prefix of objects to be downloaded (similar to downloading a directory in COS). If this parameter is set to `""`, the entire bucket will be downloaded.
    String cos_path = "/prefix";
    // Absolute path of the destination folder.
    String dir_path = "/to/mydir";
    try {
      // Return an async result "download". You can synchronously call `waitForUploadResult` to wait for the download to complete.
      MultipleFileDownload download = transferManager.downloadDirectory(bucketName, cos_path, new File(dir_path));
       // You can view the download progress.
      showTransferProgress(download);
       // You can also wait for the upload to complete.
      download.waitForCompletion();
       System.out.println("download directory done.");
    } catch (CosServiceException e) {
      e.printStackTrace();
    } catch (CosClientException e) {
      e.printStackTrace();
    } catch (InterruptedException e) {
      e.printStackTrace();
    }
    // After confirming that the process no longer uses the TransferManager instance, shut it down.
    // For the detailed code, see **Advanced API** -> **Shutting down TransferManager instance** on this page.
    shutdownTransferManager(transferManager);
    

    Parameter description

    Parameter Description Type
    bucketName Name of the bucket in COS. GetObjectRequest
    keyPrefix Prefix of the objects in COS. String
    destinationDirectory Absolute path of the destination directory. File

    Returned values

    • Success: MultipleFileUpload is returned. You can query whether the download is complete, or wait for the download to complete.
    • Failure: If an error (such as authentication failure) occurs, the CosClientException or CosServiceException exception will be thrown. For more information, 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. We recommend you create only one COSClient instance for a process and then shut it down when it is no longer used to initiate requests.

    Creating COSClient instance

    Before calling the COS API, you must create a COSClient instance first.

    // Create a COSClient instance, which is used to initiate requests later.
    COSClient createCOSClient() {
      // Set the user identity information.
      // Log in to the [CAM console](https://console.intl.cloud.tencent.com/cam/capi) to view and manage the `SECRETID` and `SECRETKEY` of your project.
      String secretId = "SECRETID";
      String secretKey = "SECRETKEY";
      COSCredentials cred = new BasicCOSCredentials(secretId, secretKey);
       // `ClientConfig` contains the COS client configuration for subsequent COS requests.
      ClientConfig clientConfig = new ClientConfig();
       // Set the bucket region.
      // For more information on COS regions, visit https://intl.cloud.tencent.com/document/product/436/6224.
      clientConfig.setRegion(new Region("COS_REGION"));
       // Set the request protocol to `http` or `https`.
      // For 5.6.53 and earlier versions, HTTPS is recommended.
      // Starting from 5.6.54, HTTPS is used by default.
      clientConfig.setHttpProtocol(HttpProtocol.https);
       // The following settings are optional:
       // Set the read timeout period, which is 30s by default.
      clientConfig.setSocketTimeout(30*1000);
      // Set the connection timeout period, which is 30s by default.
      clientConfig.setConnectionTimeout(30*1000);
       // If necessary, set the HTTP proxy, IP, and port.
      clientConfig.setHttpProxyIp("httpProxyIp");
      clientConfig.setHttpProxyPort(80);
       // Generate a COS client.
      return new COSClient(cred, clientConfig);
    }
    

    Creating COSClient instance with 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 directions on how to generate a temporary key, see Generating and Using Temporary Keys.

    // Create a COSClient instance, which is used to initiate requests later.
    COSClient createCOSClient() {
      // Here, the temporary key information is needed.
      // For directions on how to generate a temporary key, visit https://intl.cloud.tencent.com/document/product/436/14048.
      String tmpSecretId = "TMPSECRETID";
      String tmpSecretKey = "TMPSECRETKEY";
      String sessionToken = "SESSIONTOKEN";
       COSCredentials cred = new BasicSessionCredentials(tmpSecretId, tmpSecretKey, sessionToken);
       // `ClientConfig` contains the COS client configuration for subsequent COS requests.
      ClientConfig clientConfig = new ClientConfig();
       // Set the bucket region.
      // For more information on COS regions, visit https://intl.cloud.tencent.com/document/product/436/6224.
      clientConfig.setRegion(new Region("COS_REGION"));
       // Set the request protocol to `http` or `https`.
      // For 5.6.53 and earlier versions, HTTPS is recommended.
      // Starting from 5.6.54, HTTPS is used by default.
      clientConfig.setHttpProtocol(HttpProtocol.https);
       // The following settings are optional:
       // Set the read timeout period, which is 30s by default.
      clientConfig.setSocketTimeout(30*1000);
      // Set the connection timeout period, which is 30s by default.
      clientConfig.setConnectionTimeout(30*1000);
       // If necessary, set the HTTP proxy, IP, and port.
      clientConfig.setHttpProxyIp("httpProxyIp");
      clientConfig.setHttpProxyPort(80);
       // Generate a COS client.
      return new COSClient(cred, clientConfig);
    }
    

    Downloading object

    This API is used to download an object.

    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 this page.

    Method prototype

    public COSObject getObject(GetObjectRequest getObjectRequest)
              throws CosClientException, CosServiceException;
    

    Sample request

    // Before using the COS API, you must make sure that the process contains a COSClient instance; if not, then create one.
    // For the detailed code, see **Simple Operations** -> **Creating COSClient instance** on this page.
    COSClient cosClient = createCOSClient();
    // Enter the bucket name in the format of `BucketName-APPID`.
    String bucketName = "examplebucket-1250000000";
    // Object key, which is the unique identifier of the object in the bucket. For more information, see [Object Overview](https://intl.cloud.tencent.com/document/product/436/13324).
    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();
    }
    // Process the stream for the download.
    // Here, the stream is read directly. You can process it according to the actual situation.
    byte[] bytes = null;
    try {
      bytes = IOUtils.toByteArray(cosObjectInput);
    } catch (IOException e) {
      e.printStackTrace();
    } finally {
      // After using the stream, be sure to call `close()`.
      cosObjectInput.close(); 
    }
    // Do not shut down the COSClient instance before the stream processing is completed.
    // After confirming that the process no longer uses the COSClient instance, shut it down.
    cosClient.shutdown();
    

    Parameter description

    Parameter Description Type
    getObjectRequest File download request. GetObjectRequest
    destinationFile The file saved locally. File

    The request members are as described below:

    Request Member Configuration Method Description Type
    bucketName Constructor or set method Bucket name in the format of BucketName-APPID. For more information, see Bucket Overview. String
    key Constructor or set method Unique identifier of the object in the bucket. For example, if an object's access endpoint is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg, its key is doc/picture.jpg. For more information, see Object Overview. String
    range set method Download range. Long[]
    trafficLimit set method Traffic limit on the downloaded object in bit/s. There is no limit by default. Int

    Response description

    • Success: The COSObject class is returned, including the input stream and object attributes.
    • Failure: If an error (such as authentication failure) occurs, the CosClientException or CosServiceException exception will be thrown. For more information, see Troubleshooting.

    Response parameter description

    The COSObject class is used to return request results. Its main members are as described below:

    Member Name Description Type
    bucketName Bucket name in the format of BucketName-APPID. For more information, see Bucket Overview. String
    key Unique identifier of the object in the bucket. For example, if an object's access endpoint is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/do/picture.jpg, its key is doc/picture.jpg. For more information, see Object Overview. String
    metadata Object metadata. ObjectMetadata
    objectContent Data stream containing COS object content. COSObjectInputStream
    Hubungi Kami

    Hubungi tim penjualan atau penasihat bisnis kami untuk membantu bisnis Anda.

    Dukungan Teknis

    Buka tiket jika Anda mencari bantuan lebih lanjut. Tiket kami tersedia 7x24.

    Dukungan Telepon 7x24