Class: COS::API

Inherits:
Object
  • Object
show all
Defined in:
lib/cos/api.rb

Overview

腾讯云对象存储服务RestfulAPI

See Also:

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(config) ⇒ API

初始化

Examples:

COS::API.new(config)

Parameters:

See Also:



22
23
24
25
 
# File 'lib/cos/api.rb', line 22

def initialize(config)
  @config = config
  @http   = COS::HTTP.new(config)
end

Instance Attribute Details

#config ⇒ Object (readonly)

Returns the value of attribute config.



12
13
14
 
# File 'lib/cos/api.rb', line 12

def config
  @config
end

#http ⇒ Object (readonly)

Returns the value of attribute http.



12
13
14
 
# File 'lib/cos/api.rb', line 12

def http
  @http
end

Instance Method Details

#create_folder(path, options = {}) ⇒ Object

创建目录

Parameters:

  • path (String) —

    目录路径, 如: ‘path1’, ‘path1/path2’, sdk会补齐末尾的 ‘/’

  • options (Hash) (defaults to: {}) —

    高级参数

Options Hash (options):

  • :biz_attr (String) —

    目录属性, 业务端维护

  • :bucket (String) —

    bucket名称

Returns:

  • Hash

    • :ctime [String] 创建时间Unix时间戳

    • :resource_path [String] 创建的资源路径

Raises:

See Also:



41
42
43
44
45
46
47
48
49
 
# File 'lib/cos/api.rb', line 41

def create_folder(path, options = {})
  bucket  = config.get_bucket(options[:bucket])
  sign    = http.signature.multiple(bucket)
  payload = {op: 'create', biz_attr: options[:biz_attr]}
  resource_path = Util.get_resource_path(config.app_id, bucket, path)

  http.post(resource_path, {}, sign, payload.to_json)
      .merge({name: resource_path.split('/').at(-1)})
end

#delete(path, options = {}) ⇒ Object

删除文件及目录

Parameters:

  • path (String) —

    资源路径, 如: 目录‘path1/’, 文件‘path1/file’

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket (String) —

    bucket名称

Raises:

See Also:



248
249
250
251
252
253
254
255
 
# File 'lib/cos/api.rb', line 248

def delete(path, options = {})
  bucket        = config.get_bucket(options[:bucket])
  resource_path = Util.get_resource_path_or_file(config.app_id, bucket, path)
  sign          = http.signature.once(bucket, path)
  payload       = {op: 'delete'}

  http.post(resource_path, {}, sign, payload.to_json)
end

#download(access_url, file_store, options = {}) ⇒ Object

Note:

SDK会自动对私有读的Bucket进行签名

下载文件

Parameters:

  • access_url (String) —

    资源的下载URL地址可以从list,stat接口中获取

  • file_store (String) —

    本地文件存储路径

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket (String) —

    bucket名称

  • :headers (Hash) —

    设置下载请求头,如:range

Raises:



268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
 
# File 'lib/cos/api.rb', line 268

def download(access_url, file_store, options = {})
  bucket = config.get_bucket(options[:bucket])
  sign   = http.signature.multiple(bucket)

  response = RestClient::Request.execute(
      :method  => 'GET',
      :url     => "#{access_url}?sign=#{sign}",
      :headers => options[:headers]
  )

  if response.code < 300
    File.open(file_store, 'wb') do |w|
      w.write(response.body)
    end
  else
    raise DownloadError, "server response http code: #{response.code}"
  end
end

#list(path, options = {}) ⇒ Object

目录列表/前缀搜索

Parameters:

  • path (String) —

    目录路径, 如: ‘/’, ‘path1’, ‘path1/path2’, sdk会补齐末尾的 ‘/’

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket (String) —

    bucket名称

  • :prefix (String) —

    搜索前缀 如果填写prefix, 则列出含此前缀的所有文件及目录

  • :num (Integer) —

    每页拉取的数量, 默认20条

  • :pattern (Symbol) —

    获取方式 :dir_only 只获取目录, :file_only 只获取文件, 默认为 :both 全部获取

  • :order (Symbol) —

    排序方式 :asc 正序, :desc 倒序 默认为 :asc

  • :context (String) —

    页码 若需要翻页，需要将前一页返回值中的context透传到参数中 若order为:asc，则从当前页正序/往下翻页；若order为:desc，则从当前页倒序/往上翻

Returns:

  • Hash

    • :context [String] 透传字段,用于翻页,需要往前/往后翻页则透传回来

    • :has_more [Boolean] 是否有内容可以继续往前/往后翻页

    • :dircount [Integer] 子目录数量(总)

    • :filecount [Integer] 子文件数量(总)

    • :infos [Array<Hash>] 列表结果(可能为空)

      • :name [String] 目录名/文件名

      • :biz_attr [String] 目录/文件属性，业务端维护

      • :filesize [Integer] 文件大小(当类型为文件时返回)

      • :filelen [Integer] 文件已传输大小(通过与filesize对比可知文件传输进度,当类型为文件时返回)

      • :sha [String] 文件sha1(当类型为文件时返回)

      • :ctime [String] 创建时间(Unix时间戳)

      • :mtime [String] 修改时间(Unix时间戳)

      • :access_url [String] 生成的资源可访问的url(当类型为文件时返回)

Raises:

See Also:



167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
 
# File 'lib/cos/api.rb', line 167

def list(path, options = {})
  bucket  = config.get_bucket(options[:bucket])
  sign    = http.signature.multiple(bucket)
  resource_path = Util.get_resource_path(config.app_id, bucket, path, options[:prefix])

  pattern = case options[:pattern].to_s.to_sym
              when :dir_only
                'eListDirOnly'
              when :file_only
                'eListFileOnly'
              else
                'eListBoth'
            end

  query = {
      op:       'list',
      num:      options[:num] || 20,
      pattern:  pattern,
      order:    options[:order].to_s.to_sym == :desc ? 1 : 0,
      context:  options[:context]
  }

  http.get(resource_path, {params: query}, sign)
