淘宝开放平台

本文档介绍OSS Ruby SDK提供的多种文件下载方式。

下载到本地文件

通过Bucket#get_object接口，并指定:file参数将指定的OSS文件下载到本地文件。

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')

流式下载

如果要下载的文件太大，或者一次性下载耗时太长，您可以通过流式下载的方式一次处理部分内容，直到完成整个文件的下载。

通过Bucket#get_object接口，并指定block参数来流式处理下载的内容。

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

断点续传下载

当下载大文件时，如果网络不稳定或者程序异常退出，会导致下载失败，甚至重试多次仍无法完成下载。为此OSS提供了断点续传下载功能。

断点续传下载将需要下载的文件分成若干个分片分别下载，所有分片都下载完成后，将所有分片合并成完整的文件。

通过Bucket#resumable_download接口来实现断点续传下载，包含以下参数：

key：要下载的文件名称。
file：下载到本地文件的路径。
opts：可选项，主要包括：
- :cpt_file：指定checkpoint文件的路径，如果不指定，则默认是本地文件同目录下的file.cpt，其中file是本地文件的名称。
- :disable_cpt：如果指定为true，则下载过程中不会记录下载进度，失败后也无法进行续传。
- :part_size：指定每个分片的大小，默认为10 MB。
- &block：如果调用时候传递了block，则下载进度会交由block处理。

关于参数的更多说明，请参见API文档。

在下载文件的过程中会记录当前下载的进度信息，并记录在checkpoint文件中。已下载的分片将保存为file.part.N，其中 file表示下载的本地文件的名称。如果下载过程中某一分片下载失败，再次下载时会从checkpoint文件中记录的点继续下载。再次调用Bucket#resumable_download时要指定与上次相同的checkpoint文件。下载完成后，part文件和checkpoint文件都会被删除。

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}"
}

说明

SDK会将下载的中间状态信息记录在cpt文件中，您需确保对cpt文件有写权限。
SDK会将已下载的分片保存在part文件中，您需确保对file所在的目录有创建文件的权限。
cpt文件不仅记录了下载的中间状态信息，还附带校验功能。cpt文件不允许编辑。如果cpt文件损坏则无法继续下载，整个文件下载完成后cpt文件会被删除。
下载过程中待下载的文件、ETag值发生改变，part文件丢失或被修改均会导致下载失败。

HTTP下载

在不用SDK的情况下，您也可以直接使用HTTP下载存放在OSS中的文件。HTTP下载包括直接使用浏览器下载或者使用wgetcurl等命令行工具下载，此时文件的URL需要由SDK生成。

使用Bucket#object_url方法生成可下载的HTTP地址，包含以下参数：

key：要下载的文件名称。
sign：是否生成带签名的URL。
说明
- 对于拥有公共读（public-read）或者公共读写（public-read-write）权限的文件，允许通过不带签名的URL进行访问。
- 对于私有（private）权限的文件，则必须通过带签名的URL进行访问。
expires：URL的有效时间，默认值为60s。

require 'aliyun/oss'

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

bucket = client.get_bucket('my-bucket')
# 生成URL，默认带签名，有效时间为60秒。
puts bucket.object_url('my-object')
# http://my-bucket.oss-cn-hangzhou.aliyuncs.com/my-object?Expires=1448349966&OSSAccessKeyId=5vxxxx&Signature=aM2HpBLeMq1aec6JCd7BBAKYiwI%3D

# 不带签名的URL。
puts bucket.object_url('my-object', false)
# http://my-bucket.oss-cn-hangzhou.aliyuncs.com/my-object

# 指定URL过期时间为1小时（3600秒）。
puts bucket.object_url('my-object', true, 3600)

对象存储 OSS

下载文件

下载到本地文件

流式下载

断点续传下载

HTTP下载

FAQ