Module: QcloudCos::Api

Included in:
QcloudCos
Defined in:
lib/qcloud_cos/api.rb

Instance Method Summary collapse

Instance Method Details

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

创建目录

Parameters:

  • path (String) —

    指定要创建的文件夹名字，支持级联创建

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

    options

Options Hash (options):

  • :bucket (String) — default: config.bucket_name —

    指定当前 bucket, 默认是配置里面的 bucket

  • :biz_attr (Integer) —

    指定目录的 biz_attr 由业务端维护, 会在文件信息中返回

Returns:

  • (Hash) 


73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
 
# File 'lib/qcloud_cos/api.rb', line 73

def create_folder(path, options = {})
  path = fixed_path(path)
  bucket = validates(path, options, :folder_only)

  url = generate_rest_url(bucket, path)

  query = { 'op' => 'create' }.merge(Utils.hash_slice(options, 'biz_attr'))

  headers = {
    'Authorization' => authorization.sign(bucket),
    'Content-Type' => 'application/json'
  }

  http.post(url, body: query.to_json, headers: headers).parsed_response
end

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

删除文件或者目录

Parameters:

  • path (String) —

    指定文件或者目录路径

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

    额外参数

Options Hash (options):

  • :bucket (String) — default: config.bucket_name —

    指定当前 bucket, 默认是配置里面的 bucket

Returns:

  • (Hash) 


223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
 
# File 'lib/qcloud_cos/api.rb', line 223

def delete(path, options = {})
  path = fixed_path(path)
  bucket = validates(path, options, 'both')
  url = generate_rest_url(bucket, path)

  query = { 'op' => 'delete' }

  resource = "/#{bucket}#{Utils.url_encode(path)}"
  headers = {
    'Authorization' => authorization.sign_once(bucket, resource),
    'Content-Type' => 'application/json'
  }

  http.post(url, body: query.to_json, headers: headers).parsed_response
end

#delete_file(path, options = {}) ⇒ Hash

删除文件

Parameters:

  • path (String) —

    指定文件路径

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

    额外参数

Options Hash (options):

  • :bucket (String) — default: config.bucket_name —

    指定当前 bucket, 默认是配置里面的 bucket

Returns:

  • (Hash)

Raises:



273
274
275
276
 
# File 'lib/qcloud_cos/api.rb', line 273

def delete_file(path, options = {})
  fail InvalidFilePathError if path.end_with?('/')
  delete(path, options)
end

#delete_folder(path, options = {}) ⇒ Hash

删除目录

Parameters:

  • path (String) —

    指定目录路径

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

    额外参数

Options Hash (options):

  • :bucket (String) — default: config.bucket_name —

    指定当前 bucket, 默认是配置里面的 bucket

  • :recursive (Boolean) — default: false —

    指定是否需要级连删除

Returns:

  • (Hash)

Raises:



249
250
251
252
253
254
255
256
257
258
259
260
261
262
 
# File 'lib/qcloud_cos/api.rb', line 249

def delete_folder(path, options = {})
  validates(path, options, 'folder_only')

  return delete(path, options) if options['recursive'] != true

  all(path, options).each do |object|
    if object.is_a?(QcloudCos::FolderObject)
      delete_folder("#{path}#{object.name}/", options)
    elsif object.is_a?(QcloudCos::FileObject)
      delete_file("#{path}#{object.name}", options)
    end
  end
  delete(path)
end

#init_slice_upload(path, filesize, sha, options = {}) ⇒ Hash

初始化分片上传

Parameters:

  • path (String) —

    指定上传文件的路径

  • filesize (Integer) —

    指定文件总大小

  • sha (String) —

    指定该文件的 sha 值

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

    options

Options Hash (options):

  • :bucket (String) — default: config.bucket_name —

    指定当前 bucket, 默认是配置里面的 bucket

  • :biz_attr (Integer) —

    指定文件的 biz_attr 由业务端维护, 会在文件信息中返回

  • :session (Integer) —

    如果想要断点续传,则带上上一次的session

  • :slice_size (Integer) —

    指定分片大小

Returns:

  • (Hash) 


160
161
162
163
164
165
166
167
168
169
 
# File 'lib/qcloud_cos/api.rb', line 160

def init_slice_upload(path, filesize, sha, options = {})
  path = fixed_path(path)
  bucket = validates(path, options)

  url = generate_rest_url(bucket, path)
  query = generate_slice_upload_query(filesize, sha, options)
  sign = options['sign'] || authorization.sign(bucket)

  http.post(url, query: query, headers: { 'Authorization' => sign }).parsed_response
