Tencent COS Ruby SDK

Tencent🐧 COS(Cloud Object Service) SDK for Ruby 腾讯云对象存储服务

100%实现COS官方Restful API
符合Ruby使用习惯的链式操作
支持HTTPS
支持大文件自动多线程分片断点续传上传、下载
支持Rails
提供便捷的CLI工具:

CLI示例

Tencent COS Ruby SDK

1 运行环境

Ruby版本：MRI >= 1.9.3, JRuby >= 1.9
操作系统：Windows/Linux/OS X

2 安装SDK

添加至应用程序的Gemfile文件：

gem 'cos'

然后执行：

$ bundle

或手动安装gem：

$ gem install cos

3 快速入门

3.1 准备工作

在腾讯云COS控制台创建Bucket并获取您的app_id secret_id secret_key

🔍具体操作可参考COS控制台使用说明

3.2 初始化

require 'cos'

client = COS::Client.new({
  app_id:     'your_app_id',
  secret_id:  'your_secret_id',
  secret_key: 'your_secret_key',
  protocol:   'https' # 使用https
})

更多初始化参数及加载方式请见： 4.1 初始化与配置

3.3 指定Bucket

bucket = client.bucket('your_bucket_name')

🎉【Tip】你也可以在初始化Client时通过default_bucket参数设置默认的Bucket：

client = COS::Client.new({
  app_id:         'your_app_id',
  secret_id:      'your_secret_id',
  secret_key:     'your_secret_key',
  defualt_bucket: 'your_default_bucket',
})
# 取得默认Bucket
bucket = client.bucket

3.4 目录操作示例

# 列举bucket根目录中的文件与目录
bucket.list do |res|
  if res.is_a?(COS::COSDir) # 或 res.type == 'dir'
    puts "Dir：#{res.name} #{res.biz_attr}"
    # 设置目录属性
    res.update('属性1')
  else
    # 文件 COS::COSFile 或 res.type == 'file'
    puts "File：#{res.name}"
    # 输出Hash参数
    puts res.to_hash
  end
end

# 可以按路径列出资源
bucket.list('/path/path2/') { |r| puts r.name }

# 只列出文件
bucket.list('/path/path2/', :pattern => :only_file) { |r| puts r.name }

# 倒序只列出目录
bucket.list('/path/path2/', :pattern => :only_dir, :order => :desc) { |r| puts r.name }

# 获取bucket信息
b = bucket.stat
puts b.refers

# 判断目录是否存在
puts bucket.exist?('dir')
# 获取目录信息
dir = bucket.stat('dir')
# 创建时间修改时间
puts dir.created_at
puts dir.updated_at
# 判断目录是否是空的
puts dir.empty?
# 目录中的文件及目录总数
puts dir.count
# 目录中的文件总数
puts dir.count_files
# 目录中的文件夹总数
puts dir.count_dirs
# 获取目录的树形结构
puts dir.hash_tree.to_json
# 删除目录
puts dir.delete!
# 上传文件至目录, 自动大文件分片多线程断点续传
dir.upload('file2', '~/path2/file2')
# 批量上传文件至目录，自动大文件分片多线程断点续传
dir.upload_all('~/path1')
# 下载目录中的所有文件，自动大文件分片多线程断点续传
puts bucket.stat('path3').download_all('~/path_store')

3.5 文件操作示例

# 上传文件，自动大文件分片多线程断点续传
file = bucket.upload('path', 'file1', '~/local_path/file1') do |pr|
  puts "上传进度 #{(pr*100).round(2)}%"
end
# 判断文件是否存在
puts bucket.exist?('path/file1')
# 获取文件信息
file = bucket.stat('path/file1')
puts file.name
puts file.biz_attr
# 更新文件属性
file.update('i am a biz attr')
# 判断文件是否上传完成
puts file.complete?
# 获取文件大小
puts file.size # file.file_size OR file.filesize
# 获取文件格式化的文件大小
puts file.format_size # 102KB, 3.1MB, 1.5GB
# 下载文件，自动大文件分片多线程断点续传
file.download('~/path/file1') do |pr|
  puts "下载进度 #{(pr*100).round(2)}%"
end
# 获取文件访问URL，私有读取bucket自动添加签名
file.url(cname: 's.domain.com')
# 删除文件
file.delete

4 SDK详细说明

4.1 初始化与配置

4.1.1 详细参数

  {
    # COS分配的app_id
    :app_id => 'app_id',
    # COS分配的secret_id
    :secret_id => 'secret_id',
    # COS分配的secret_key
    :secret_key => 'secret_key',
    # COS Reatful API Host
    :host => 'web.file.myqcloud.com',
    # 使用协议,默认为http,可选https
    :protocol => 'https',
    # 接口通讯建立连接超时秒数
    :open_timeout => 30,
    # 接口通讯读取数据超时秒数
    :read_timeout => 120,
    # 加载配置文件路径
    :config => '~/path/cos.yml',
    # 日志输出位置，可以是文件路径也可为STDOUT、STDERR
    :log_src => '/var/log/cos.log',
    # 输出日志级别
    :log_level => Logger::INFO,
    # 默认bucket
    :default_bucket => 'bucket_name',
    # 多次签名过期时间(单位秒)
    :multiple_sign_expire => 300
  }

4.1.2 标准方式初始化配置

  require 'cos'

  @client = COS::Client.new(configs)

4.1.3 实例方式初始化配置

  require 'cos'

  # 程序启动时加载配置
  COS.client(configs)
  # 使用client
  COS.client.bucket