end

#stat(path, options = {}) ⇒ Object

目录/文件信息查询

Parameters:

  • path (String) —

    资源路径, 如: 目录‘path1/’, 文件‘path1/file’

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket (String) —

    bucket名称

Returns:

  • Hash

    • :name [String] 目录名/文件名

    • :biz_attr [String] 目录/文件属性，业务端维护

    • :filesize [Integer] 文件大小(当类型为文件时返回)

    • :filelen [Integer] 文件已传输大小(通过与filesize对比可知文件传输进度,当类型为文件时返回)

    • :sha [String] 文件sha1(当类型为文件时返回)

    • :ctime [String] 创建时间(Unix时间戳)

    • :mtime [String] 修改时间(Unix时间戳)

    • :access_url [String] 生成的资源可访问的url(当类型为文件时返回)

Raises:

See Also:



231
232
233
234
235
236
237
 
# File 'lib/cos/api.rb', line 231

def stat(path, options = {})
  bucket        = config.get_bucket(options[:bucket])
  sign          = http.signature.multiple(bucket)
  resource_path = Util.get_resource_path_or_file(config.app_id, bucket, path)

  http.get(resource_path, {params: {op: 'stat'}}, sign)
end

#update(path, biz_attr, options = {}) ⇒ Object

更新目录/文件信息(biz_attr)

Parameters:

  • path (String) —

    资源路径, 如: 目录‘path1/’, 文件‘path1/file’

  • biz_attr (String) —

    目录/文件属性，业务端维护

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bucket (String) —

    bucket名称

Raises:

See Also:



203
204
205
206
207
208
209
210
 
# File 'lib/cos/api.rb', line 203

def update(path, biz_attr, options = {})
  bucket        = config.get_bucket(options[:bucket])
  resource_path = Util.get_resource_path_or_file(config.app_id, bucket, path)
  sign          = http.signature.once(bucket, path)
  payload       = {op: 'update', biz_attr: biz_attr}

  http.post(resource_path, {}, sign, payload.to_json)
end

#upload(path, file_name, file_src, options = {}) ⇒ Object

上传文件(完整上传)

Parameters:

  • path (String) —

    目录路径, 如: ‘/’, ‘path1’, ‘path1/path2’, sdk会补齐末尾的 ‘/’

  • file_name (String) —

    文件名

  • file_src (String) —

    本地文件路径

  • options (Hash) (defaults to: {}) —

    高级参数

Options Hash (options):

  • :biz_attr (String) —

    目录属性, 业务端维护

  • :bucket (String) —

    bucket名称

Returns:

  • Hash

    • :access_url [String] 生成的文件下载url

    • :url [String] 操作文件的url

    • :resource_path [String] 资源路径

Raises:

See Also:



68
69
70
71
72
73
74
75
76
77
78
79
80
81
 
# File 'lib/cos/api.rb', line 68

def upload(path, file_name, file_src, options = {})
  bucket        = config.get_bucket(options[:bucket])
  sign          = http.signature.multiple(bucket)
  resource_path = Util.get_resource_path(config.app_id, bucket, path, file_name)

  payload = {
      op:            'upload',
      sha:           Util.file_sha1(file_src),
      filecontent:   File.new(file_src, 'rb'),
      biz_attr:      options[:biz_attr]
  }

  http.post(resource_path, {}, sign, payload)
end

#upload_slice(path, file_name, file_src, options = {}) {|Float| ... } ⇒ Object

上传文件(分片上传)

Parameters:

  • path (String) —

    目录路径, 如: ‘/’, ‘path1’, ‘path1/path2’, sdk会补齐末尾的 ‘/’

  • file_name (String) —

    文件名

  • file_src (String) —

    本地文件路径

  • options (Hash) (defaults to: {}) —

    高级参数

Options Hash (options):

  • :biz_attr (String) —

    目录属性, 业务端维护

  • :bucket (String) —

    bucket名称

  • :disable_cpt (Boolean) —

    是否禁用checkpoint功能，如 果设置为true，则在上传的过程中不会写checkpoint文件，这意味着 上传失败后不能断点续传，而只能重新上传整个文件。如果这个值为 true，则:cpt_file会被忽略。

  • :threads (Integer) —

    多线程上传线程数, 默认为10

  • :slice_size (Integer) —

    设置分片上传时每个分片的大小 默认为3 MB, 目前服务端最大限制也为3MB。

  • :cpt_file (String) —

    断点续传的checkpoint文件，如果 指定的cpt文件不存在，则会在file所在目录创建一个默认的cpt文件， 命名方式为：file.cpt，其中file是用户要下载的文件名。在下载的过 程中会不断更新此文件，成功完成下载后会删除此文件；如果指定的 cpt文件已存在，则从cpt文件中记录的点继续下载。

Yields:

  • (Float) —

    上传进度百分比回调, 进度值是一个0-1之间的小数

Returns:

  • Hash

    • :access_url [String] 生成的文件下载url

    • :url [String] 操作文件的url

    • :resource_path [String] 资源路径

Raises:

See Also:



115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/cos/api.rb', line 115

def upload_slice(path, file_name, file_src, options = {}, &block)
  slice = Slice.new(
      config:    config,
      http:      http,
      path:      path,
      file_name: file_name,
      file_src:  file_src,
      options:   options,
      progress:  block
  ).upload

  {
      access_url:    slice[:access_url],
      url:           slice[:url],
      resource_path: slice[:resource_path]
  }
end