当下载大文件时,如果网络不稳定或者程序异常退出,会导致下载失败,甚至重试多次仍无法完成下载。为此,OSS提供了断点续传下载功能。断点续传下载将需要下载的文件分成若干个分片分别下载,所有分片都下载完成后,将所有分片合并成完整的文件。

通过Bucket#resumable_download接口来实现断点续传下载,包含以下参数:
  • key:要下载的文件名称。
  • file:下载到本地文件的路径。
  • opts:可选项,主要包括:
    • :cpt_file:指定checkpoint文件的路径,如果不指定,则默认是本地文件同目录下的file.cpt,其中file是本地文件的名称。
    • :disable_cpt:指定是否在下载过程中记录下载进度,默认值为false,表示记录下载进度。如果指定为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以华东1(杭州)为例,其它Region请按实际情况填写。
  endpoint: 'https://oss-cn-hangzhou.aliyuncs.com',
  # 阿里云账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维,请登录RAM控制台创建RAM用户。
  access_key_id: 'AccessKeyId', access_key_secret: 'AccessKeySecret')

# 填写Bucket名称,例如examplebucket。
bucket = client.get_bucket('examplebucket')
# 填写Object完整路径和本地文件的完整路径。Object完整路径中不能包含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文件丢失或被修改均会导致下载失败。

相关文档

关于断点续传下载的API接口说明,请参见GetObject