4.1.4 从配置文件加载配置

  require 'cos'

  @client = COS::Client.new(config: './cos.yml')
  # 或
  COS.client(config: './cos.yml')

Rails中会自动加载项目目录下的配置文件log/cos.yml

🎉【Tip】可以使用CLI指令cos init创建默认的yml配置文件，cos init [配置文件路径]自定义配置文件的路径。

4.2 指定Bucket

所有的资源基本操作是基于一个bucket的，所有我们需要先指定一个bucket：

@bucket = @client.bucket('bucket_name')
# 或使用配置的默认bucket
@bucket = @client.bucket

注：指定bucket时，SDK会获取一次bucket信息，获取权限类型等信息，如bucket不存在将会抛出异常。

4.3 Bucket操作（COS::Bucket）

4.3.1 获取Bucket属性

# bucket名称
puts @bucket.bucket_name
# bucket权限
puts @bucket.authority

属性	类型	描述
bucket_name	String	bucket名称
authority	String	eWPrivateRPublic私有写公共读，eWPrivate私有写私有读
bucket_type	Integer	bucket_type
migrate_source_domain	String	回源地址
need_preview	String	need_preview
refers	Array	refers
blackrefers	Array	blackrefers
cnames	Array	cnames
nugc_flag	String	nugc_flag

4.3.2 创建目录（create_folder，mkdir）

@bucket.create_folder(path, options = {}) # 方法别名mkdir

参数：

参数名	类型	必须	默认值	参数描述
path	String	是	无	需要创建的目录路径, 如: 'path1', 'path1/path2', sdk会补齐末尾的 '/'。
options	Hash
options[:biz_attr]	String	否	无	目录属性, 业务端维护

COS::COSDir # 详见目录操作（COS::COSDir）

示例：

@bucket.create_folder("test_dir1", biz_attr: '测试目录1')

更多示例详见：example/create_folder.rb

4.3.3 列举目录（list，ls）

@bucket.list(path = '', options = {}) # 方法别名ls

参数：

参数名	类型	必须	默认值	参数描述
path	String	否	空	需要列举的目录路径, 如: 'path1', 'path1/path2', sdk会补齐末尾的 '/'。
options	Hash
options[:prefix]	String	否	无	搜索前缀，如果填写prefix, 则列出含此前缀的所有文件及目录
options[:num]	Integer	否	20
options[:pattern]	Symbol	否	:both	获取模式，:dir_only 只获取目录, :file_only 只获取文件, 默认为 :both 全部获取
options[:order]	Symbol	否	:asc	排序方式 :asc 正序, :desc 倒序默认为 :asc

[Enumerator<Object>] 迭代器, 其中Object可能是COS::COSFile或COS::COSDir

示例：

@bucket.list('test') do |res|
  if res.is_a?(COS::COSDir)
    puts "Dir: #{res.name} #{res.path}"
  else
    puts "File: #{res.name} #{res.format_size}"
  end
end

更多示例详见：example/list.rb

4.3.4 上传文件（upload）

@bucket.upload(path_or_dir, file_name, file_src, options = {}, &block)

参数：

参数名	类型	必须	默认值	参数描述
path_or_dir	String/COS::COSDir	否	空	目录路径或目录对象COSDir目录路径如: '/', 'path1', 'path1/path2', sdk会补齐末尾的 '/'
file_name	String	是	无	存储文件名
file_src	String	是	无	本地文件路径
options	Hash	否	无
options[:auto_create_folder]	Boolean	否	false	自动创建远端目录
options[:min_slice_size]	Integer	否	10 * 1024 * 1024	完整上传最小文件大小,超过此大小将会使用分片多线程断点续传
options[:upload_retry]	Integer	否	10	上传重试次数
options[:biz_attr]	String	否	无	业务属性
options[:disable_cpt]	Boolean	否	false	是否禁用checkpoint，如禁用仍可通过服务端进行断点续传
options[:threads]	Integer	否	10	多线程上传线程数
options[:slice_size]	Integer	否	3 * 1024 * 1024	设置分片上传时每个分片的大小。默认为3 MB, 目前服务端最大限制也为3MB。
options[:cpt_file]	String	否	无	断点续传的checkpoint文件
yield	Float	否	无	上传进度百分比回调, 进度值是一个0-1之间的小数

注：SDK会自动使用分片断点续传上传大文件。

COS::COSFile # 详见目录操作（COS::COSFile）

示例：

file = @bucket.upload('/test', 'file1.txt', '~/test.txt') do |pr|
  puts "上传进度 #{(pr*100).round(2)}%"
end
puts file.name
puts file.format_size
puts file.url

更多示例详见： example/upload.rb

4.3.4 资源属性（stat）

@bucket.stat(path)

参数：

参数名	类型	必须	默认值	参数描述
path	String	是	无	资源路径, 如: 目录'path1/', 文件'path1/file'。

可能是COS::COSFile(文件)或COS::COSDir(目录)

示例：

puts @bucket.stat('/test').name

更多示例详见： example/stat.rb

4.3.5 更新资源属性（upadte）

@bucket.update(path, biz_attr)

参数：

参数名	类型	必须	默认值	参数描述
path	String	是	无	资源路径, 如: 目录'path1/', 文件'path1/file'。
biz_attr	String	是	无	业务属性

示例：

@bucket.update('test/file1', 'new biz attr')

更多示例详见： example/update.rb

4.3.6 删除资源（delete）

@bucket.delete(path)

参数：

参数名	类型	必须	默认值	参数描述
path	String	是	无	资源路径, 如: 目录'path1/', 文件'path1/file'。

注意：非空目录或根目录无法删除，会抛出异常

