How to perform a resumable download of a file using Ruby SDK - Object Storage Service

You may fail to download a large object if the network is unstable or other exceptions occur. In some cases, you may fail to download the object even after multiple attempts. To resolve this issue, Object Storage Service (OSS) provides the resumable download feature. In resumable download, OSS splits an object into multiple parts and downloads each part separately. After all parts are downloaded, OSS combines the parts into a complete object.

Implementation method

You can use the Bucket#resumable_download method to perform a resumable download. This method uses the following parameters:

Parameter	Description	Required	Default value
key	The full path of the OSS file. Note If the ETag value of the file to be downloaded changes, the download fails.	Yes	None
file	The full path of the local file where the download is saved.	Yes	None
:cpt_file	The file that records breakpoint information. You must have write permissions for this file. Note Download progress is recorded in the .cpt file. Downloaded shards are saved as `file.part.N`. If a shard fails to download, the next download attempt resumes from the breakpoint recorded in the .cpt file. When you call Bucket#resumable_download again, specify the same .cpt file as the previous attempt. After the file is downloaded, the part file and the .cpt file are deleted. The .cpt file records the intermediate state of the download and includes a verification feature. Do not edit the .cpt file. If the .cpt file is corrupted, the download cannot be resumed.	No	`file.cpt` in the same folder as the local file, where `file` is the name of the local file.
:disable_cpt	Specifies whether to record download progress. Valid values: true: Download progress is not recorded. The download cannot be resumed if it fails. false: Download progress is recorded. The download can be resumed from the breakpoint if it fails.	No	false
:part_size	The size of each shard.	No	10 MB
&block	If a block is passed during the call, the download progress is handled by the block.	No	None

For more information, see the API document.

Sample code

The following code provides an example of how to perform a resumable download.

require 'aliyun/oss'

client = Aliyun::OSS::Client.new(
  # The endpoint of China (Hangzhou) is used as an example. Specify the actual endpoint.
  endpoint: 'https://oss-cn-hangzhou.aliyuncs.com',
  # Obtain access credentials from environment variables. Before running this sample code, make sure the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  access_key_id: ENV['OSS_ACCESS_KEY_ID'],
  access_key_secret: ENV['OSS_ACCESS_KEY_SECRET']
)

# Specify the bucket name, for example, examplebucket.
bucket = client.get_bucket('examplebucket')
# Set key to the full path of the object. The full path cannot contain the bucket name. For example, exampledir/example.zip.
# Set file to the full path of the local file. For example, /tmp/example.zip.
bucket.resumable_download('exampledir/example.zip', '/tmp/example.zip') do |p|
  puts "Progress: #{p}"
end

bucket.resumable_download(
  'exampledir/example.zip', '/tmp/example.zip',
  # Set cpt_file to the path of the file that records breakpoint information.
  :part_size => 100 * 1024, :cpt_file => '/tmp/example.zip.cpt') { |p|
  puts "Progress: #{p}"
}

References

For more information about the API operation used for resumable downloads, see GetObject.