end

#list(path = '/', options = {}) ⇒ Hash

列出文件或者目录

Parameters:

  • path (String) (defaults to: '/') —

    指定目标路径, 以 / 结尾, 则列出该目录下文件或者文件夹，不以 / 结尾，就搜索该前缀的文件或者文件夹

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

    额外参数

Options Hash (options):

  • :bucket (String) — default: config.bucket_name —

    指定当前 bucket, 默认是配置里面的 bucket

  • :num (Integer) — default: 100 —

    指定需要拉取的条目, 可选范围: 1~199

  • :pattern (String) — default: eListBoth —

    指定拉取的内容，可选值: eListBoth, eListDirOnly, eListFileOnly

  • :order (Integer) — default: 0 —

    指定拉取文件的顺序, 默认为正序(=0), 可选值: 0, 1

  • :context (String) — default: "" —

    透传字段，查看第一页，则传空字符串。若需要翻页，需要将前一页返回值中的context透传到参数中。order用于指定翻页顺序。若order填0，则从当前页正序/往下翻页；若order填1，则从当前页倒序/往上翻页。

Returns:

  • (Hash) 


19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
 
# File 'lib/qcloud_cos/api.rb', line 19

def list(path = '/', options = {})
  path = fixed_path(path)
  bucket = validates(path, options, 'both')

  query = {
    'op' => 'list',
    'num' => 100
  }.merge(Utils.hash_slice(options, 'num', 'pattern', 'order', 'context'))

  url = generate_rest_url(bucket, path)
  sign = authorization.sign(bucket)

  result = http.get(url, query: query, headers: { 'Authorization' => sign }).parsed_response
  QcloudCos::List.new(result['data'])
end

#list_files(path = '/', options = {}) ⇒ Hash

列出所有文件

Parameters:

  • path (String) (defaults to: '/') —

    指定目标路径, 以 / 结尾, 则列出该目录下文件，不以 / 结尾，就搜索该前缀的文件

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

    额外参数

Options Hash (options):

  • :bucket (String) — default: config.bucket_name —

    指定当前 bucket, 默认是配置里面的 bucket

  • :num (Integer) — default: 100 —

    指定需要拉取的条目

  • :order (Integer) — default: 0 —

    指定拉取文件的顺序, 默认为正序(=0), 可选值: 0, 1

  • :context (String) — default: "" —

    透传字段，查看第一页，则传空字符串。若需要翻页，需要将前一页返回值中的context透传到参数中。order用于指定翻页顺序。若order填0，则从当前页正序/往下翻页；若order填1，则从当前页倒序/往上翻页。

Returns:

  • (Hash) 


45
46
47
48
 
# File 'lib/qcloud_cos/api.rb', line 45

def list_files(path = '/', options = {})
  Utils.stringify_keys!(options)
  list(path, options.merge('pattern' => 'eListFileOnly'))
end

#list_folders(path = '/', options = {}) ⇒ Hash

列出所有目录

Parameters:

  • path (String) (defaults to: '/') —

    指定目标路径, 以 / 结尾, 则列出该目录下文件夹，不以 / 结尾，就搜索该前缀的文件夹

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

    额外参数

Options Hash (options):

  • :bucket (String) — default: config.bucket_name —

    指定当前 bucket, 默认是配置里面的 bucket

  • :num (Integer) — default: 100 —

    指定需要拉取的条目

  • :order (Integer) — default: 0 —

    指定拉取文件的顺序, 默认为正序(=0), 可选值: 0, 1

  • :context (String) — default: "" —

    透传字段，查看第一页，则传空字符串。若需要翻页，需要将前一页返回值中的context透传到参数中。order用于指定翻页顺序。若order填0，则从当前页正序/往下翻页；若order填1，则从当前页倒序/往上翻页。

Returns:

  • (Hash) 


60
61
62
63
 
# File 'lib/qcloud_cos/api.rb', line 60

def list_folders(path = '/', options = {})
  Utils.stringify_keys!(options)
  list(path, options.merge('pattern' => 'eListDirOnly'))
end

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

查看文件或者文件夹信息

Parameters:

  • path (String) —

    指定文件或者文件夹目录

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

    额外参数

Options Hash (options):

  • :bucket (String) — default: config.bucket_name —

    指定当前 bucket, 默认是配置里面的 bucket

Returns:

  • (Hash) 


285
286
287
288
289
290
291
292
293
294
 
# File 'lib/qcloud_cos/api.rb', line 285