示例：

@bucket.delete('test/')

更多示例详见：example/delete.rb

4.3.7 删除资源（无异常）（delete!）

@bucket.delete!(path)

参数：

参数名	类型	必须	默认值	参数描述
path	String	是	无	资源路径, 如: 目录'path1/', 文件'path1/file'。

注意：非空目录或根目录无法删除，返回是否成功的bool值。

Boolean

示例：

puts @bucket.delete!('test/')

更多示例详见：example/delete.rb

4.3.8 判断目录是否为空（empty?）

@bucket.empty?(path)

参数：

参数名	类型	必须	默认值	参数描述
path	String	否	空	目录路径, 如: 目录'path1/'。如为空则会判断bucket是否为空。

Boolean

示例：

# 目录是否为空
puts @bucket.empty?('test/')
# bucket是否为空
puts @bucket.empty?

4.3.9 判断资源是否存在（exist?，exists?）

@bucket.exist?(path) # 别名 exists?

参数：

参数名	类型	必须	默认值	参数描述
path	String	是	无	资源路径, 如: 目录'path1/', 文件'path1/file'

Boolean

示例：

puts @bucket.exist?('test/')
puts @bucket.exist?('test/file1')

4.3.9 判断文件是否上传完成（complete?）

@bucket.complete?(path)

参数：

参数名	类型	必须	默认值	参数描述
path	String	是	无	文件资源路径, 如: 'path1/file'

Boolean

示例：

puts @bucket.complete?('path/file1')

4.3.10 获取文件的访问URL（url）

@bucket.url(path_or_file, options = {})

参数：

参数名	类型	必须	默认值	参数描述
path_or_file	String/COS::COSFile	否	空	文件资源COSFile或路径, 如: 'path1/file'
options	Hash
options[:cname]	String	否	无	获取使用cname的url。在cos控制台设置的cname域名
options[:https]	Boolean	否	false	是否获取https的url
options[:expire_seconds]	Integer	否	600	签名有效时间(秒,私有读取bucket时需要)

String

示例：

puts bucket.url('path1/file1', https: true, cname: 'static.domain.com')

4.3.11 下载文件（download）

@bucket.download(path_or_file, file_store, options = {}, &block)

参数：

参数名	类型	必须	默认值	参数描述
path_or_file	String/COS::COSFile	是	无	文件资源COSFile或路径, 如: 'path1/file'
file_store	String	是	无	本地文件存储路径
options	Hash	否	无
options[:disable_mkdir]	Boolean	否	true	禁止自动创建本地文件夹, 默认会创建
options[:min_slice_size]	Integer	否	5 * 10 * 1024	完整下载最小文件大小,超过此大小将会使用分片多线程断点续传
options[:part_size]	Integer	否	5 * 10 * 1024	分片下载大小,如多线程下载时使用该大小分片下载
options[:download_retry]	Integer	否	10	下载重试次数
options[:disable_cpt]	Boolean	否	false	是否禁用checkpoint，如果禁用则不使用断点续传
yield	Float	否	无	下载进度百分比回调, 进度值是一个0-1之间的小数

注：支持私有访问资源下载，SDK会自动携带鉴权签名。SDK会自动使用分片断点续传下载大文件。

String # 本地文件存储路径

示例：

file = bucket.download('path/file1', '~/test/file1') do |p|
  puts "下载进度: #{(p*100).round(2)}%")
end
puts file

更多示例详见：example/download.rb

4.3.12 获取Object树形结构（tree）

@bucket.tree(path_or_dir = '', options = {})

参数：

参数名	类型	必须	默认值	参数描述
path_or_dir	String/COS::COSDir	否	空	目录路径或目录对象COSDir目录路径如: '/', 'path1', 'path1/path2', sdk会补齐末尾的 '/'
options	Hash
options[:depth]	Integer	否	5	子目录深度,默认为5
options[:files]	Boolean	否	false	同时列出文件,默认不列出

{
    :resource => Object<COS::COSDir>,
    :children => [
        {:resource => Object<COS::COSDir>, :children => [...]},
        {:resource => Object<COS::COSFile>, :children => [...]},
        ...
    ]
}

示例：

tree = @bucket.tree
puts tree[:resource].name
tree[:children].each do |r|
  puts r[:resource].name
end

4.3.13 获取Hash树形结构（hash_tree）

@bucket.hash_tree(path_or_dir = '', options = {})

参数：

参数名	类型	必须	默认值	参数描述
path_or_dir	String/COS::COSDir	否	空	目录路径或目录对象COSDir目录路径如: '/', 'path1', 'path1/path2', sdk会补齐末尾的 '/'
options	Hash
options[:depth]	Integer	否	5	子目录深度,默认为5
options[:files]	Boolean	否	false	同时列出文件,默认不列出

{
    :resource => {:name...},
    :children => [
        {:resource => {:name...}, :children => [...]},
        {:resource => {:name...}, :children => [...]},
        ...
    ]
}

示例：

tree = @bucket.hash_tree
puts tree[:resource][:name]
tree[:children].each do |r|
  puts r[:resource][:name]
end
puts tree.to_json # 可直接转为json

4.3.14 批量下载目录下的所有文件（download_all）

@bucket.download_all(path_or_dir, file_store_path, options = {}, &block)

参数：

