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文件:

ruby gem 'cos'

然后执行:

$ bundle

或手动安装gem:

$ gem install cos

3 快速入门

3.1 准备工作

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

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

3.2 初始化

``` ruby 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

ruby bucket = client.bucket('your_bucket_name')

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

ruby 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 目录操作示例

``` ruby # 列举bucket根目录中的文件与目录 bucket.list do |res| if res.is_a?(COS::COSDir) # 或 res.type == ‘dir’ puts “Dir:#resres.name #resres.biz_attr” # 设置目录属性 res.update(‘属性1’) else # 文件 COS::COSFile 或 res.type == ‘file’ puts “File:#resres.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 文件操作示例

ruby # 上传文件,自动大文件分片多线程断点续传 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 详细参数

    ruby { # 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 标准方式初始化配置

    ``` ruby require ‘cos’

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

  • 4.1.3 实例方式初始化配置

    ``` ruby require ‘cos’

    程序启动时加载配置

    COS.client(configs) # 使用client COS.client.bucket ```

  • 4.1.4 从配置文件加载配置

    ``` ruby 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:

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

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

4.3 Bucket操作(COS::Bucket)

4.3.1 获取Bucket属性

ruby # 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)

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

参数:

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

返回:

ruby COS::COSDir # 详见目录操作(COS::COSDir)

示例:

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

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

4.3.3 列举目录(list,ls)

ruby @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

返回:

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

示例:

ruby @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)

ruby @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会自动使用分片断点续传上传大文件。

返回:

ruby COS::COSFile # 详见目录操作(COS::COSFile)

示例:

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

ruby @bucket.stat(path)

参数:

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

返回:

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

示例:

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

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

4.3.5 更新资源属性(upadte)

ruby @bucket.update(path, biz_attr)

参数:

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

示例:

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

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

4.3.6 删除资源(delete)

ruby @bucket.delete(path)

参数:

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

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

示例:

ruby @bucket.delete('test/')

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

4.3.7 删除资源(无异常)(delete!)

ruby @bucket.delete!(path)

参数:

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

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

返回:

ruby Boolean

示例:

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

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

4.3.8 判断目录是否为空(empty?)

ruby @bucket.empty?(path)

参数:

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

返回:

ruby Boolean

示例:

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

4.3.9 判断资源是否存在(exist?,exists?)

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

参数:

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

返回:

ruby Boolean

示例:

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

4.3.9 判断文件是否上传完成(complete?)

ruby @bucket.complete?(path)

参数:

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

返回:

ruby Boolean

示例:

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

4.3.10 获取文件的访问URL(url)

ruby @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时需要)

返回:

ruby String

示例:

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

4.3.11 下载文件(download)

ruby @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会自动使用分片断点续传下载大文件。

返回:

ruby String # 本地文件存储路径

示例:

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

ruby @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 => [...]}, ... ] }

示例:

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

4.3.13 获取Hash树形结构(hash_tree)

ruby @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 => [...]}, ... ] }

示例:

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

ruby @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会自动使用分片断点续传下载大文件。

返回:

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

示例:

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

4.3.15 批量上传目录中的所有文件(upload_all)

ruby @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会自动使用分片断点续传上传大文件。

返回:

ruby Array<COS::COSFile> # 详见目录操作(COS::COSFile)

示例:

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

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

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

参数:

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

返回:

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

示例:

ruby puts @bucket.list_count[:files]

4.3.17 获取资源个数(count, size)

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

参数:

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

返回:

ruby Integer # 目录及文件总数

示例:

ruby puts @bucket.count

4.3.18 获取文件个数(count_files)

ruby @bucket.count_files(path = '')

参数:

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

返回:

ruby Integer # 文件总数

示例:

ruby puts @bucket.count_files

4.3.19 获取目录个数(count_dirs)

ruby @bucket.count_dirs(path = '')

参数:

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

返回:

ruby Integer # 目录总数

示例:

ruby puts @bucket.count_dirs

4.4 资源操作

4.4.1 文件操作(COS::COSFile)

4.4.1.1 获取文件属性

ruby # 文件名称 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)

ruby file.stat

返回:

ruby COS::COSFile

示例:

ruby puts file.stat.to_hash

4.4.1.3 更新当前文件属性(upadte)

ruby file.update(biz_attr)

参数:

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

示例:

ruby file.update('new biz attr')

4.4.1.4 删除当前文件(delete)

ruby file.delete

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

示例:

ruby file.delete

4.4.1.5 删除当前文件(无异常)(delete!)

ruby file.delete!

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

返回:

ruby Boolean

示例:

ruby puts file.delete!

4.4.1.6 判断当前文件是否存在(exist?,exists?)

ruby file.exist? # 别名 exists?

返回:

ruby Boolean

示例:

ruby puts file.exist?

4.4.1.7 判断当前文件是否上传完成(complete?)

ruby file.complete?

返回:

ruby Boolean

示例:

ruby puts file.complete?

4.4.1.8 获取当前文件的访问URL(url)

ruby file.url(options = {})

参数:

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

返回:

ruby String

示例:

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

4.4.1.9 下载当前文件(download)

ruby 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会自动使用分片断点续传下载大文件。

返回:

ruby String # 本地文件存储路径

示例:

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

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

ruby file.sha1_match?(file)

参数:

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

返回:

ruby Boolean

示例:

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

4.4.2 目录操作(COS::COSDir)

4.4.2.1 获取目录属性

ruby # 目录名称 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)

ruby 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

返回:

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

示例:

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

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

参数:

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

返回:

ruby COS::COSDir

示例:

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

4.4.2.4 上传文件至当前目录(upload)

ruby 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会自动使用分片断点续传上传大文件。

返回:

ruby COS::COSFile

示例:

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

ruby 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会自动使用分片断点续传上传大文件。

返回:

ruby Array<COS::COSFile>

示例:

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

4.4.2.6 批量下载当前目录下的所有文件(download_all)

ruby 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会自动使用分片断点续传下载大文件。

返回:

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

示例:

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

4.4.2.7 当前目录属性(刷新)(stat)

ruby dir.stat

返回:

ruby COS::COSDir

示例:

ruby puts dir.stat.to_hash

4.4.2.8 更新当前目录属性(upadte)

ruby dir.update(biz_attr)

参数:

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

示例:

ruby dir.update('new biz attr')

4.4.2.9 删除当前目录(delete)

ruby dir.delete

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

示例:

ruby dir.delete

4.4.2.10 删除当前目录(无异常)(delete!)

ruby dir.delete!

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

返回:

ruby Boolean

示例:

ruby puts dir.delete!

4.4.2.11 判断当前目录是否为空(empty?)

ruby dir.empty?

返回:

ruby Boolean

示例:

ruby puts dir.empty?

4.4.2.12 判断当前目录是否存在(exist?,exists?)

ruby dir.exist? # 别名 exists?

返回:

ruby Boolean

示例:

ruby puts dir.exist?

4.4.2.13 获取当前目录下的Object树形结构(tree)

ruby 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 => [...]}, ... ] }

示例:

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

4.4.2.14 获取当前目录下的Hash树形结构(hash_tree)

ruby dir.hash_tree(options = {})

参数:

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

返回:

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

示例:

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

ruby dir.list_count(options = {})

参数:

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

返回:

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

示例:

ruby puts dir.list_count[:files]

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

ruby dir.count # 别名 size

返回:

ruby Integer # 目录及文件总数

示例:

ruby puts dir.count

4.4.2.17 获取当前目录下的文件个数(count_files)

ruby dir.count_files

返回:

ruby Integer # 文件总数

示例:

ruby puts dir.count_files

4.4.2.18 获取当前目录下的子目录个数(count_dirs)

ruby dir.count_dirs

返回:

ruby Integer # 目录总数

示例:

ruby puts dir.count_dirs

4.5 签名操作(COS::Signature)

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

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

4.5.1 获取单次有效签名(once)

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

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

4.5.2 获取多次有效签名(multiple)

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

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

5 底层API(COS::API)

5.1 创建目录(create_folder)

ruby @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 创建的资源路径

示例:

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

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

ruby @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(当类型为文件时返回)

示例:

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

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

ruby @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 资源路径

示例:

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

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

ruby @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 资源路径

示例:

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

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

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

参数:

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

返回:无

示例:

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

5.6 删除文件、目录(delete)

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

参数:

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

返回:无

示例:

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

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

ruby @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(当类型为文件时返回)

示例:

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

5.8下载文件

ruby @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

示例:

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

6 CLI命令行工具

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

获取CLI指令列表:

``` shell $ 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 ```

获取指令的详细参数如:

``` shell $ 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)

shell $ cos init

使用CLI:

shell $ cos upload path/path2 file1 ~/file1

7 运行测试

rspec

bundle exec rake spec