This topic describes the methods provided by OSS SDK for Ruby to download objects.

Download an object to your computer

You can call the Bucket#get_object operation and specify the :file parameter to download the specified OSS object to your computer.

require 'aliyun/oss'

client = Aliyun::OSS::Client.new(
  endpoint: 'endpoint',
  access_key_id: 'AccessKeyId', access_key_secret: 'AccessKeySecret')

bucket = client.get_bucket('my-bucket')
bucket.get_object('my-object', :file => 'local-file')
            

Streaming download

If a long period of time is required to download an object, you can use streaming download to download the object in increments until the entire object is downloaded.

You can call the Bucket#get_object operation and specify the block parameter to stream the content to download.

require 'aliyun/oss'

client = Aliyun::OSS::Client.new(
  endpoint: 'endpoint',
  access_key_id: 'AccessKeyId', access_key_secret: 'AccessKeySecret')

bucket = client.get_bucket('my-bucket')
bucket.get_object('my-object') do |chunk|
  # handle_data(chunk)
  puts "Got a chunk, size: #{chunk.size}."
end
            

Resumable download

You may fail to download a large object if the network is unstable or other exceptions occur. In some cases, you may still fail to download the object even after multiple attempts. To resolve this issue, OSS SDK for Ruby provides the resumable download feature.

In resumable download, the object that you want to download is split into multiple parts and each part is separately downloaded. After all parts are downloaded, these parts are combined into a complete object.

You can call the Bucket#resumable_download operation to implement resumable download. You can configure the following parameters in the operation:

  • key: the name of the object you want to download.
  • file: the local path to which you want to download the object.
  • opts: contains the following options:
    • :cpt_file: the path of the checkpoint file. If you do not specify this option, file.cpt in the local path to which the object is downloaded is used by default. file specifies the name of the local file.
    • :disable_cpt: If you set this option to true, the download progress is not recorded during the object download. If the object fails to download, the download cannot be resumed.
    • :part_size: the size of each part. By default, the size of each part is 10 MB.
    • &block: If you pass in block when you call the Bucket#resumable_download operation, the download progress is processed by block.

For more information about parameters, see Download objects.

The current download progress information is recorded in the checkpoint file during the object download. A downloaded part is stored as file.part.N. file indicates the name of the local file after the part is downloaded. If a part fails to download in the download process, the part continues to download based on the record in the checkpoint file next time the download is resumed. Next time you call Bucket#resumable_download, you must specify the same checkpoint file as last time. After the object is downloaded, the part and checkpoint file are deleted.

require 'aliyun/oss'

client = Aliyun::OSS::Client.new(
  endpoint: 'endpoint',
  access_key_id: 'AccessKeyId', access_key_secret: 'AccessKeySecret')

bucket = client.get_bucket('my-bucket')
bucket.resumable_download('my-object', 'local-file') do |p|
  puts "Progress: #{p}"
end

bucket.resumable_download(
  'my-object', 'local-file',
  :part_size => 100 * 1024, :cpt_file => '/tmp/x.cpt') { |p|
  puts "Progress: #{p}"
}
            
Note
  • OSS SDK for Ruby records the download progress in the cpt file. Make sure that you have write permissions on the cpt file.
  • OSS SDK for Ruby stores the downloaded parts in the part local file. You must make sure that you have permissions to create files in the local directory that contains file.
  • The cpt file records the intermediate status information of downloads, and downloaded data can be verified. You cannot edit the cpt file. If the cpt file is damaged, the file cannot be downloaded. After the entire object is downloaded, the cpt file is deleted.
  • If the object to download is modified, the ETag value is changed, or the part file is missing or modified, the object fails to download.

HTTP-based download

You can download objects stored in OSS by using OSS SDK for Ruby. You can also directly download the objects over HTTP. To download an object over HTTP, you can use a browser or a command-line tool such as wget or curl. In this case, you must use OSS SDK for Ruby to generate the URL of the object.

If you use the Bucket#object_url method to generate an HTTP address used to download the object, you must configure the following parameters:

  • key: the name of the object that you want to download.
  • sign: specifies whether to generate a signed URL.
    Note
    • If the ACL of the object is public read or public read/write, you can access the object by using a URL that does not contain a signature.
    • If the ACL of the object is private, you must use a signed URL to access the object.
  • expires: the validity period of the URL. Default value: 60. Unit: seconds.
require 'aliyun/oss'

client = Aliyun::OSS::Client.new(
  endpoint: 'endpoint',
  access_key_id: 'AccessKeyId', access_key_secret: 'AccessKeySecret')

bucket = client.get_bucket('my-bucket')
# Generate a URL. By default, the URL includes a signature. The validity period is 60 seconds. 
puts bucket.object_url('my-object')
# http://my-bucket.oss-cn-hangzhou.aliyuncs.com/my-object?Expires=1448349966&OSSAccessKeyId=5vxxxx&Signature=aM2HpBLeMq1aec6JCd7BBAKYiwI%3D

# Generate a URL that does not contain a signature. 
puts bucket.object_url('my-object', false)
# http://my-bucket.oss-cn-hangzhou.aliyuncs.com/my-object

# Set the validity period of the specified URL to 3600 seconds. 
puts bucket.object_url('my-object', true, 3600)