参数名	类型	必须	默认值	参数描述
path_or_dir	String/COS::COSDir	否	空	目录路径或目录对象COSDir目录路径如: '/', 'path1', 'path1/path2', sdk会补齐末尾的 '/'
file_store_path	String	是	无	本地文件存储目录
options	Hash	否	无
options[:disable_mkdir]	Boolean	否	true	禁止自动创建本地文件夹, 默认会创建
options[:min_slice_size]	Integer	否	5 * 10 * 1024	完整下载最小文件大小,超过此大小将会使用分片多线程断点续传
options[:download_retry]	Integer	否	10	下载重试次数
options[:disable_cpt]	Boolean	否	false	是否禁用checkpoint，如果禁用则不使用断点续传
yield	Float	否	无	下载进度百分比回调, 进度值是一个0-1之间的小数

注：不包含子目录。支持私有访问资源下载，SDK会自动携带鉴权签名。SDK会自动使用分片断点续传下载大文件。

Array<String> # 本地文件存储路径数组

示例：

files = bucket.download_all('path/', '~/test/path/') do |p|
  puts "下载进度: #{(p*100).round(2)}%")
end
puts files

4.3.15 批量上传目录中的所有文件（upload_all）

@bucket.upload(path_or_dir, file_src_path, options = {}, &block)

参数：

参数名	类型	必须	默认值	参数描述
path_or_dir	String/COS::COSDir	否	空	目录路径或目录对象COSDir目录路径如: '/', 'path1', 'path1/path2', sdk会补齐末尾的 '/'
file_src_path	String	是	无	本地文件夹路径
options	Hash	否	无
options[:skip_error]	Boolean	否	false	是否跳过错误仍继续上传下一个文件
options[:auto_create_folder]	Boolean	否	false	自动创建远端目录
options[:min_slice_size]	Integer	否	10 * 1024 * 1024	完整上传最小文件大小,超过此大小将会使用分片多线程断点续传
options[:upload_retry]	Integer	否	10	上传重试次数
options[:biz_attr]	String	否	无	业务属性
options[:disable_cpt]	Boolean	否	false	是否禁用checkpoint，如禁用仍可通过服务端进行断点续传
options[:threads]	Integer	否	10	多线程上传线程数
options[:slice_size]	Integer	否	3 * 1024 * 1024	设置分片上传时每个分片的大小。默认为3 MB, 目前服务端最大限制也为3MB。
options[:cpt_file]	String	否	无	断点续传的checkpoint文件
yield	Float	否	无	上传进度百分比回调, 进度值是一个0-1之间的小数

注：不包含子目录。SDK会自动使用分片断点续传上传大文件。

Array<COS::COSFile> # 详见目录操作（COS::COSFile）

示例：

files = @bucket.upload_all('/test', '~/path') do |pr|
  puts "上传进度 #{(pr*100).round(2)}%"
end
puts files

4.3.16 获取资源个数详情（支持前缀搜索）（list_count）

@bucket.list_count(path = '', options = {})

参数：

参数名	类型	必须	默认值	参数描述
path	String	否	空	目录路径, 如: 'path1', 'path1/path2', sdk会补齐末尾的 '/'。默认获取bucket根目录
options	Hash
options[:prefix]	String	否	无	前缀搜索

Hash
{
  :total => 5, # 目录及文件总数
  :files => 2, # 文件总数
  :dirs => 3, # 目录总数
}

示例：

puts @bucket.list_count[:files]

4.3.17 获取资源个数（count, size）

@bucket.count(path = '') # 别名 size

参数：

参数名	类型	必须	默认值	参数描述
path	String	否	空	目录路径, 如: 'path1', 'path1/path2', sdk会补齐末尾的 '/'。默认获取bucket根目录

Integer # 目录及文件总数

示例：

puts @bucket.count

4.3.18 获取文件个数（count_files）

@bucket.count_files(path = '')

参数：

参数名	类型	必须	默认值	参数描述
path	String	否	空	目录路径, 如: 'path1', 'path1/path2', sdk会补齐末尾的 '/'。默认获取bucket根目录

Integer # 文件总数

示例：

puts @bucket.count_files

4.3.19 获取目录个数（count_dirs）

@bucket.count_dirs(path = '')

参数：

参数名	类型	必须	默认值	参数描述
path	String	否	空	目录路径, 如: 'path1', 'path1/path2', sdk会补齐末尾的 '/'。默认获取bucket根目录

Integer # 目录总数

示例：

puts @bucket.count_dirs

4.4 资源操作

4.4.1 文件操作（COS::COSFile）

4.4.1.1 获取文件属性

# 文件名称 
puts file.name
# 文件格式化大小 1B 1KB 1.1MB 1.12GB...
puts file.format_size

属性	类型	描述
name	String	名称
path	String	存储路径
ctime	String	创建时间unix时间戳
mtime	String	修改时间unix时间戳
created_at	Time	创建时间Time
updated_at	Time	修改时间Time
biz_attr	String	业务属性
filesize（file_size, size）	Integer	文件大小
filelen	Integer	已上传的文件大小
sha	String	文件sha1值
access_url	String	文件访问url
type	String	类型，固定为file
format_size	String	格式化文件大小 1B 1KB 1.1MB 1.12GB

4.4.1.2 获取当前文件属性（刷新）（stat）

file.stat

COS::COSFile

示例：

puts file.stat.to_hash

4.4.1.3 更新当前文件属性（upadte）

file.update(biz_attr)

参数：

参数名	类型	必须	默认值	参数描述
biz_attr	String	是	无	业务属性

示例：

file.update('new biz attr')

4.4.1.4 删除当前文件（delete）

file.delete

注意：删除失败将抛出异常

示例：

file.delete

4.4.1.5 删除当前文件（无异常）（delete!）

file.delete!

注意：删除失败不会抛出异常，返回是否成功的bool值。

