edit-icon download-icon

Download objects

Last Updated: Nov 07, 2017

OSS Go SDK provides a variety of object downloading interfaces. You can download an object from OSS by any of the following methods:

  • Download it to the stream io.ReadCloser.
  • Download it to a local file.
  • Download it in multiple parts.

Download an object to the stream io.ReadCloser

Note: For example code of object downloading, see sample/get_object.go.

Download an object to a stream

  1. import (
  2. "fmt"
  3. "io/ioutil"
  4. "github.com/aliyun/aliyun-oss-go-sdk/oss"
  5. )
  6. client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
  7. if err != nil {
  8. // HandleError(err)
  9. }
  10. bucket, err := client.Bucket("my-bucket")
  11. if err != nil {
  12. // HandleError(err)
  13. }
  14. body, err := bucket.GetObject("my-object")
  15. if err != nil {
  16. // HandleError(err)
  17. }
  18. data, err := ioutil.ReadAll(body)
  19. if err != nil {
  20. // HandleError(err)
  21. }
  22. body.Close()
  23. fmt.Println("data:", string(data))

Note: After io.ReadCloser reads the data, you must call the Close method to disable it.

Download an object to the cache

  1. import (
  2. "bytes"
  3. "io"
  4. "github.com/aliyun/aliyun-oss-go-sdk/oss"
  5. )
  6. client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
  7. if err != nil {
  8. // HandleError(err)
  9. }
  10. bucket, err := client.Bucket("my-bucket")
  11. if err != nil {
  12. // HandleError(err)
  13. }
  14. body, err := bucket.GetObject("my-object")
  15. if err != nil {
  16. // HandleError(err)
  17. }
  18. buf := new(bytes.Buffer)
  19. io.Copy(buf, body)
  20. body.Close()

Download an object to a local file stream

  1. import (
  2. "io"
  3. "os"
  4. "github.com/aliyun/aliyun-oss-go-sdk/oss"
  5. )
  6. client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
  7. if err != nil {
  8. // HandleError(err)
  9. }
  10. bucket, err := client.Bucket("my-bucket")
  11. if err != nil {
  12. // HandleError(err)
  13. }
  14. body, err := bucket.GetObject("my-object")
  15. if err != nil {
  16. // HandleError(err)
  17. }
  18. defer body.Close()
  19. fd, err := os.OpenFile("LocalFile", os.O_WRONLY|os.O_CREATE, 0660)
  20. if err != nil {
  21. // HandleError(err)
  22. }
  23. defer fd.Close()
  24. io.Copy(fd, body)

Download an object to a local file

  1. import "github.com/aliyun/aliyun-oss-go-sdk/oss"
  2. client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
  3. if err != nil {
  4. // HandleError(err)
  5. }
  6. bucket, err := client.Bucket("my-bucket")
  7. if err != nil {
  8. // HandleError(err)
  9. }
  10. err = bucket.GetObjectToFile("my-object", "LocalFile")
  11. if err != nil {
  12. // HandleError(err)
  13. }

Multipart download

If the network jitters or the program crashes when a large object is being downloaded, the whole download operation fails. You have to re-download the objects, which results in to wastage of the resources. When the network is unstable, you may have to retry a multiple times.

You can use the Bucket.DownloadFile interface to resume the download task from the checkpoint. The interface has the following parameters:

  • objectKey: The name of the object to be downloaded.
  • filePath: The local path of the downloaded object.
  • partSize: The size of each part to be downloaded. The size ranges from 1 B to 5 GB. Its unit is byte.
  • options: Optional items, mainly include:
    • Routines: The number of concurrent downloads. The default value is 1 that means no concurrent downloads.
    • Checkpoint: Whether to enable resumable download and the path of the checkpoint object. The resumable download is disabled by default. The path of the checkpoint object can be set to null. If no specified, the checkpoint object is file.cpt, by default, under the same directory of the local file. The file is the name of the local file.
    • For restrictions for the download, see Download with Specified Conditions.

