qcloud_cos 0.1.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/.rubocop.yml +37 -0
- data/.travis.yml +4 -1
- data/Gemfile +1 -0
- data/README.md +79 -46
- data/Rakefile +15 -5
- data/bin/console +12 -3
- data/lib/qcloud_cos.rb +63 -2
- data/lib/qcloud_cos/api.rb +365 -0
- data/lib/qcloud_cos/authorization.rb +65 -0
- data/lib/qcloud_cos/configuration.rb +9 -0
- data/lib/qcloud_cos/convenient_api.rb +107 -0
- data/lib/qcloud_cos/error.rb +49 -0
- data/lib/qcloud_cos/http.rb +81 -0
- data/lib/qcloud_cos/model/file_object.rb +16 -0
- data/lib/qcloud_cos/model/folder_object.rb +35 -0
- data/lib/qcloud_cos/model/list.rb +34 -0
- data/lib/qcloud_cos/model/objectable.rb +9 -0
- data/lib/qcloud_cos/utils.rb +47 -0
- data/lib/qcloud_cos/version.rb +1 -1
- data/qcloud_cos.gemspec +19 -11
- data/wiki/get_started.md +761 -0
- metadata +122 -11
data/lib/qcloud_cos/version.rb
CHANGED
data/qcloud_cos.gemspec
CHANGED
@@ -4,21 +4,29 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
|
|
4
4
|
require 'qcloud_cos/version'
|
5
5
|
|
6
6
|
Gem::Specification.new do |spec|
|
7
|
-
spec.name =
|
7
|
+
spec.name = 'qcloud_cos'
|
8
8
|
spec.version = QcloudCos::VERSION
|
9
|
-
spec.authors = [
|
10
|
-
spec.email = [
|
9
|
+
spec.authors = ['Newell Zhu']
|
10
|
+
spec.email = ['zlx.star@gmail.com']
|
11
11
|
|
12
|
-
spec.summary =
|
13
|
-
spec.description =
|
14
|
-
spec.homepage =
|
12
|
+
spec.summary = 'Ruby SDK For QCloud COS, Enjoy it!'
|
13
|
+
spec.description = 'Ruby SDK For QCloud COS, Enjoy it!'
|
14
|
+
spec.homepage = 'https://github.com/tencentyun'
|
15
15
|
|
16
16
|
spec.files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
|
17
|
-
spec.bindir =
|
17
|
+
spec.bindir = 'exe'
|
18
18
|
spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
|
19
|
-
spec.require_paths = [
|
19
|
+
spec.require_paths = ['lib']
|
20
20
|
|
21
|
-
spec.
|
22
|
-
spec.
|
23
|
-
spec.
|
21
|
+
spec.add_dependency 'httparty'
|
22
|
+
spec.add_dependency 'httmultiparty'
|
23
|
+
spec.add_dependency 'addressable'
|
24
|
+
|
25
|
+
spec.add_development_dependency 'bundler'
|
26
|
+
spec.add_development_dependency 'rake'
|
27
|
+
spec.add_development_dependency 'minitest'
|
28
|
+
spec.add_development_dependency 'mocha'
|
29
|
+
spec.add_development_dependency 'webmock'
|
30
|
+
spec.add_development_dependency 'timecop'
|
31
|
+
spec.add_development_dependency 'rubocop'
|
24
32
|
end
|
data/wiki/get_started.md
ADDED
@@ -0,0 +1,761 @@
|
|
1
|
+
## 目录
|
2
|
+
|
3
|
+
1. [开发准备](#开发准备)
|
4
|
+
1. [前期准备](#前期准备)
|
5
|
+
2. [获取 SDK](#获取sdk)
|
6
|
+
3. [Https 支持](#https支持)
|
7
|
+
2. [API详细说明](#api详细说明)
|
8
|
+
1. [生成签名](#生成签名)
|
9
|
+
2. [Bucket 操作](#bucket-操作)
|
10
|
+
1. [查看 Bucket 信息](#查看-bucket-信息 )
|
11
|
+
2. [目录操作](#目录操作)
|
12
|
+
1. [创建目录 (create, create_folder)](#创建目录)
|
13
|
+
2. [更新目录属性 (update)](#更新属性)
|
14
|
+
3. [查询目录信息 (stat)](#目录或者文件查询)
|
15
|
+
4. [列出目录 (list, list_folders)](#列举目录下文件或目录)
|
16
|
+
5. [文件夹搜索 (list)](#列举目录下文件或目录)
|
17
|
+
6. [删除目录 (delete, delete_folder)](#删除文件或目录)
|
18
|
+
7. [检查目录是否存在 (exists?, exist?)](#判断目录或者文件是否存在)
|
19
|
+
8. [查看目录下文件夹数量 (count)](#查看文件和文件夹数目)
|
20
|
+
9. [检查目录是否为空 (empty?)](#判断目录是否为空)
|
21
|
+
10. [检查目录下是否有文件夹 (contains_folder?)](#判断目录是否为空)
|
22
|
+
3. [文件操作](#文件操作)
|
23
|
+
1. [上传文件 (create, upload)](#文件上传)
|
24
|
+
2. [分片上传文件,支持断点续传 (upload_slice)](#文件分片上传)
|
25
|
+
3. [更新文件属性 (update)](#更新属性)
|
26
|
+
4. [查询文件信息 (stat)](#目录或者文件查询)
|
27
|
+
5. [列出文件 (list, list_files)](#列举目录下文件或目录)
|
28
|
+
6. [删除文件 (delete, delete_file)](#删除文件或目录)
|
29
|
+
7. [获取文件外网访问地址 (public_url)](#获取文件外网访问地址)
|
30
|
+
8. [文件搜索 (list)](#列举目录下文件或目录)
|
31
|
+
9. [检查文件是否存在 (exists?, exist?)](#判断目录或者文件是否存在)
|
32
|
+
10. [查看目录下文件数量 (count)](#查看文件和文件夹数目)
|
33
|
+
11. [检查目录下是否有文件 (contains_folder?)](#判断目录是否为空)
|
34
|
+
3. [其它资源](#其它资源)
|
35
|
+
|
36
|
+
|
37
|
+
## 开发准备
|
38
|
+
|
39
|
+
1. 对象存储服务的 Ruby SDK 的 官方地址:https://github.com/tencentyun/cos-ruby-sdk
|
40
|
+
2. 项目名: tencentyun/cos-ruby-sdk
|
41
|
+
|
42
|
+
### 前期准备
|
43
|
+
|
44
|
+
1. sdk 支持 Ruby 1.9.3 及以上。
|
45
|
+
2. 获取项目ID(appid),bucket,secret_id和secret_key;
|
46
|
+
|
47
|
+
### 获取SDK
|
48
|
+
|
49
|
+
把这行代码加到你的 Gemfile:
|
50
|
+
|
51
|
+
gem 'qcloud_cos'
|
52
|
+
|
53
|
+
然后执行:
|
54
|
+
|
55
|
+
$ bundle
|
56
|
+
|
57
|
+
或者自己安装:
|
58
|
+
|
59
|
+
$ gem install qcloud_cos
|
60
|
+
|
61
|
+
然后配置你的环境:
|
62
|
+
|
63
|
+
```ruby
|
64
|
+
QcloudCos.configure do |config|
|
65
|
+
config.app_id = 'app-id'
|
66
|
+
config.secret_id = 'secret_id'
|
67
|
+
config.secret_key = 'secret_key'
|
68
|
+
config.endpoint = "http://web.file.myqcloud.com/files/v1/"
|
69
|
+
config.bucket = "default-bucket-name"
|
70
|
+
end
|
71
|
+
```
|
72
|
+
|
73
|
+
### https支持
|
74
|
+
|
75
|
+
需要支持 https, 有两种方式:
|
76
|
+
|
77
|
+
|
78
|
+
1. 配置 endpoint 为 https 地址(比如: https://web.file.myqcloud.com/files/v1/ )即可。这时候会加密客户端请求,但是服务端会无条件信任证书
|
79
|
+
|
80
|
+
2. 配置 endpoint 为 https 地址(比如: https://web.file.myqcloud.com/files/v1/ ),并配置 ssl_ca_file, 这样服务端会验证你的证书,保证你的通信安全并且合法
|
81
|
+
|
82
|
+
```ruby
|
83
|
+
QcloudCos.config do |config|
|
84
|
+
config.ssl_ca_file = 'path/to/ca/file'
|
85
|
+
end
|
86
|
+
```
|
87
|
+
|
88
|
+
## API详细说明
|
89
|
+
|
90
|
+
### 生成签名
|
91
|
+
|
92
|
+
1. 接口说明
|
93
|
+
|
94
|
+
签名生成方法,可以在服务端生成签名,供移动端app使用。
|
95
|
+
|
96
|
+
签名分为2种:
|
97
|
+
多次有效签名(有一定的有效时间)
|
98
|
+
单次有效签名(绑定资源url,只能生效一次)
|
99
|
+
签名的详细描述及使用场景参见 [鉴权技术服务方案](http://www.qcloud.com/wiki/%E9%89%B4%E6%9D%83%E6%8A%80%E6%9C%AF%E6%9C%8D%E5%8A%A1%E6%96%B9%E6%A1%88)
|
100
|
+
|
101
|
+
2. 方法
|
102
|
+
|
103
|
+
多次有效签名
|
104
|
+
|
105
|
+
```ruby
|
106
|
+
Authorization#sign(bucket, expired)
|
107
|
+
```
|
108
|
+
|
109
|
+
单次有效签名
|
110
|
+
|
111
|
+
```ruby
|
112
|
+
Authorization#sign_once(bucket, fileid)
|
113
|
+
```
|
114
|
+
|
115
|
+
3. 参数和返回值
|
116
|
+
|
117
|
+
参数说明:
|
118
|
+
|
119
|
+
|
120
|
+
| 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
|
121
|
+
| ----- | ----- | ---- | ----- | ------ |
|
122
|
+
|expired |long |否 |无 |有效时长, 以当前时间计算过期时间|
|
123
|
+
|bucket |String |是 |无 |bucket名称,bucket创建参见创建Bucket|
|
124
|
+
|fileid |String |是 |无 |文件路径,以斜杠开头,例如 /filepath/filename,为文件在此bucketname下的全路径|
|
125
|
+
|
126
|
+
|
127
|
+
返回值:签名字符串
|
128
|
+
|
129
|
+
示例代码:
|
130
|
+
|
131
|
+
```ruby
|
132
|
+
expired = 600
|
133
|
+
authorization = QcloudCos::Authorization.new(QcloudCos.config)
|
134
|
+
authorization.sign(bucket, expired) # 生成一个10分钟有效的多次有效签名
|
135
|
+
fileid = "/myFloder/myFile.rar"
|
136
|
+
authorization.sign_once(bucket, fileid) # 生成一个绑定文件的单次有效签名
|
137
|
+
```
|
138
|
+
|
139
|
+
### Bucket 操作
|
140
|
+
|
141
|
+
#### 查看 Bucket 信息
|
142
|
+
|
143
|
+
1. 接口说明
|
144
|
+
|
145
|
+
查看 Bucket 配置信息
|
146
|
+
|
147
|
+
2. 方法
|
148
|
+
|
149
|
+
```ruby
|
150
|
+
QcloudCos.bucket_info(bucket_name = config.bucket)
|
151
|
+
```
|
152
|
+
|
153
|
+
3. 参数和返回值
|
154
|
+
|
155
|
+
参数说明:
|
156
|
+
|
157
|
+
|
158
|
+
|参数名|类型 |必须 |默认值 |参数描述|
|
159
|
+
|-----|-----|----|------|------|
|
160
|
+
| bucket_name |String|是 |配置里面的默认 Bucket | Bucket 名字|
|
161
|
+
|
162
|
+
|
163
|
+
返回值, Hash
|
164
|
+
|
165
|
+
如果指定的 Bucket 不存在,则返回 `{}`
|
166
|
+
|
167
|
+
| 属性 | 类型 | 描述 |
|
168
|
+
| --------------------- | ------------- | -------------------------------------- |
|
169
|
+
| authority | String | eWPrivateRPublic私有写公共读,eWPrivate私有写私有读 |
|
170
|
+
| bucket_type | Integer | bucket_type |
|
171
|
+
| migrate_source_domain | String | 回源地址 |
|
172
|
+
| need_preview | String | need_preview |
|
173
|
+
| refers | Array<String> | refers |
|
174
|
+
| blackrefers | Array<String> | blackrefers |
|
175
|
+
| cnames | Array<String> | cnames |
|
176
|
+
| nugc_flag | String | nugc_flag |
|
177
|
+
|
178
|
+
|
179
|
+
示例代码:
|
180
|
+
|
181
|
+
```ruby
|
182
|
+
QcloudCos.bucket_info #=> { authority: '', ... }
|
183
|
+
QcloudCos.bucket_info('other-bucket') # => {}
|
184
|
+
```
|
185
|
+
|
186
|
+
### 目录操作
|
187
|
+
|
188
|
+
#### 创建目录
|
189
|
+
|
190
|
+
1. 接口说明
|
191
|
+
|
192
|
+
用于目录的创建,调用者可以通过此接口在指定bucket下创建目录。
|
193
|
+
|
194
|
+
2. 方法
|
195
|
+
|
196
|
+
```ruby
|
197
|
+
QcloudCos.create_folder(path, options = {})
|
198
|
+
```
|
199
|
+
|
200
|
+
3. 参数和返回值
|
201
|
+
|
202
|
+
***文件夹名称限制:***
|
203
|
+
|
204
|
+
> 文件夹名请保持在 20 个字符以内,同时注意不支持保留符号和保留字段。
|
205
|
+
>
|
206
|
+
> 保留符号不可以使用,例如:'/' , '?' , '*' , ':' , '|' , '\' , '<' , '>' , '"'。
|
207
|
+
>
|
208
|
+
> 保留字段不可以直接使用,可以包含使用,例如:'con' , 'aux' , 'nul' , 'prn' , 'com0' , 'com1' , 'com2' , 'com3' , 'com4' , 'com5' , 'com6' , 'com7' , 'com8' , 'com9' , 'lpt0' , 'lpt1' , 'lpt2' , 'lpt3' , 'lpt4' , 'lpt5' , 'lpt6' , 'lpt7' , 'lpt8' , 'lpt9',但 'con1' 或 'aux1' 这样的名字可以使用。
|
209
|
+
|
210
|
+
对不符合要求的文件夹路径会抛出 InvalidFolderPathError 异常。
|
211
|
+
|
212
|
+
参数说明:
|
213
|
+
|
214
|
+
|参数名|类型|必须|默认值|参数描述|
|
215
|
+
|-----|---|----|-----|------|
|
216
|
+
|path| String| 是| 无| 需要创建目录的全路径,API 会自动补齐"/"开头, 缺失 / 结尾,会抛出异常 InvalidFolderPathError|
|
217
|
+
|options| Hash| 否 |{}| 支持 bucket 和 biz_attr(目录绑定的属性信息,业务自行维护)|
|
218
|
+
|
219
|
+
返回值, Hash:
|
220
|
+
|
221
|
+
|参数名|类型 |参数描述|
|
222
|
+
|-----|----|-------|
|
223
|
+
|code| Int| 错误码,成功时为0|
|
224
|
+
|message| String| 错误信息|
|
225
|
+
|data| Hash| 返回数据|
|
226
|
+
|data['ctime']| String| 目录的创建时间,unix时间戳|
|
227
|
+
|data['resource_path'] |String| 目录的资源路径|
|
228
|
+
|
229
|
+
API 请求错误,则抛出 RequestError 异常
|
230
|
+
|
231
|
+
|参数名 |类型 |参数描述|
|
232
|
+
|------|----|-------|
|
233
|
+
|code| Int| API 错误码|
|
234
|
+
|message| String| 错误信息|
|
235
|
+
|original_response| Response| 原始返回结果|
|
236
|
+
|
237
|
+
|
238
|
+
示例代码:
|
239
|
+
|
240
|
+
```ruby
|
241
|
+
path = "/myFolder/"
|
242
|
+
biz_attr = "attr_folder"
|
243
|
+
result = QcloudCos.create_folder(path, biz_attr: biz_attr)
|
244
|
+
```
|
245
|
+
|
246
|
+
|
247
|
+
#### 更新属性
|
248
|
+
|
249
|
+
1. 接口说明
|
250
|
+
|
251
|
+
用于目录业务自定义属性的更新,调用者可以通过此接口更新业务的自定义属性字段。
|
252
|
+
|
253
|
+
2. 方法
|
254
|
+
|
255
|
+
```ruby
|
256
|
+
QcloudCos.update(path, biz_attr, options = {})
|
257
|
+
```
|
258
|
+
|
259
|
+
3. 参数和返回值
|
260
|
+
|
261
|
+
参数说明:
|
262
|
+
|
263
|
+
|参数名 |类型 |必须 |默认值 |参数描述|
|
264
|
+
|------|----|-----|------|------|
|
265
|
+
|path| String| 是 |无 |需要创建目录的全路径,以"/"开头,api会补齐|
|
266
|
+
|biz_attr| String| 是 |无 |新的目录绑定的属性信息|
|
267
|
+
|options| Hash| 否 |{}| 支持 bucket, 默认使用配置的 bucket |
|
268
|
+
|
269
|
+
|
270
|
+
返回值, Hash:
|
271
|
+
|
272
|
+
|参数名 |类型 |参数描述|
|
273
|
+
|------|----|-------|
|
274
|
+
|code| Int| 错误码,成功时为0|
|
275
|
+
|message| String| 错误信息|
|
276
|
+
|
277
|
+
API 请求错误,则抛出 RequestError 异常
|
278
|
+
|
279
|
+
|参数名 |类型 |参数描述|
|
280
|
+
|------|----|-------|
|
281
|
+
|code| Int| API 错误码|
|
282
|
+
|message| String| 错误信息|
|
283
|
+
|original_response| Response| 原始返回结果|
|
284
|
+
|
285
|
+
|
286
|
+
示例代码:
|
287
|
+
|
288
|
+
```ruby
|
289
|
+
path = "/myFolder/";
|
290
|
+
biz_attr = "attr_folder_new";
|
291
|
+
result = QcloudCos.update(path, biz_attr)
|
292
|
+
```
|
293
|
+
|
294
|
+
|
295
|
+
#### 目录或者文件查询
|
296
|
+
|
297
|
+
1. 接口说明
|
298
|
+
|
299
|
+
用于目录属性的查询,调用者可以通过此接口查询目录的属性。
|
300
|
+
|
301
|
+
2. 方法
|
302
|
+
|
303
|
+
```ruby
|
304
|
+
QcloudCos.stat(path, options = {})
|
305
|
+
```
|
306
|
+
|
307
|
+
3. 参数和返回值
|
308
|
+
|
309
|
+
参数说明:
|
310
|
+
|
311
|
+
|
312
|
+
|参数名 |类型 |必须 |默认值 |参数描述|
|
313
|
+
|------|----|-----|------|------|
|
314
|
+
|path| String| 是 |无 |需要创建目录的全路径,以"/"开头,api会补齐|
|
315
|
+
|options| Hash| 否 |{}| 支持 bucket, 默认使用配置的 bucket |
|
316
|
+
|
317
|
+
|
318
|
+
返回值, Hash:
|
319
|
+
|
320
|
+
|参数名 |类型 |参数描述|
|
321
|
+
|------|----|-------|
|
322
|
+
|code| Int| 错误码,成功时为0|
|
323
|
+
|message| String| 错误信息|
|
324
|
+
|data['biz_attr'] |String |目录绑定的属性信息,业务自行维护|
|
325
|
+
|data['ctime'] |String |目录或者文件的创建时间,unix时间戳|
|
326
|
+
|data['mtime'] |String |目录或者文件的修改时间,unix时间戳|
|
327
|
+
|data['name'] |String |目录或者文件的名称|
|
328
|
+
|data['filesize'] |Integer |文件的大小,当类型为文件时有|
|
329
|
+
|data['sha'] |String |文件的Sha,当类型为文件时有|
|
330
|
+
|data['access_url'] |String |文件的可访问的url,当类型为文件时有|
|
331
|
+
|
332
|
+
|
333
|
+
API 请求错误,则抛出 RequestError 异常
|
334
|
+
|
335
|
+
|参数名 |类型 |参数描述|
|
336
|
+
|------|----|-------|
|
337
|
+
|code| Int| API 错误码|
|
338
|
+
|message| String| 错误信息|
|
339
|
+
|original_response| Response| 原始返回结果|
|
340
|
+
|
341
|
+
|
342
|
+
示例代码:
|
343
|
+
|
344
|
+
```ruby
|
345
|
+
path = "/myFolder/";
|
346
|
+
result = QcloudCos.stat(path)
|
347
|
+
```
|
348
|
+
|
349
|
+
#### 删除文件或目录
|
350
|
+
|
351
|
+
1. 接口说明
|
352
|
+
|
353
|
+
用于目录的删除,调用者可以通过此接口删除空目录,如果目录中存在有效文件或目录,将不能删除。
|
354
|
+
|
355
|
+
2. 方法
|
356
|
+
|
357
|
+
```ruby
|
358
|
+
QcloudCos.delete(path, options = {}) # 删除文件或者目录
|
359
|
+
QcloudCos.delete_file(path, options = {}) # 删除文件
|
360
|
+
QcloudCos.delete_folder(path, options = {}) # 删除目录
|
361
|
+
```
|
362
|
+
|
363
|
+
3. 参数和返回值
|
364
|
+
|
365
|
+
参数说明:
|
366
|
+
|
367
|
+
|参数名 |类型 |必须 |默认值 |参数描述|
|
368
|
+
|------|----|-----|------|------|
|
369
|
+
|path| String| 是 |无 |需要创建目录的全路径,以"/"开头,api会补齐|
|
370
|
+
|options| Hash| 否 |{}| 支持 bucket, 默认使用配置的 bucket |
|
371
|
+
|recursive| Boolean| 否 |false| 级联删除, 删除目录下所有内容, 仅 delete_folder 方法支持 |
|
372
|
+
|
373
|
+
|
374
|
+
返回值, Hash:
|
375
|
+
|
376
|
+
|参数名 |类型 |参数描述|
|
377
|
+
|------|----|-------|
|
378
|
+
|code| Int| 错误码,成功时为0|
|
379
|
+
|message| String| 错误信息|
|
380
|
+
|
381
|
+
API 请求错误,则抛出 RequestError 异常
|
382
|
+
|
383
|
+
|
384
|
+
|参数名 |类型 |参数描述|
|
385
|
+
|------|----|-------|
|
386
|
+
|code| Int| API 错误码|
|
387
|
+
|message| String| 错误信息|
|
388
|
+
|original_response| Response| 原始返回结果|
|
389
|
+
|
390
|
+
|
391
|
+
示例代码:
|
392
|
+
|
393
|
+
```ruby
|
394
|
+
path = "/myFolder/"
|
395
|
+
result = QcloudCos.delete(path)
|
396
|
+
|
397
|
+
path = "/myNotEmptyFolder/"
|
398
|
+
result = QcloudCos.delete_folder(path) # 错误: 目录非空
|
399
|
+
result = QcloudCos.delete_folder(path, recursive: true) # 成功
|
400
|
+
```
|
401
|
+
|
402
|
+
#### 列举目录下文件或目录
|
403
|
+
|
404
|
+
1. 接口说明
|
405
|
+
|
406
|
+
用于列举目录下文件和目录,调用者可以通过此接口查询目录下的文件和目录属性。
|
407
|
+
|
408
|
+
2. 方法
|
409
|
+
|
410
|
+
```ruby
|
411
|
+
QcloudCos.list(path, options = {}) # 列出文件或者目录
|
412
|
+
QcloudCos.list_folders(path, options = {}) # 列出目录
|
413
|
+
QcloudCos.list_files(path, options = {}) # 列出文件
|
414
|
+
QcloudCos.list(path, options = {}) # path 不为 / 结尾,则为搜索该前缀的文件或者目录
|
415
|
+
```
|
416
|
+
|
417
|
+
3. 参数和返回值
|
418
|
+
|
419
|
+
参数说明:
|
420
|
+
|
421
|
+
|参数名 |类型 |必须 |默认值 |参数描述|
|
422
|
+
|------|----|-----|------|------|
|
423
|
+
|path| String| 是 |'/'| 目录的全路径,以"/"开头,api会补齐|
|
424
|
+
|options| Hash| 否 | {} | 额外参数|
|
425
|
+
|options['num'] |int |否 |100 |要查询的目录/文件数量|
|
426
|
+
|options['context']| String| 否| null| 透传字段,查看第一页,则传空字符串。若需要翻页,需要将前一页返回值中的context透传到参数中。order用于指定翻页顺序。若order填0,则从当前页正序/往下翻页;若order填1,则从当前页倒序/往上翻页|
|
427
|
+
|options['order'] |int| 否| 0| 默认正序(=0), 填1为反序|
|
428
|
+
|options['pattern'] |String |否 |eListBoth| eListBoth,eListDirOnly,eListFileOnly 默认eListBoth|
|
429
|
+
|
430
|
+
返回值, List 对象:
|
431
|
+
|
432
|
+
|属性 |类型 |必然返回 |描述 |
|
433
|
+
|----|-----|-------|-----|
|
434
|
+
|has_more |Boolean| 是 |是否有内容可以继续往前/往后翻页|
|
435
|
+
|context |String |是| 透传字段,查看第一页,则传空字符串。若需要翻页,需要将前一页返回值中的context透传到参数中。order用于指定翻页顺序。若order填0,则从当前页正序/往下翻页;若order填1,则从当前页倒序/往上翻页|
|
436
|
+
|dircount |String |是| 子目录数量(总)|
|
437
|
+
|filecount] |String |是 |子文件数量(总)|
|
438
|
+
|objects | Hash| 是 | FileObject 和 FolderObject 集合|
|
439
|
+
|
440
|
+
FileObject 对象
|
441
|
+
|
442
|
+
|属性 |类型 |必然返回 |描述 |
|
443
|
+
|----|-----|-------|-----|
|
444
|
+
|name|String| 是 |文件名字|
|
445
|
+
|biz_attr |String| 是 |文件属性,业务端维护|
|
446
|
+
|ctime |String| 是 |文件的创建时间,unix时间戳|
|
447
|
+
|mtime |String| 是 |文件的修改时间,unix时间戳|
|
448
|
+
|filesize |Int| 否 |文件大小|
|
449
|
+
|filelen |Int| 否 |文件已传输大小(通过与filesize对比可知文件传输进度)|
|
450
|
+
|sha |String| 否 |文件sha|
|
451
|
+
|access_url| String |否 |生成的文件下载url|
|
452
|
+
|
453
|
+
FolderObject 对象
|
454
|
+
|
455
|
+
|
456
|
+
|属性 |类型 |必然返回 |描述|
|
457
|
+
|----|-----|-------|----|
|
458
|
+
|name|String| 是 |目录名字|
|
459
|
+
|biz_attr |String| 是 |目录属性,业务端维护|
|
460
|
+
|ctime |String| 是 |目录的创建时间,unix时间戳|
|
461
|
+
|mtime |String| 是 |目录的修改时间,unix时间戳|
|
462
|
+
|
463
|
+
|
464
|
+
API 请求错误,则抛出 RequestError 异常
|
465
|
+
|
466
|
+
|
467
|
+
|参数名 |类型 |参数描述|
|
468
|
+
|------|----|-------|
|
469
|
+
|code| Int| API 错误码|
|
470
|
+
|message| String| 错误信息|
|
471
|
+
|original_response| Response| 原始返回结果|
|
472
|
+
|
473
|
+
|
474
|
+
示例代码:
|
475
|
+
|
476
|
+
```ruby
|
477
|
+
path = "/myFolder/"
|
478
|
+
result = QcloudCos.list(path, num: 20)
|
479
|
+
prefix= "/myFolder/2015-";
|
480
|
+
result = QcloudCos.list(prefix, num: 20)
|
481
|
+
```
|
482
|
+
|
483
|
+
|
484
|
+
|
485
|
+
### 文件操作
|
486
|
+
|
487
|
+
#### 文件上传
|
488
|
+
|
489
|
+
1. 接口说明
|
490
|
+
|
491
|
+
用于较小文件(一般小于8MB)的上传,调用者可以通过此接口上传较小的文件并获得文件的url,较大的文件请使用分片上传接口。
|
492
|
+
|
493
|
+
2. 方法
|
494
|
+
|
495
|
+
```ruby
|
496
|
+
QcloudCos.upload(path, file_or_bin, options = {})
|
497
|
+
```
|
498
|
+
|
499
|
+
3. 参数和返回值
|
500
|
+
|
501
|
+
参数说明:
|
502
|
+
|
503
|
+
|
504
|
+
|参数名 |类型 |必须 |默认值 |参数描述|
|
505
|
+
|------|----|-----|------|------|
|
506
|
+
|path |String|是 |无 |文件在COS服务端的全路径,不包括/appid/bucketname|
|
507
|
+
|file_or_bin| IO 或者 Binary| 否 | 无|一个IO对象或者文件内容 |
|
508
|
+
| options | Hash | 否 | 无 | 额外参数, 支持 bucket, 默认使用配置的 bucket |
|
509
|
+
| options['biz_attr'] | String| 否 | 无 | 文件属性,业务端自己维护 |
|
510
|
+
|
511
|
+
|
512
|
+
返回值, Hash:
|
513
|
+
|
514
|
+
|
515
|
+
|参数名 |类型 |必然返回 |参数描述 |
|
516
|
+
|------|----|--------|--------|
|
517
|
+
|code| Int| 是 |错误码,成功时为0|
|
518
|
+
|message| String| 是|错误信息|
|
519
|
+
|data| Hash|是|返回数据|
|
520
|
+
|data['access_url'] | String| 是 |生成的文件下载url|
|
521
|
+
|data['url']| String |是 |操作文件的url|
|
522
|
+
|data['resource_path'] |String| 是 |资源路径. 格式:/appid/bucket/xxx|
|
523
|
+
|
524
|
+
API 请求错误,则抛出 RequestError 异常
|
525
|
+
|
526
|
+
|
527
|
+
|参数名 |类型 |参数描述|
|
528
|
+
|------|----|-------|
|
529
|
+
|code| Int| API 错误码|
|
530
|
+
|message| String| 错误信息|
|
531
|
+
|original_response| Response| 原始返回结果|
|
532
|
+
|
533
|
+
|
534
|
+
示例代码:
|
535
|
+
|
536
|
+
```ruby
|
537
|
+
file = File.new("/data/test.log")
|
538
|
+
path = "/myFolder/test.log";
|
539
|
+
result = QcloudCos.upload(path, file, biz_attr: 'attr')
|
540
|
+
```
|
541
|
+
|
542
|
+
#### 文件分片上传
|
543
|
+
|
544
|
+
1. 接口说明
|
545
|
+
|
546
|
+
用于较大文件(一般大于8MB)的上传,调用者可以通过此接口上传较大文件并获得文件的url和唯一标识resource_path(用于调用其他api)。
|
547
|
+
|
548
|
+
2. 方法
|
549
|
+
|
550
|
+
```ruby
|
551
|
+
QcloudCos.upload_slice(dst_path, src_path, options = {})
|
552
|
+
```
|
553
|
+
|
554
|
+
3. 参数和返回值
|
555
|
+
|
556
|
+
参数说明:
|
557
|
+
|
558
|
+
|
559
|
+
|参数名|类型 |必须 |默认值 |参数描述|
|
560
|
+
|-----|----|-----|------|-------|
|
561
|
+
| dst_path | String|是 |无 |文件在COS服务端的全路径,不包括/appid/bucketname|
|
562
|
+
| src_path | String |是 |无 |本地要上传文件的全路径|
|
563
|
+
| options | Hash | 否 | 无 | 额外参数
|
564
|
+
| options['bucket'] | String| 否 | 配置的默认 bucket | Bucket 名称|
|
565
|
+
| options['biz_attr'] | String| 否 | 无 | 文件属性,业务端自己维护 |
|
566
|
+
| options['slice_size'] |Integer |否 | 3M|分片大小,用户可以根据网络状况自行设置|
|
567
|
+
| options['session'] |String |否 |null |如果是断点续传, 则带上(唯一标识此文件传输过程的id, 由后台下发, 调用方透传)|
|
568
|
+
|
569
|
+
|
570
|
+
返回值, Hash:
|
571
|
+
|
572
|
+
|
573
|
+
|参数名 |类型 |必然返回 |参数描述 |
|
574
|
+
|------|----|--------|--------|
|
575
|
+
|code |Integer |是 |错误码,成功时为0|
|
576
|
+
|message |String |是 |错误信息|
|
577
|
+
|data |Array |是 |返回数据|
|
578
|
+
|data['access_url'] | String| 是 |生成的文件下载url|
|
579
|
+
|data['url'] |String |是 |操作文件的url|
|
580
|
+
|data['resource_path'] |String |是 |资源路径. 格式:/appid/bucket/xxx|
|
581
|
+
|
582
|
+
API 请求错误,则抛出 RequestError 异常
|
583
|
+
|
584
|
+
|
585
|
+
|参数名 |类型 |参数描述 |
|
586
|
+
|------|----|--------|
|
587
|
+
|code | Int| API 错误码|
|
588
|
+
|message | String| 错误信息|
|
589
|
+
|original_response | Response | 原始返回结果|
|
590
|
+
|
591
|
+
示例代码:
|
592
|
+
|
593
|
+
```ruby
|
594
|
+
src_path= "/data/test.mp4"
|
595
|
+
dst_path = "/myFolder/test.mp4"
|
596
|
+
result = QcloudCos.upload_slice(dst_path, src_path)
|
597
|
+
```
|
598
|
+
|
599
|
+
#### 查看文件和文件夹数目
|
600
|
+
|
601
|
+
1. 接口说明
|
602
|
+
|
603
|
+
查看某路径下文件或者文件夹数目
|
604
|
+
|
605
|
+
2. 方法
|
606
|
+
|
607
|
+
```ruby
|
608
|
+
QcloudCos.count(path, options = {})
|
609
|
+
```
|
610
|
+
|
611
|
+
3. 参数和返回值
|
612
|
+
|
613
|
+
参数说明:
|
614
|
+
|
615
|
+
|
616
|
+
|参数名|类型 |必须 |默认值 |参数描述|
|
617
|
+
|-----|-----|----|------|------|
|
618
|
+
| path |String|是 |无 |文件在COS服务端的全路径,不包括/appid/bucketname|
|
619
|
+
| options | Hash | 否 | 无 | 额外参数
|
620
|
+
| options['bucket'] | String| 否 | 配置的默认 bucket | Bucket 名称|
|
621
|
+
|
622
|
+
|
623
|
+
返回值, Hash
|
624
|
+
|
625
|
+
|参数名 |类型 |参数描述|
|
626
|
+
|------|-----|------|
|
627
|
+
|file_count | Integer | 文件数目 |
|
628
|
+
|folder_count | Integer | 文件夹数目 |
|
629
|
+
|
630
|
+
|
631
|
+
示例代码:
|
632
|
+
|
633
|
+
```ruby
|
634
|
+
QcloudCos.public_url("/myFolder/") #=> { file_count: 10, folder_count: 100 }
|
635
|
+
```
|
636
|
+
|
637
|
+
#### 判断目录或者文件是否存在
|
638
|
+
|
639
|
+
1. 接口说明
|
640
|
+
|
641
|
+
判断目录或者文件是否存在
|
642
|
+
|
643
|
+
2. 方法
|
644
|
+
|
645
|
+
```ruby
|
646
|
+
QcloudCos.exists?(path, options = {})
|
647
|
+
QcloudCos.exist?(path, options = {})
|
648
|
+
```
|
649
|
+
|
650
|
+
3. 参数和返回值
|
651
|
+
|
652
|
+
参数说明:
|
653
|
+
|
654
|
+
|
655
|
+
|参数名|类型 |必须 |默认值 |参数描述|
|
656
|
+
|-----|-----|----|------|------|
|
657
|
+
| path |String|是 |无 |文件在COS服务端的全路径,不包括/appid/bucketname|
|
658
|
+
| options | Hash | 否 | 无 | 额外参数
|
659
|
+
| options['bucket'] | String| 否 | 配置的默认 bucket | Bucket 名称|
|
660
|
+
|
661
|
+
|
662
|
+
返回值, Boolean
|
663
|
+
|
664
|
+
文件或者目录存在则返回 true,反之 false
|
665
|
+
|
666
|
+
|
667
|
+
示例代码:
|
668
|
+
|
669
|
+
```ruby
|
670
|
+
QcloudCos.exists?("/myFolder/") #=> true
|
671
|
+
QcloudCos.exist?("/myFolder/") #=> true
|
672
|
+
```
|
673
|
+
|
674
|
+
|
675
|
+
#### 判断目录是否为空
|
676
|
+
|
677
|
+
1. 接口说明
|
678
|
+
|
679
|
+
判断目录是否为空,或者是否含有文件或者文件夹
|
680
|
+
|
681
|
+
2. 方法
|
682
|
+
|
683
|
+
```ruby
|
684
|
+
QcloudCos.empty?(path, options = {})
|
685
|
+
QcloudCos.contains_file?(path, options = {})
|
686
|
+
QcloudCos.contains_folder?(path, options = {})
|
687
|
+
```
|
688
|
+
|
689
|
+
3. 参数和返回值
|
690
|
+
|
691
|
+
参数说明:
|
692
|
+
|
693
|
+
|
694
|
+
|参数名|类型 |必须 |默认值 |参数描述|
|
695
|
+
|-----|-----|----|------|------|
|
696
|
+
| path |String|是 |无 |文件在COS服务端的全路径,不包括/appid/bucketname|
|
697
|
+
| options | Hash | 否 | 无 | 额外参数
|
698
|
+
| options['bucket'] | String| 否 | 配置的默认 bucket | Bucket 名称|
|
699
|
+
|
700
|
+
|
701
|
+
返回值, Boolean
|
702
|
+
|
703
|
+
+ empty? 该路径下面没有文件和文件夹则返回 true , 反之 false
|
704
|
+
+ contains_file? 该路径下面有文件则返回 true , 反之 false
|
705
|
+
+ contails_folder? 该路径下面有文件夹则返回 true , 反之 false
|
706
|
+
|
707
|
+
|
708
|
+
示例代码:
|
709
|
+
|
710
|
+
```ruby
|
711
|
+
QcloudCos.empty?("/myFolder/") #=> false
|
712
|
+
QcloudCos.contains_file?("/myFolder/") #=> true
|
713
|
+
QcloudCos.contains_folder?("/myFolder/") #=> false
|
714
|
+
```
|
715
|
+
|
716
|
+
#### 获取文件外网访问地址
|
717
|
+
|
718
|
+
1. 接口说明
|
719
|
+
|
720
|
+
有防盗链情况下获取文件的外网访问地址,自动完成签名
|
721
|
+
|
722
|
+
2. 方法
|
723
|
+
|
724
|
+
```ruby
|
725
|
+
QcloudCos.public_url(path, options = {})
|
726
|
+
```
|
727
|
+
|
728
|
+
3. 参数和返回值
|
729
|
+
|
730
|
+
参数说明:
|
731
|
+
|
732
|
+
|
733
|
+
|参数名|类型 |必须 |默认值 |参数描述|
|
734
|
+
|-----|-----|----|------|------|
|
735
|
+
|path |String|是 |无 |文件在COS服务端的全路径,不包括/appid/bucketname|
|
736
|
+
| options | Hash | 否 | 无 | 额外参数
|
737
|
+
| options['bucket'] | String| 否 | 配置的默认 bucket | Bucket 名称|
|
738
|
+
|
739
|
+
|
740
|
+
返回值, 带签名的外网可访问地址
|
741
|
+
|
742
|
+
API 请求错误,则抛出 RequestError 异常
|
743
|
+
|
744
|
+
|
745
|
+
|参数名 |类型 |参数描述|
|
746
|
+
|------|-----|------|
|
747
|
+
|code| Int| API 错误码|
|
748
|
+
|message| String| 错误信息|
|
749
|
+
|original_response| Response| 原始返回结果|
|
750
|
+
|
751
|
+
示例代码:
|
752
|
+
|
753
|
+
```ruby
|
754
|
+
path = "/myFolder/test.mp4"
|
755
|
+
result = QcloudCos.public_url(path)
|
756
|
+
```
|
757
|
+
|
758
|
+
## 其它资源
|
759
|
+
|
760
|
+
+ [RDoc 文档](http://www.rubydoc.info/gems/qcloud_cos/0.1.0)
|
761
|
+
+ [腾讯 COS 详细文档](http://www.qcloud.com/doc/product/227/%E4%BA%A7%E5%93%81%E4%BB%8B%E7%BB%8D)
|