Boolean

示例：

puts file.delete!

4.4.1.6 判断当前文件是否存在（exist?，exists?）

file.exist? # 别名 exists?

Boolean

示例：

puts file.exist?

4.4.1.7 判断当前文件是否上传完成（complete?）

file.complete?

Boolean

示例：

puts file.complete?

4.4.1.8 获取当前文件的访问URL（url）

file.url(options = {})

参数：

参数名	类型	必须	默认值	参数描述
options	Hash
options[:cname]	String	否	无	获取使用cname的url。在cos控制台设置的cname域名
options[:https]	Boolean	否	false	是否获取https的url
options[:expire_seconds]	Integer	否	600	签名有效时间(秒,私有读取bucket时需要)

String

示例：

puts file.url(https: true, cname: 'static.domain.com')

4.4.1.9 下载当前文件（download）

file.download(file_store, options = {}, &block)

参数：

参数名	类型	必须	默认值	参数描述
file_store	String	是	无	本地文件存储路径
options	Hash	否	无
options[:disable_mkdir]	Boolean	否	true	禁止自动创建本地文件夹, 默认会创建
options[:min_slice_size]	Integer	否	5 * 10 * 1024	完整下载最小文件大小,超过此大小将会使用分片多线程断点续传
options[:download_retry]	Integer	否	10	下载重试次数
options[:disable_cpt]	Boolean	否	false	是否禁用checkpoint，如果禁用则不使用断点续传
yield	Float	否	无	下载进度百分比回调, 进度值是一个0-1之间的小数

注：支持私有访问资源下载，SDK会自动携带鉴权签名。SDK会自动使用分片断点续传下载大文件。

String # 本地文件存储路径

示例：

file = file.download('~/test/file1') do |p|
  puts "下载进度: #{(p*100).round(2)}%")
end
puts file

4.4.1.10 判断当前文件与本地文件是否相同

file.sha1_match?(file)

参数：

参数名	类型	必须	默认值	参数描述
file	String	是	无	本地文件路径

Boolean

示例：

puts file.sha1_match?('~/file1')

4.4.2 目录操作（COS::COSDir）

4.4.2.1 获取目录属性

# 目录名称 
puts dir.name
# 目录存储路径
puts dir.path

属性	类型	描述
name	String	名称
path	String	存储路径
ctime	String	创建时间unix时间戳
mtime	String	修改时间unix时间戳
created_at	Time	创建时间Time
updated_at	Time	修改时间Time
biz_attr	String	业务属性
type	String	类型，固定为dir

4.4.2.2 列举当前目录（前缀搜索）（list，ls）

dir.list(options = {}) # 方法别名ls

参数：

参数名	类型	必须	默认值	参数描述
options	Hash
options[:prefix]	String	否	无	搜索前缀，如果填写prefix, 则列出含此前缀的所有文件及目录
options[:num]	Integer	否	20
options[:pattern]	Symbol	否	:both	获取模式，:dir_only 只获取目录, :file_only 只获取文件, 默认为 :both 全部获取
options[:order]	Symbol	否	:asc	排序方式 :asc 正序, :desc 倒序默认为 :asc

[Enumerator<Object>] 迭代器, 其中Object可能是COS::COSFile或COS::COSDir

示例：

dir.list do |res|
  if res.is_a?(COS::COSDir)
    puts "Dir: #{res.name} #{res.path}"
  else
    puts "File: #{res.name} #{res.format_size}"
  end
end

4.4.2.3 创建子目录（create_folder，mkdir）

dir.create_folder(dir_name, options = {}) # 方法别名mkdir

参数：

参数名	类型	必须	默认值	参数描述
dir_name	String	是	无	需要创建的子目录名称，不包含父系目录路径。
options	Hash
options[:biz_attr]	String	否	无	目录属性, 业务端维护

COS::COSDir

示例：

dir.create_folder("test_dir2", biz_attr: '测试目录1-2')

4.4.2.4 上传文件至当前目录（upload）

dir.upload(file_name, file_src, options = {}, &block)

参数：

参数名	类型	必须	默认值	参数描述
file_name	String	是	无	存储文件名
file_src	String	是	无	本地文件路径
options	Hash	否	无
options[:auto_create_folder]	Boolean	否	false	自动创建远端目录
options[:min_slice_size]	Integer	否	10 * 1024 * 1024	完整上传最小文件大小,超过此大小将会使用分片多线程断点续传
options[:upload_retry]	Integer	否	10	上传重试次数
options[:biz_attr]	String	否	无	业务属性
options[:disable_cpt]	Boolean	否	false	是否禁用checkpoint，如禁用仍可通过服务端进行断点续传
options[:threads]	Integer	否	10	多线程上传线程数
options[:slice_size]	Integer	否	3 * 1024 * 1024	设置分片上传时每个分片的大小。默认为3 MB, 目前服务端最大限制也为3MB。
options[:cpt_file]	String	否	无	断点续传的checkpoint文件
yield	Float	否	无	上传进度百分比回调, 进度值是一个0-1之间的小数

注：SDK会自动使用分片断点续传上传大文件。

COS::COSFile

示例：

file = dir.upload('file1.txt', '~/test.txt') do |pr|
  puts "上传进度 #{(pr*100).round(2)}%"
end
puts file.name
puts file.format_size
puts file.url

4.4.2.5 批量上传本地目录中的所有文件至当前目录（upload_all）

dir.upload(file_src_path, options = {}, &block)

参数：