def stat(path, options = {})
  path = fixed_path(path)
  bucket = validates(path, options, 'both')
  url = generate_rest_url(bucket, path)

  query = { 'op' => 'stat' }
  sign = authorization.sign(bucket)

  http.get(url, query: query, headers: { 'Authorization' => sign }).parsed_response
end

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

更新文件或者目录信息

Parameters:

  • path (String) —

    指定文件或者目录路径

  • biz_attr (String) —

    指定文件或者目录的 biz_attr

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

    额外参数

Options Hash (options):

  • :bucket (String) — default: config.bucket_name —

    指定当前 bucket, 默认是配置里面的 bucket

Returns:

  • (Hash) 


200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
 
# File 'lib/qcloud_cos/api.rb', line 200

def update(path, biz_attr, options = {})
  path = fixed_path(path)
  bucket = validates(path, options, 'both')
  url = generate_rest_url(bucket, path)

  query = { 'op' => 'update', 'biz_attr' => biz_attr }

  resource = "/#{bucket}#{Utils.url_encode(path)}"
  headers = {
    'Authorization' => authorization.sign_once(bucket, resource),
    'Content-Type' => 'application/json'
  }

  http.post(url, body: query.to_json, headers: headers).parsed_response
end

#upload(path, file_or_bin, options = {}) ⇒ Hash Also known as: create

上传文件

Parameters:

  • path (String) —

    指定上传文件的路径

  • file_or_bin (File||String) —

    指定文件或者文件内容

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

    options

Options Hash (options):

  • :bucket (String) — default: config.bucket_name —

    指定当前 bucket, 默认是配置里面的 bucket

  • :biz_attr (Integer) —

    指定文件的 biz_attr 由业务端维护, 会在文件信息中返回

Returns:

  • (Hash) 


98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/qcloud_cos/api.rb', line 98

def upload(path, file_or_bin, options = {})
  path = fixed_path(path)
  bucket = validates(path, options)

  url = generate_rest_url(bucket, path)

  query = {
    'op' => 'upload'
  }.merge(Utils.hash_slice(options, 'biz_attr')).merge(generate_file_query(file_or_bin))

  http.post(url, query: query, headers: { 'Authorization' => authorization.sign(bucket) }).parsed_response
end

#upload_part(path, session, offset, content, options = {}) ⇒ Hash

上传分片数据

Parameters:

  • path (String) —

    指定上传文件的路径

  • session (String) —

    指定分片上传的 session id

  • offset (Integer) —

    本次分片位移

  • content (Binary) —

    指定文件内容

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

    options

Options Hash (options):

  • :bucket (String) — default: config.bucket_name —

    指定当前 bucket, 默认是配置里面的 bucket

Returns:

  • (Hash) 


181
182
183
184
185
186
187
188
189
190
 
# File 'lib/qcloud_cos/api.rb', line 181

def upload_part(path, session, offset, content, options = {})
  path = fixed_path(path)
  bucket = validates(path, options)

  url = generate_rest_url(bucket, path)
  query = generate_upload_part_query(session, offset, content)
  sign = options['sign'] || authorization.sign(bucket)

  http.post(url, query: query, headers: { 'Authorization' => sign }).parsed_response
end

#upload_slice(dst_path, src_path, options = {}, &block) ⇒ Hash

分片上传

Examples:


upload_slice('/data/test.log', 'test.log') do |pr|
  puts "uploaded #{pr * 100}%"
end

Parameters:

  • dst_path (String) —

    指定文件的目标路径

  • src_path (String) —

    指定文件的本地路径

  • block (Block) —

    指定 Block 来显示进度提示

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

    options

Options Hash (options):

  • :bucket (String) — default: config.bucket_name —

    指定当前 bucket, 默认是配置里面的 bucket

  • :biz_attr (Integer) —

    指定文件的 biz_attr 由业务端维护, 会在文件信息中返回

  • :session (Integer) —

    指定本次分片上传的 session

  • :slice_size (Integer) —

    指定分片大小

Returns:

  • (Hash)

Raises:



134
135
136
137
138
139
140
141
142
143
144
145
146
 
# File 'lib/qcloud_cos/api.rb', line 134

def upload_slice(dst_path, src_path, options = {}, &block)
  dst_path = fixed_path(dst_path)
  fail FileNotExistError unless File.exist?(src_path)
  bucket = validates(dst_path, options)

  multipart = QcloudCos::Multipart.new(
    dst_path,
    src_path,
    options.merge(bucket: bucket, authorization: authorization)
  )
  multipart.upload(&block)
  multipart.result
end