The fucntion of the multipart download is to divide the object to be downloaded into multiple parts and download them separately. When all the parts are downloaded, the download of the entire object is completed. The progress of the current download task and downloaded parts are recorded (in the checkpoint object). If the download of any part fails during the process, the next download attempt starts from the recorded position in the checkpoint object. This requires that the same checkpoint object with the previous download must be used in the next call. When the download is completed, the checkpoint object is deleted.

  1. import "github.com/aliyun/aliyun-oss-go-sdk/oss"
  2. client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
  3. if err != nil {
  4. // HandleError(err)
  5. }
  6. bucket, err := client.Bucket("my-bucket")
  7. if err != nil {
  8. // HandleError(err)
  9. }
  10. err = bucket.DownloadFile("my-object", "LocalFile", 100*1024, oss.Routines(3), oss.Checkpoint(true, ""))
  11. if err != nil {
  12. // HandleError(err)
  13. }

Note:

  • The SDK records the download intermediate states in the cp object. You must have the write permission on the cpt object.
  • The cpt object records the intermediate state information of the download and has a self-checking function. You cannot edit the object. If the cpt object is damaged, all the parts must be downloaded again.
  • If the object to be downloaded is changed during download (the ETag is changed) or a part is missing or modified, the object is downloaded again.
  • You can use oss.Checkpoint(true, "your-cp-file.cp") to specify the path of the checkpoint object for resumable download.
  • You can use bucket.DownloadFile(objectKey, localFile, 100*1024). By default, the concurrent multipart download and resumable download are disabled.

Download with specified conditions

You can specify one or more conditions for downloading an object. The object gets downloaded only when all conditions are satisfied. Otherwise, an error is reported and the object is not downloaded. Available conditions include:

Parameter Description
IfModifiedSince If the specified time is earlier than the actual modification time, the object is transmitted normally. Otherwise, an error is returned.
IfUnmodifiedSince If the specified time in the input parameter is the same as or later than the actual modification time of the object, the object is transmitted normally. Otherwise, an error is returned.
IfMatch If the expected ETag that is passed in matches the object’s ETag, the object is transmitted normally. Otherwise, an error is returned.
IfNoneMatch If the ETag that is passed in does not match the object’s ETag, the object is transmitted normally. Otherwise, an error is returned.
  1. import "time"
  2. import "github.com/aliyun/aliyun-oss-go-sdk/oss"
  3. client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
  4. if err != nil {
  5. // HandleError(err)
  6. }
  7. bucket, err := client.Bucket("my-bucket")
  8. if err != nil {
  9. // HandleError(err)
  10. }
  11. date := time.Date(2015, time.November, 10, 23, 0, 0, 0, time.UTC)
  12. // The condition is not met, and the object cannot be downloaded
  13. err = bucket.GetObjectToFile("my-object", "LocalFile", oss.IfModifiedSince(date))
  14. if err == nil {
  15. // HandleError(err)
  16. }
  17. // The conditions are met, and the object is downloaded
  18. err = bucket.GetObjectToFile("my-object", "LocalFile", oss.IfUnmodifiedSince(date))
  19. if err != nil {
  20. // HandleError(err)
  21. }

Note:

  • You can use Bucket.GetObjectDetailedMeta to get the ETag value.
  • You can specify conditions for Bucket.GetObject, Bucket.GetObjectToFile, and Bucket.DownloadFile.

Download a compressed object

Objects can be compressed for downloading. Currently, GZIP is supported for object compression. Bucket.GetObject and Bucket.GetObjectToFile support downloading compressed objects.

  1. import "github.com/aliyun/aliyun-oss-go-sdk/oss"
  2. client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
  3. if err != nil {
  4. // HandleError(err)
  5. }
  6. bucket, err := client.Bucket("my-bucket")
  7. if err != nil {
  8. // HandleError(err)
  9. }
  10. err = bucket.GetObjectToFile("my-object.txt", "LocalFile.gzip", oss.AcceptEncoding("gzip"))
  11. if err != nil {
  12. // HandleError(err)
  13. }
Thank you! We've received your feedback.