参数名	类型	必须	默认值	参数描述
file_src_path	String	是	无	本地文件夹路径
options	Hash	否	无
options[:skip_error]	Boolean	否	false	是否跳过错误仍继续上传下一个文件
options[:auto_create_folder]	Boolean	否	false	自动创建远端目录
options[:min_slice_size]	Integer	否	10 * 1024 * 1024	完整上传最小文件大小,超过此大小将会使用分片多线程断点续传
options[:upload_retry]	Integer	否	10	上传重试次数
options[:biz_attr]	String	否	无	业务属性
options[:disable_cpt]	Boolean	否	false	是否禁用checkpoint，如禁用仍可通过服务端进行断点续传
options[:threads]	Integer	否	10	多线程上传线程数
options[:slice_size]	Integer	否	3 * 1024 * 1024	设置分片上传时每个分片的大小。默认为3 MB, 目前服务端最大限制也为3MB。
options[:cpt_file]	String	否	无	断点续传的checkpoint文件
yield	Float	否	无	上传进度百分比回调, 进度值是一个0-1之间的小数

注：不包含子目录。SDK会自动使用分片断点续传上传大文件。

Array<COS::COSFile>

示例：

files = dir.upload_all('~/path') do |pr|
  puts "上传进度 #{(pr*100).round(2)}%"
end

4.4.2.6 批量下载当前目录下的所有文件（download_all）

dir.download_all(file_store_path, options = {}, &block)

参数：

参数名	类型	必须	默认值	参数描述
file_store_path	String	是	无	本地文件存储目录
options	Hash	否	无
options[:disable_mkdir]	Boolean	否	true	禁止自动创建本地文件夹, 默认会创建
options[:min_slice_size]	Integer	否	5 * 10 * 1024	完整下载最小文件大小,超过此大小将会使用分片多线程断点续传
options[:download_retry]	Integer	否	10	下载重试次数
options[:disable_cpt]	Boolean	否	false	是否禁用checkpoint，如果禁用则不使用断点续传
yield	Float	否	无	下载进度百分比回调, 进度值是一个0-1之间的小数

注：不包含子目录。支持私有访问资源下载，SDK会自动携带鉴权签名。SDK会自动使用分片断点续传下载大文件。

Array<String> # 本地文件存储路径数组

示例：

files = dir.download_all('~/test/path/') do |p|
  puts "下载进度: #{(p*100).round(2)}%")
end

4.4.2.7 当前目录属性（刷新）（stat）

dir.stat

COS::COSDir

示例：

puts dir.stat.to_hash

4.4.2.8 更新当前目录属性（upadte）

dir.update(biz_attr)

参数：

参数名	类型	必须	默认值	参数描述
biz_attr	String	是	无	业务属性

示例：

dir.update('new biz attr')

4.4.2.9 删除当前目录（delete）

dir.delete

注意：非空目录或根目录无法删除，会抛出异常

示例：

dir.delete

4.4.2.10 删除当前目录（无异常）（delete!）

dir.delete!

注意：非空目录或根目录无法删除，返回是否成功的bool值。

Boolean

示例：

puts dir.delete!

4.4.2.11 判断当前目录是否为空（empty?）

dir.empty?

Boolean

示例：

puts dir.empty?

4.4.2.12 判断当前目录是否存在（exist?，exists?）

dir.exist? # 别名 exists?

Boolean

示例：

puts dir.exist?

4.4.2.13 获取当前目录下的Object树形结构（tree）

dir.tree(options = {})

参数：

参数名	类型	必须	默认值	参数描述
options	Hash
options[:depth]	Integer	否	5	子目录深度,默认为5

{
    :resource => Object<COS::COSDir>,
    :children => [
        {:resource => Object<COS::COSDir>, :children => [...]},
        {:resource => Object<COS::COSFile>, :children => [...]},
        ...
    ]
}

示例：

tree = dir.tree
puts tree[:resource].name
tree[:children].each do |r|
  puts r[:resource].name
end

4.4.2.14 获取当前目录下的Hash树形结构（hash_tree）

dir.hash_tree(options = {})

参数：

参数名	类型	必须	默认值	参数描述
options	Hash
options[:depth]	Integer	否	5	子目录深度,默认为5

{
    :resource => {:name...},
    :children => [
        {:resource => {:name...}, :children => [...]},
        {:resource => {:name...}, :children => [...]},
        ...
    ]
}

示例：

tree = dir.hash_tree
puts tree[:resource][:name]
tree[:children].each do |r|
  puts r[:resource][:name]
end
puts tree.to_json # 可直接转为json

4.4.2.15 获取当前目录下的资源个数详情（支持前缀搜索）（list_count）

dir.list_count(options = {})

参数：

参数名	类型	必须	默认值	参数描述
options	Hash
options[:prefix]	String	否	无	前缀搜索

Hash
{
  :total => 5, # 目录及文件总数
  :files => 2, # 文件总数
  :dirs => 3, # 目录总数
}

示例：

puts dir.list_count[:files]

4.4.2.16 获取当前目录下的资源个数（count, size）

dir.count # 别名 size

Integer # 目录及文件总数

示例：

puts dir.count

4.4.2.17 获取当前目录下的文件个数（count_files）

dir.count_files

Integer # 文件总数

示例：

puts dir.count_files

4.4.2.18 获取当前目录下的子目录个数（count_dirs）

dir.count_dirs

Integer # 目录总数

示例：

puts dir.count_dirs

4.5 签名操作（COS::Signature）

腾讯移动服务通过签名来验证请求的合法性。开发者通过将签名授权给客户端，使其具备上传下载及管理指定资源的能力。签名分为多次有效签名和单次有效签名

