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) 


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

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) 


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

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:



304
305
306
307
 
# File 'lib/qcloud_cos/api.rb', line 304

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:



275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
 
# File 'lib/qcloud_cos/api.rb', line 275

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

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

  loop do
    objects = list(path, options)
    objects.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
    break unless objects.has_more
    options['context'] = objects.context
  end
  delete(path)
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 —

    指定需要拉取的条目

  • :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) 


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

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) 


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

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) 


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

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) 


316
317
318
319
320
321
322
323
324
325
 
# File 'lib/qcloud_cos/api.rb', line 316

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) 


226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
 
# File 'lib/qcloud_cos/api.rb', line 226

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) 


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

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_slice(dst_path, src_path, options = {}) ⇒ Hash

分片上传

Parameters:

  • dst_path (String) —

    指定文件的目标路径

  • src_path (String) —

    指定文件的本地路径

  • 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:



126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/qcloud_cos/api.rb', line 126

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

  filesize = File.size(src_path)
  sha = Utils.generate_file_sha(src_path)
  sign = authorization.sign(bucket)

  resp = init_slice_upload(dst_path, filesize, sha, options.merge('sign' => sign))
  puts "init slice upload: #{resp}"

  data = resp['data']
  return data if data.key?('url') # 妙传命中

  slice_size = data['slice_size'] || DEFAULT_SLICE_SIZE
  session = data['session'] || options['session']
  offset = data['offset'] || 0

  fail MissingSessionIdError unless session

  while offset < filesize
    filecontent = IO.read(src_path, slice_size, offset)

    retry_times = 0
    begin
      result = upload_part(dst_path, session, offset, filecontent, options)
      puts "upload part data: #{result}"

      if result.key?('data') && result['data'].key?('session')
        session = result['data']['session']
      elsif result.key?('data') && result['data'].key?('url')
        return result['data']
      end
    rescue => e
      retry_times += 1
      puts "retry part upload request with offset:#{offset}, slice_size:#{slice_size} ..."
      retry if retry_times <= config.max_retry_times
      raise e
    end
    offset += slice_size
  end
end