Skip to content

RaymondChou/cos-ruby-sdk

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

73 Commits

bin

bin

 
 

example

example

 
 

lib

lib

 
 

spec

spec

 
 

test

test

 
 

.gitignore

.gitignore

 
 

.rspec

.rspec

 
 

.travis.yml

.travis.yml

 
 

Gemfile

Gemfile

 
 

LICENSE

LICENSE

 
 

README.md

README.md

 
 

Rakefile

Rakefile

 
 

cos.gemspec

cos.gemspec

 
 

Repository files navigation

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 => 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

About

Tencent COS(Cloud Object Service) Ruby SDK

Resources

Readme

License

Apache-2.0 license
Activity

Stars

17 stars

Watchers

3 watching

Forks

6 forks
Report repository

Releases

1 tags

Packages

No packages published

Languages