🔍具体适用场景参见签名适用场景

4.5.1 获取单次有效签名（once）

签名中绑定文件fileid，此签名只可使用一次，且只能应用于被绑定的文件。

puts @client.signature.once(bucket_name, path)
# path 为操作资源的路径

4.5.2 获取多次有效签名（multiple）

签名中不绑定文件fileid，有效期内此签名可多次使用，有效期最长可设置三个月。

puts @client.signature.multiple(bucket_name, expire_seconds)
# expire_seconds 为从获取时间起得有效时间单位秒，必须大于0。

5 底层API（COS::API）

5.1 创建目录(create_folder)

@client.api.create_folder(path, options = {})

参数：

参数名	类型	必须	默认值	参数描述
path	String	是	无	需要创建的目录路径, 如: 'path1', 'path1/path2', sdk会补齐末尾的 '/'。
options	Hash
options[:biz_attr]	String	否	无	目录属性, 业务端维护
options[:bucket]	String	否	无	bucket名称，如未配置default_bucket则必须制定

Hash

参数名	类型	必须	参数描述
ctime	String	是	创建时间Unix时间戳
resource_path	String	是	创建的资源路径

示例：

puts @client.api.create_folder("test_dir5", biz_attr: '测试目录5')

5.2 目录列表（前缀搜索）(list)

@client.api.list(path, options = {})

参数：

参数名	类型	必须	默认值	参数描述
path	String	是	否	需要列举的目录路径, 如: 'path1', 'path1/path2', sdk会补齐末尾的 '/'。
options	Hash
options[:prefix]	String	否	无	搜索前缀，如果填写prefix, 则列出含此前缀的所有文件及目录
options[:num]	Integer	否	20
options[:pattern]	Symbol	否	:both	获取模式，:dir_only 只获取目录, :file_only 只获取文件, 默认为 :both 全部获取
options[:order]	Symbol	否	:asc	排序方式 :asc 正序, :desc 倒序默认为 :asc
options[:context]	String	否	空	若需要翻页，需要将前一页返回值中的context透传到参数中
options[:bucket]	String	否	无	bucket名称，如未配置default_bucket则必须制定

Hash

参数名	类型	必须	参数描述
context	String	是	透传字段,用于翻页,需要往前/往后翻页则透传回来
has_more	Boolean	是	是否有内容可以继续往前/往后翻页
dircount	Integer	是	子目录数量(总)
filecount	Integer	是	子文件数量(总)
infos	Array	是	列表结果(可能为空)
子属性 :name	String	是	目录名/文件名
子属性 :biz_attr	String	是	目录/文件属性，业务端维护
子属性 :filesize	Integer	否	文件大小(当类型为文件时返回)
子属性 :filelen	Integer	否	文件已传输大小(通过与filesize对比可知文件传输进度,当类型为文件时返回)
子属性 :sha	String	否	文件sha1(当类型为文件时返回)
子属性 :ctime	String	是	创建时间(Unix时间戳)
子属性 :mtime	String	是	修改时间(Unix时间戳)
子属性 :access_url	String	否	生成的资源可访问的url(当类型为文件时返回)

示例：

puts @client.api.list('/test', pattern: :dir_only, order: :desc, prefix: 'abc', context: '')

5.3 上传文件（完整上传）(upload)

@client.api.upload(path, file_name, file_src, options = {})

参数：

参数名	类型	必须	默认值	参数描述
path	String	是	无	目录路径, 如: '/', 'path1', 'path1/path2', sdk会补齐末尾的 '/'
file_name	String	是	无	存储文件名
file_src	String	是	无	本地文件路径
options	Hash	否	无
options[:biz_attr]	String	否	无	文件属性, 业务端维护
options[:bucket]	String	否	无	bucket名称，如未配置default_bucket则必须制定

Hash

参数名	类型	必须	参数描述
access_url	String	是	生成的文件下载url
url	String	是	操作文件的url
resource_path	String	是	资源路径

示例：

puts @client.api.upload('/test', 'file1.txt', '~/test.txt')

5.4 上传文件（分片上传）(upload_slice)

@client.api.upload_slice(path, file_name, file_src, options = {})

参数：

参数名	类型	必须	默认值	参数描述
path	String	是	无	目录路径, 如: '/', 'path1', 'path1/path2', sdk会补齐末尾的 '/'
file_name	String	是	无	存储文件名
file_src	String	是	无	本地文件路径
options	Hash	否	无
options[:biz_attr]	String	否	无	业务属性
options[:disable_cpt]	Boolean	否	false	是否禁用checkpoint，如禁用仍可通过服务端进行断点续传
options[:threads]	Integer	否	10	多线程上传线程数
options[:slice_size]	Integer	否	3 * 1024 * 1024	设置分片上传时每个分片的大小。默认为3 MB, 目前服务端最大限制也为3MB。
options[:cpt_file]	String	否	无	断点续传的checkpoint文件
options[:bucket]	String	否	无	bucket名称，如未配置default_bucket则必须制定
yield	Float	否	无	上传进度百分比回调, 进度值是一个0-1之间的小数

Hash

参数名	类型	必须	参数描述
access_url	String	是	生成的文件下载url
url	String	是	操作文件的url
resource_path	String	是	资源路径

示例：

puts @client.api.upload_slice('/test', 'file1.txt', '~/test.txt') do |pr|
  puts "上传进度 #{(pr*100).round(2)}%"
end

5.5 更新文件、目录属性(update)

@client.api.update(path, biz_attr, options = {})

参数：

