Resumable download - Object Storage Service - Alibaba Cloud Documentation Center

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 the object that you want to download 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 call the Bucket#resumable_download method to implement resumable download. The method contains the following parameters.

Parameter	Description	Required	Default value
key	The full path of the OSS object to download. Note If the ETag value of the object to download changes, the download fails.	Yes	None
file	The full path of the local file to which you want the object to be downloaded.	Yes	None
:cpt_file	The path of the checkpoint file. You must have the write permissions on the file. Note Information about the download progress is recorded in the .cpt file. The downloaded parts are saved as `file.part.N`. If a part fails to be downloaded, the download is resumed from the position recorded in the .cpt file. You must specify the same .cpt file as the last time when you call Bucket#resumable_download again. After the object is downloaded, both the parts and the .cpt file are deleted. The .cpt file records the intermediate status information of downloads, and can be used to verify downloaded data. You cannot edit the .cpt file. If the .cpt file is damaged, the download cannot continue.	No	`file.cpt` in the directory of the local file, where `file` indicates the name of the local file
:disable_cpt	Specifies whether to record the download progress. Valid values: true: does not record the download progress. If the download fails, the download cannot be resumed. false: records the download progress. If the download fails, the download is resumed from the position recorded in the checkpoint file.	No	false
:part_size	The size of each part.	No	10 MB
&block	Specifies whether the download progress is handled by block. If you pass in block when you call Bucket#resumable_download, the download progress is handled by block.	No	None

For more information, see Alibaba Cloud OSS SDK for Ruby.

Sample code

The following code provides an example on how to perform resumable download:

require 'aliyun/oss'

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

# Specify the name of the bucket. Example: examplebucket. 
bucket = client.get_bucket('examplebucket')
# Set key to the full path of the object. Do not include the bucket name in the full path. Example: exampledir/example.zip. 
# Set file to the full path of the local file. 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 checkpoint file. 
  :part_size => 100 * 1024, :cpt_file => '/tmp/example.zip.cpt') { |p|
  puts "Progress: #{p}"
}

References

For more information about the API operation that you can call to perform resumable download, see GetObject.