Tencent COS Ruby SDK

Gem Version Dependency Status Code Climate Build Status Test Coverage

Gitter Gem Downloads Github Code Yard Docs


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

  • 100%实现COS官方Restful API

  • 符合Ruby使用习惯的链式操作

  • 支持HTTPS

  • 支持大文件自动多线程分片断点续传上传、下载

  • 支持Rails

  • 提供便捷的CLI工具:

    CLI示例

目录

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 => 15,
    # 接口通讯读取数据超时秒数
    :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
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
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
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 = 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
options Hash
options[:depth] Integer 5 子目录深度,默认为5

返回:

{
    :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
options Hash
options[:depth] Integer 5 子目录深度,默认为5

返回:

{
    :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
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
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 运行测试

rspec

bundle exec rake spec