参数名	类型	必须	默认值	参数描述
path	String	是	无	需要创建的目录路径, 如: 'path1', 'path1/path2', sdk会补齐末尾的 '/'。
biz_attr	String	是	无	目录属性, 业务端维护
options	Hash
options[:bucket]	String	否	无	bucket名称，如未配置default_bucket则必须制定

返回：无

示例：

@client.api.update('test/file1', 'new biz attr')

5.6 删除文件、目录(delete)

@client.api.delete(path, options = {})

参数：

参数名	类型	必须	默认值	参数描述
path	String	是	无	需要创建的目录路径, 如: 'path1', 'path1/path2', sdk会补齐末尾的 '/'。
options	Hash
options[:bucket]	String	否	无	bucket名称，如未配置default_bucket则必须制定

返回：无

示例：

@client.api.delete('test/file1')

5.7 获取文件或目录属性(stat)

@client.api.update(path, options = {})

参数：

	类型	必须	默认值	参数描述
path	String	是	无	需要创建的目录路径, 如: 'path1', 'path1/path2', sdk会补齐末尾的 '/'。
options	Hash
options[:bucket]	String	否	无	bucket名称，如未配置default_bucket则必须制定

Hash

参数名	类型	必须	参数描述
name	String	是	目录名/文件名
biz_attr	String	是	目录/文件属性，业务端维护
filesize	Integer	否	文件大小(当类型为文件时返回)
filelen	Integer	否	文件已传输大小(通过与filesize对比可知文件传输进度,当类型为文件时返回)
sha	String	否	文件sha1(当类型为文件时返回)
ctime	String	是	创建时间(Unix时间戳)
mtime	String	是	修改时间(Unix时间戳)
access_url	String	否	生成的资源可访问的url(当类型为文件时返回)

示例：

puts @client.api.stat('/test/file')

5.8下载文件

@client.api.download(access_url, file_store, options = {})

参数：

参数名	类型	必须	默认值	参数描述
access_url	String	是	无	资源的下载URL地址可以从list,stat接口中获取
file_store	String	是	无	本地文件存储路径
options	Hash	否	无
options[:bucket]	String	否	无	bucket名称，如未配置default_bucket则必须制定
options[:headers]	Hash	否	无	设置下载请求头,如:rang

示例：

@client.api.download('/test/file', '~/test.txt')

6 CLI命令行工具

SDK提供了一套包含所有API调用的CLI工具，方便开发者更好的调试与更便捷的使用COS。

获取CLI指令列表：

$ cos

COS Ruby SDK CLI commands:
  cos count [PATH]                           # 获取文件及目录数
  cos count_dirs [PATH]                      # 获取目录数
  cos count_files [PATH]                     # 获取文件数
  cos create_folder [PATH]                   # 创建目录
  cos delete [PATH]                          # 删除目录或文件
  cos download [PATH] [FILE_STORE]           # 下载文件(大文件自动分片下载,支持多线程断点续传)
  cos download_all [PATH] [FILE_STORE_PATH]  # 下载目录下的所有文件(不含子目录)
  cos is_exist [PATH]                        # 判断文件或目录是否存在
  cos help [COMMAND]                         # 获取指令的使用帮助
  cos init                                   # 创建默认配置文件
  cos is_complete [PATH]                     # 判断文件是否上传完整
  cos is_empty [PATH]                        # 判断目录是否为空
  cos list [PATH]                            # 获取目录列表
  cos sign_multi [EXPIRE]                    # 生成多次可用签名
  cos sign_once [PATH]                       # 生成单次可用签名
  cos stat [PATH]                            # 获取目录或文件信息
  cos tree [PATH]                            # 显示树形结构
  cos update [PATH] [BIZ_ATTR]               # 更新业务属性
  cos upload [PATH] [FILE_NAME] [FILE_SRC]   # 上传文件(大文件自动分片上传,支持多线程断点续传)
  cos upload_all [PATH] [FILE_SRC_PATH]      # 上传目录下的所有文件(不含子目录)
  cos url [PATH]                             # 获取文件的访问URL

Options:
  -c, [--config=CONFIG]  # 加载配置文件
                         # Default: ~/.cos.yml
  -b, [--bucket=BUCKET]  # 指定Bucket

获取指令的详细参数如：

$ cos help upload

Usage:
  cos upload [PATH] [FILE_NAME] [FILE_SRC]

Options:
  -r, [--biz-attr=BIZ_ATTR]                              # 业务属性
  -m, [--min-slice-size=bytes]                           # 最小完整上传大小
  -f, [--auto-create-folder], [--no-auto-create-folder]  # 自动创建目录
  -d, [--disable-cpt], [--no-disable-cpt]                # 禁用断点续传(分片上传时有效)
  -t, [--threads=N]                                      # 线程数(分片上传时有效)
  -n, [--upload-retry=N]                                 # 重试次数(分片上传时有效)
  -s, [--slice-size=N]                                   # 分片上传时每个分片的大小(分片上传时有效)
  -e, [--cpt-file=CPT_FILE]                              # 指定断点续传记录(分片上传时有效)
  -c, [--config=CONFIG]                                  # 加载配置文件
                                                         # Default: ~/.cos.yml
  -b, [--bucket=BUCKET]                                  # 指定Bucket

上传文件(大文件自动分片上传,支持多线程上传,断点续传)

初始化创建配置文件：(默认创建于~/.cos.yml)

$ cos init

使用CLI:

$ cos upload path/path2 file1 ~/file1

7 运行测试

7.1 单元测试

rspec

或

bundle exec rake spec

7.2 集成测试

先安装memory_profiler

gem install memory_profiler

bundle exec rake test