cos 0.1.0 → 0.1.1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (51) hide show
  1. checksums.yaml +4 -4
  2. data/.gitignore +12 -0
  3. data/.rspec +2 -0
  4. data/.travis.yml +13 -2
  5. data/Gemfile +4 -1
  6. data/LICENSE +191 -0
  7. data/README.md +2014 -17
  8. data/Rakefile +23 -6
  9. data/bin/cos +325 -0
  10. data/bin/setup +1 -3
  11. data/cos.gemspec +24 -13
  12. data/lib/cos.rb +41 -4
  13. data/lib/cos/api.rb +289 -0
  14. data/lib/cos/bucket.rb +731 -0
  15. data/lib/cos/checkpoint.rb +62 -0
  16. data/lib/cos/client.rb +58 -0
  17. data/lib/cos/config.rb +102 -0
  18. data/lib/cos/dir.rb +301 -0
  19. data/lib/cos/download.rb +252 -0
  20. data/lib/cos/exception.rb +62 -0
  21. data/lib/cos/file.rb +152 -0
  22. data/lib/cos/http.rb +95 -0
  23. data/lib/cos/logging.rb +47 -0
  24. data/lib/cos/resource.rb +201 -0
  25. data/lib/cos/signature.rb +119 -0
  26. data/lib/cos/slice.rb +292 -0
  27. data/lib/cos/struct.rb +49 -0
  28. data/lib/cos/tree.rb +165 -0
  29. data/lib/cos/util.rb +82 -0
  30. data/lib/cos/version.rb +2 -2
  31. data/spec/cos/bucket_spec.rb +562 -0
  32. data/spec/cos/client_spec.rb +77 -0
  33. data/spec/cos/dir_spec.rb +195 -0
  34. data/spec/cos/download_spec.rb +105 -0
  35. data/spec/cos/http_spec.rb +70 -0
  36. data/spec/cos/signature_spec.rb +83 -0
  37. data/spec/cos/slice_spec.rb +302 -0
  38. data/spec/cos/struct_spec.rb +38 -0
  39. data/spec/cos/tree_spec.rb +322 -0
  40. data/spec/cos/util_spec.rb +106 -0
  41. data/test/download_test.rb +44 -0
  42. data/test/list_test.rb +43 -0
  43. data/test/upload_test.rb +48 -0
  44. metadata +132 -21
  45. data/.idea/.name +0 -1
  46. data/.idea/cos.iml +0 -49
  47. data/.idea/encodings.xml +0 -6
  48. data/.idea/misc.xml +0 -14
  49. data/.idea/modules.xml +0 -8
  50. data/.idea/workspace.xml +0 -465
  51. data/bin/console +0 -14
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: df9a6fa79870d91c4a1a07b359167035111bde83
4
- data.tar.gz: 739349acefe5ae42ff7097d096ca056f66de475b
3
+ metadata.gz: 8dd5186b7dc60c10661854d62c9ce39d4b13b52b
4
+ data.tar.gz: 16ec04430868339b7ef0806167c2273a90b8ff31
5
5
  SHA512:
6
- metadata.gz: cdda13350455e45f20598a9daf5d89354a89cbfd7d2c254392e06f3a3e1aa46f31b827e89ee9f488d3c07b854b8684a146a7f5f7e82fc481be81e3211763c4d0
7
- data.tar.gz: aba7fb36c4dc670f921d625595aff93ed7735f4631ab9701790728800aafab639ed40d6c9a0ea6d5d36d1c9146c114d4bc80dffaa152efc49bc8abe1a7ff2116
6
+ metadata.gz: c0e1a7704fe2b84be3a4b1901e1426bd0a8806ec4da8a95727496ac11cc3e234c4460d2e962e146f70e90c7841696d50d489d18085d16461a8e08b9ee9683b33
7
+ data.tar.gz: c6ce091a53d60fdbf3408815b0df75c4f7bd4b2d4da95df40634a1a634fd2ef4b431e385ad16040386b977e2ed5f977386a81d9c53c93bece631f2e4ef12c909
data/.gitignore CHANGED
@@ -7,3 +7,15 @@
7
7
  /pkg/
8
8
  /spec/reports/
9
9
  /tmp/
10
+ *.gem
11
+ *.log
12
+
13
+ .idea
14
+ .DS_Store
15
+ Thumbs.db
16
+ .cache
17
+ .project
18
+ .settings
19
+ .tmproj
20
+ *.esproj
21
+ nbproject
data/.rspec ADDED
@@ -0,0 +1,2 @@
1
+ --color
2
+ --require spec_helper
data/.travis.yml CHANGED
@@ -1,4 +1,15 @@
1
1
  language: ruby
2
2
  rvm:
3
- - 2.2.3
4
- before_install: gem install bundler -v 1.11.2
3
+ - 1.9.3
4
+ - jruby-19mode
5
+ - 2.0
6
+ - 2.1
7
+ - 2.2
8
+ - 2.2.4
9
+ script:
10
+ bundle exec rake spec
11
+ before_install: gem install bundler
12
+
13
+ addons:
14
+ code_climate:
15
+ repo_token: 1f460aa92bd5cff641f3ab71dad000c3c102689d97e2b4df90cb90789161284a
data/Gemfile CHANGED
@@ -1,4 +1,7 @@
1
1
  source 'https://rubygems.org'
2
2
 
3
- # Specify your gem's dependencies in cos.gemspec
4
3
  gemspec
4
+
5
+ gem "codeclimate-test-reporter", group: :test, require: nil
6
+ # gem 'coveralls', group: :test, require: false
7
+ gem 'simplecov', group: :test, require: false
data/LICENSE ADDED
@@ -0,0 +1,191 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction, and
10
+ distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by the copyright
13
+ owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all other entities
16
+ that control, are controlled by, or are under common control with that entity.
17
+ For the purposes of this definition, "control" means (i) the power, direct or
18
+ indirect, to cause the direction or management of such entity, whether by
19
+ contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
20
+ outstanding shares, or (iii) beneficial ownership of such entity.
21
+
22
+ "You" (or "Your") shall mean an individual or Legal Entity exercising
23
+ permissions granted by this License.
24
+
25
+ "Source" form shall mean the preferred form for making modifications, including
26
+ but not limited to software source code, documentation source, and configuration
27
+ files.
28
+
29
+ "Object" form shall mean any form resulting from mechanical transformation or
30
+ translation of a Source form, including but not limited to compiled object code,
31
+ generated documentation, and conversions to other media types.
32
+
33
+ "Work" shall mean the work of authorship, whether in Source or Object form, made
34
+ available under the License, as indicated by a copyright notice that is included
35
+ in or attached to the work (an example is provided in the Appendix below).
36
+
37
+ "Derivative Works" shall mean any work, whether in Source or Object form, that
38
+ is based on (or derived from) the Work and for which the editorial revisions,
39
+ annotations, elaborations, or other modifications represent, as a whole, an
40
+ original work of authorship. For the purposes of this License, Derivative Works
41
+ shall not include works that remain separable from, or merely link (or bind by
42
+ name) to the interfaces of, the Work and Derivative Works thereof.
43
+
44
+ "Contribution" shall mean any work of authorship, including the original version
45
+ of the Work and any modifications or additions to that Work or Derivative Works
46
+ thereof, that is intentionally submitted to Licensor for inclusion in the Work
47
+ by the copyright owner or by an individual or Legal Entity authorized to submit
48
+ on behalf of the copyright owner. For the purposes of this definition,
49
+ "submitted" means any form of electronic, verbal, or written communication sent
50
+ to the Licensor or its representatives, including but not limited to
51
+ communication on electronic mailing lists, source code control systems, and
52
+ issue tracking systems that are managed by, or on behalf of, the Licensor for
53
+ the purpose of discussing and improving the Work, but excluding communication
54
+ that is conspicuously marked or otherwise designated in writing by the copyright
55
+ owner as "Not a Contribution."
56
+
57
+ "Contributor" shall mean Licensor and any individual or Legal Entity on behalf
58
+ of whom a Contribution has been received by Licensor and subsequently
59
+ incorporated within the Work.
60
+
61
+ 2. Grant of Copyright License.
62
+
63
+ Subject to the terms and conditions of this License, each Contributor hereby
64
+ grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
65
+ irrevocable copyright license to reproduce, prepare Derivative Works of,
66
+ publicly display, publicly perform, sublicense, and distribute the Work and such
67
+ Derivative Works in Source or Object form.
68
+
69
+ 3. Grant of Patent License.
70
+
71
+ Subject to the terms and conditions of this License, each Contributor hereby
72
+ grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
73
+ irrevocable (except as stated in this section) patent license to make, have
74
+ made, use, offer to sell, sell, import, and otherwise transfer the Work, where
75
+ such license applies only to those patent claims licensable by such Contributor
76
+ that are necessarily infringed by their Contribution(s) alone or by combination
77
+ of their Contribution(s) with the Work to which such Contribution(s) was
78
+ submitted. If You institute patent litigation against any entity (including a
79
+ cross-claim or counterclaim in a lawsuit) alleging that the Work or a
80
+ Contribution incorporated within the Work constitutes direct or contributory
81
+ patent infringement, then any patent licenses granted to You under this License
82
+ for that Work shall terminate as of the date such litigation is filed.
83
+
84
+ 4. Redistribution.
85
+
86
+ You may reproduce and distribute copies of the Work or Derivative Works thereof
87
+ in any medium, with or without modifications, and in Source or Object form,
88
+ provided that You meet the following conditions:
89
+
90
+ You must give any other recipients of the Work or Derivative Works a copy of
91
+ this License; and
92
+ You must cause any modified files to carry prominent notices stating that You
93
+ changed the files; and
94
+ You must retain, in the Source form of any Derivative Works that You distribute,
95
+ all copyright, patent, trademark, and attribution notices from the Source form
96
+ of the Work, excluding those notices that do not pertain to any part of the
97
+ Derivative Works; and
98
+ If the Work includes a "NOTICE" text file as part of its distribution, then any
99
+ Derivative Works that You distribute must include a readable copy of the
100
+ attribution notices contained within such NOTICE file, excluding those notices
101
+ that do not pertain to any part of the Derivative Works, in at least one of the
102
+ following places: within a NOTICE text file distributed as part of the
103
+ Derivative Works; within the Source form or documentation, if provided along
104
+ with the Derivative Works; or, within a display generated by the Derivative
105
+ Works, if and wherever such third-party notices normally appear. The contents of
106
+ the NOTICE file are for informational purposes only and do not modify the
107
+ License. You may add Your own attribution notices within Derivative Works that
108
+ You distribute, alongside or as an addendum to the NOTICE text from the Work,
109
+ provided that such additional attribution notices cannot be construed as
110
+ modifying the License.
111
+ You may add Your own copyright statement to Your modifications and may provide
112
+ additional or different license terms and conditions for use, reproduction, or
113
+ distribution of Your modifications, or for any such Derivative Works as a whole,
114
+ provided Your use, reproduction, and distribution of the Work otherwise complies
115
+ with the conditions stated in this License.
116
+
117
+ 5. Submission of Contributions.
118
+
119
+ Unless You explicitly state otherwise, any Contribution intentionally submitted
120
+ for inclusion in the Work by You to the Licensor shall be under the terms and
121
+ conditions of this License, without any additional terms or conditions.
122
+ Notwithstanding the above, nothing herein shall supersede or modify the terms of
123
+ any separate license agreement you may have executed with Licensor regarding
124
+ such Contributions.
125
+
126
+ 6. Trademarks.
127
+
128
+ This License does not grant permission to use the trade names, trademarks,
129
+ service marks, or product names of the Licensor, except as required for
130
+ reasonable and customary use in describing the origin of the Work and
131
+ reproducing the content of the NOTICE file.
132
+
133
+ 7. Disclaimer of Warranty.
134
+
135
+ Unless required by applicable law or agreed to in writing, Licensor provides the
136
+ Work (and each Contributor provides its Contributions) on an "AS IS" BASIS,
137
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied,
138
+ including, without limitation, any warranties or conditions of TITLE,
139
+ NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are
140
+ solely responsible for determining the appropriateness of using or
141
+ redistributing the Work and assume any risks associated with Your exercise of
142
+ permissions under this License.
143
+
144
+ 8. Limitation of Liability.
145
+
146
+ In no event and under no legal theory, whether in tort (including negligence),
147
+ contract, or otherwise, unless required by applicable law (such as deliberate
148
+ and grossly negligent acts) or agreed to in writing, shall any Contributor be
149
+ liable to You for damages, including any direct, indirect, special, incidental,
150
+ or consequential damages of any character arising as a result of this License or
151
+ out of the use or inability to use the Work (including but not limited to
152
+ damages for loss of goodwill, work stoppage, computer failure or malfunction, or
153
+ any and all other commercial damages or losses), even if such Contributor has
154
+ been advised of the possibility of such damages.
155
+
156
+ 9. Accepting Warranty or Additional Liability.
157
+
158
+ While redistributing the Work or Derivative Works thereof, You may choose to
159
+ offer, and charge a fee for, acceptance of support, warranty, indemnity, or
160
+ other liability obligations and/or rights consistent with this License. However,
161
+ in accepting such obligations, You may act only on Your own behalf and on Your
162
+ sole responsibility, not on behalf of any other Contributor, and only if You
163
+ agree to indemnify, defend, and hold each Contributor harmless for any liability
164
+ incurred by, or claims asserted against, such Contributor by reason of your
165
+ accepting any such warranty or additional liability.
166
+
167
+ END OF TERMS AND CONDITIONS
168
+
169
+ APPENDIX: How to apply the Apache License to your work
170
+
171
+ To apply the Apache License to your work, attach the following boilerplate
172
+ notice, with the fields enclosed by brackets "{}" replaced with your own
173
+ identifying information. (Don't include the brackets!) The text should be
174
+ enclosed in the appropriate comment syntax for the file format. We also
175
+ recommend that a file or class name and description of purpose be included on
176
+ the same "printed page" as the copyright notice for easier identification within
177
+ third-party archives.
178
+
179
+ Copyright 2016 RaymondChou zhouyt@outlook.com
180
+
181
+ Licensed under the Apache License, Version 2.0 (the "License");
182
+ you may not use this file except in compliance with the License.
183
+ You may obtain a copy of the License at
184
+
185
+ http://www.apache.org/licenses/LICENSE-2.0
186
+
187
+ Unless required by applicable law or agreed to in writing, software
188
+ distributed under the License is distributed on an "AS IS" BASIS,
189
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
190
+ See the License for the specific language governing permissions and
191
+ limitations under the License.
data/README.md CHANGED
@@ -1,36 +1,2033 @@
1
- # Cos
1
+ # Tencent COS Ruby SDK
2
2
 
3
- Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/cos`. To experiment with that code, run `bin/console` for an interactive prompt.
3
+ [![Gem Version](https://badge.fury.io/rb/cos.svg)](https://badge.fury.io/rb/cos) [![Dependency Status](https://gemnasium.com/bfcd58e8c449a47dcf4bd15e35806dc8.svg)](https://gemnasium.com/RaymondChou/cos-ruby-sdk) [![Code Climate](https://codeclimate.com/repos/5690d89cb1a7430e970051c5/badges/e1ec353330a7f9bb90a1/gpa.svg)](https://codeclimate.com/repos/5690d89cb1a7430e970051c5/feed) [![Build Status](https://travis-ci.com/RaymondChou/cos-ruby-sdk.svg?token=J7GcZgoty9nseAGRShu5&branch=master)](https://travis-ci.com/RaymondChou/cos-ruby-sdk) [![Test Coverage](https://codeclimate.com/repos/5690d89cb1a7430e970051c5/badges/e1ec353330a7f9bb90a1/coverage.svg)](https://codeclimate.com/repos/5690d89cb1a7430e970051c5/coverage)
4
4
 
5
- TODO: Delete this and the text above, and describe your gem
5
+ [![Gitter](https://badges.gitter.im/RaymondChou/cos-ruby-sdk.svg)](https://gitter.im/RaymondChou/cos-ruby-sdk?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) [![Gem Downloads](http://ruby-gem-downloads-badge.herokuapp.com/cos?type=total)](https://rubygems.org/gems/cos) [![Github Code](http://img.shields.io/badge/github-code-blue.svg)](https://github.com/RaymondChou/cos-ruby-sdk) [![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://rubydoc.info/github/RaymondChou/cos-ruby-sdk)
6
6
 
7
- ## Installation
8
7
 
9
- Add this line to your application's Gemfile:
10
8
 
11
- ```ruby
9
+ -----
10
+
11
+ Tencent🐧 COS(Cloud Object Service) SDK for Ruby [腾讯云对象存储服务](http://wiki.qcloud.com/wiki/COS%E4%BA%A7%E5%93%81%E4%BB%8B%E7%BB%8D)
12
+
13
+ - 100%实现COS官方Restful API
14
+
15
+ - 符合Ruby使用习惯的链式操作
16
+
17
+ - 支持HTTPS
18
+
19
+ - 支持大文件自动多线程分片断点续传上传、下载
20
+
21
+ - 支持Rails
22
+
23
+ - 提供便捷的CLI工具:
24
+
25
+ ![CLI示例](http://mytest-10016219.file.myqcloud.com/out2.gif)
26
+
27
+ **目录**
28
+
29
+ - [Tencent COS Ruby SDK](#tencent-cos-ruby-sdk)
30
+ - [1 运行环境](#1-%E8%BF%90%E8%A1%8C%E7%8E%AF%E5%A2%83)
31
+ - [2 安装SDK](#2-%E5%AE%89%E8%A3%85sdk)
32
+ - [3 快速入门](#3-%E5%BF%AB%E9%80%9F%E5%85%A5%E9%97%A8)
33
+ - [3.1 准备工作](#31-%E5%87%86%E5%A4%87%E5%B7%A5%E4%BD%9C)
34
+ - [3.2 初始化](#32-%E5%88%9D%E5%A7%8B%E5%8C%96)
35
+ - [3.3 指定Bucket](#33-%E6%8C%87%E5%AE%9Abucket)
36
+ - [3.4 目录操作示例](#34-%E7%9B%AE%E5%BD%95%E6%93%8D%E4%BD%9C%E7%A4%BA%E4%BE%8B)
37
+ - [3.5 文件操作示例](#35-%E6%96%87%E4%BB%B6%E6%93%8D%E4%BD%9C%E7%A4%BA%E4%BE%8B)
38
+ - [4 SDK详细说明](#4-sdk%E8%AF%A6%E7%BB%86%E8%AF%B4%E6%98%8E)
39
+ - [4.1 初始化与配置](#41-%E5%88%9D%E5%A7%8B%E5%8C%96%E4%B8%8E%E9%85%8D%E7%BD%AE)
40
+ - [4.2 指定Bucket](#42-%E6%8C%87%E5%AE%9Abucket)
41
+ - [4.3 Bucket操作（COS::Bucket）](#43-bucket%E6%93%8D%E4%BD%9C%EF%BC%88cosbucket%EF%BC%89)
42
+ - [4.3.1 获取Bucket属性](#431-%E8%8E%B7%E5%8F%96bucket%E5%B1%9E%E6%80%A7)
43
+ - [4.3.2 创建目录（create_folder，mkdir）](#432-%E5%88%9B%E5%BB%BA%E7%9B%AE%E5%BD%95%EF%BC%88create_folder%EF%BC%8Cmkdir%EF%BC%89)
44
+ - [4.3.3 列举目录（list，ls）](#433-%E5%88%97%E4%B8%BE%E7%9B%AE%E5%BD%95%EF%BC%88list%EF%BC%8Cls%EF%BC%89)
45
+ - [4.3.4 上传文件（upload）](#434-%E4%B8%8A%E4%BC%A0%E6%96%87%E4%BB%B6%EF%BC%88upload%EF%BC%89)
46
+ - [4.3.4 资源属性（stat）](#434-%E8%B5%84%E6%BA%90%E5%B1%9E%E6%80%A7%EF%BC%88stat%EF%BC%89)
47
+ - [4.3.5 更新资源属性（upadte）](#435-%E6%9B%B4%E6%96%B0%E8%B5%84%E6%BA%90%E5%B1%9E%E6%80%A7%EF%BC%88upadte%EF%BC%89)
48
+ - [4.3.6 删除资源（delete）](#436-%E5%88%A0%E9%99%A4%E8%B5%84%E6%BA%90%EF%BC%88delete%EF%BC%89)
49
+ - [4.3.7 删除资源（无异常）（delete!）](#437-%E5%88%A0%E9%99%A4%E8%B5%84%E6%BA%90%EF%BC%88%E6%97%A0%E5%BC%82%E5%B8%B8%EF%BC%89%EF%BC%88delete%EF%BC%89)
50
+ - [4.3.8 判断目录是否为空（empty?）](#438-%E5%88%A4%E6%96%AD%E7%9B%AE%E5%BD%95%E6%98%AF%E5%90%A6%E4%B8%BA%E7%A9%BA%EF%BC%88empty%EF%BC%89)
51
+ - [4.3.9 判断资源是否存在（exist?，exists?）](#439-%E5%88%A4%E6%96%AD%E8%B5%84%E6%BA%90%E6%98%AF%E5%90%A6%E5%AD%98%E5%9C%A8%EF%BC%88exist%EF%BC%8Cexists%EF%BC%89)
52
+ - [4.3.9 判断文件是否上传完成（complete?）](#439-%E5%88%A4%E6%96%AD%E6%96%87%E4%BB%B6%E6%98%AF%E5%90%A6%E4%B8%8A%E4%BC%A0%E5%AE%8C%E6%88%90%EF%BC%88complete%EF%BC%89)
53
+ - [4.3.10 获取文件的访问URL（url）](#4310-%E8%8E%B7%E5%8F%96%E6%96%87%E4%BB%B6%E7%9A%84%E8%AE%BF%E9%97%AEurl%EF%BC%88url%EF%BC%89)
54
+ - [4.3.11 下载文件（download）](#4311-%E4%B8%8B%E8%BD%BD%E6%96%87%E4%BB%B6%EF%BC%88download%EF%BC%89)
55
+ - [4.3.12 获取Object树形结构（tree）](#4312-%E8%8E%B7%E5%8F%96object%E6%A0%91%E5%BD%A2%E7%BB%93%E6%9E%84%EF%BC%88tree%EF%BC%89)
56
+ - [4.3.13 获取Hash树形结构（hash_tree）](#4313-%E8%8E%B7%E5%8F%96hash%E6%A0%91%E5%BD%A2%E7%BB%93%E6%9E%84%EF%BC%88hash_tree%EF%BC%89)
57
+ - [4.3.14 批量下载目录下的所有文件（download_all）](#4314-%E6%89%B9%E9%87%8F%E4%B8%8B%E8%BD%BD%E7%9B%AE%E5%BD%95%E4%B8%8B%E7%9A%84%E6%89%80%E6%9C%89%E6%96%87%E4%BB%B6%EF%BC%88download_all%EF%BC%89)
58
+ - [4.3.15 批量上传目录中的所有文件（upload_all）](#4315-%E6%89%B9%E9%87%8F%E4%B8%8A%E4%BC%A0%E7%9B%AE%E5%BD%95%E4%B8%AD%E7%9A%84%E6%89%80%E6%9C%89%E6%96%87%E4%BB%B6%EF%BC%88upload_all%EF%BC%89)
59
+ - [4.3.16 获取资源个数详情（支持前缀搜索）（list_count）](#4316-%E8%8E%B7%E5%8F%96%E8%B5%84%E6%BA%90%E4%B8%AA%E6%95%B0%E8%AF%A6%E6%83%85%EF%BC%88%E6%94%AF%E6%8C%81%E5%89%8D%E7%BC%80%E6%90%9C%E7%B4%A2%EF%BC%89%EF%BC%88list_count%EF%BC%89)
60
+ - [4.3.17 获取资源个数（count, size）](#4317-%E8%8E%B7%E5%8F%96%E8%B5%84%E6%BA%90%E4%B8%AA%E6%95%B0%EF%BC%88count-size%EF%BC%89)
61
+ - [4.3.18 获取文件个数（count_files）](#4318-%E8%8E%B7%E5%8F%96%E6%96%87%E4%BB%B6%E4%B8%AA%E6%95%B0%EF%BC%88count_files%EF%BC%89)
62
+ - [4.3.19 获取目录个数（count_dirs）](#4319-%E8%8E%B7%E5%8F%96%E7%9B%AE%E5%BD%95%E4%B8%AA%E6%95%B0%EF%BC%88count_dirs%EF%BC%89)
63
+ - [4.4 资源操作](#44-%E8%B5%84%E6%BA%90%E6%93%8D%E4%BD%9C)
64
+ - [4.4.1 文件操作（COS::COSFile）](#441-%E6%96%87%E4%BB%B6%E6%93%8D%E4%BD%9C%EF%BC%88coscosfile%EF%BC%89)
65
+ - [4.4.1.1 获取文件属性](#4411-%E8%8E%B7%E5%8F%96%E6%96%87%E4%BB%B6%E5%B1%9E%E6%80%A7)
66
+ - [4.4.1.2 获取当前文件属性（刷新）（stat）](#4412-%E8%8E%B7%E5%8F%96%E5%BD%93%E5%89%8D%E6%96%87%E4%BB%B6%E5%B1%9E%E6%80%A7%EF%BC%88%E5%88%B7%E6%96%B0%EF%BC%89%EF%BC%88stat%EF%BC%89)
67
+ - [4.4.1.3 更新当前文件属性（upadte）](#4413-%E6%9B%B4%E6%96%B0%E5%BD%93%E5%89%8D%E6%96%87%E4%BB%B6%E5%B1%9E%E6%80%A7%EF%BC%88upadte%EF%BC%89)
68
+ - [4.4.1.4 删除当前文件（delete）](#4414-%E5%88%A0%E9%99%A4%E5%BD%93%E5%89%8D%E6%96%87%E4%BB%B6%EF%BC%88delete%EF%BC%89)
69
+ - [4.4.1.5 删除当前文件（无异常）（delete!）](#4415-%E5%88%A0%E9%99%A4%E5%BD%93%E5%89%8D%E6%96%87%E4%BB%B6%EF%BC%88%E6%97%A0%E5%BC%82%E5%B8%B8%EF%BC%89%EF%BC%88delete%EF%BC%89)
70
+ - [4.4.1.6 判断当前文件是否存在（exist?，exists?）](#4416-%E5%88%A4%E6%96%AD%E5%BD%93%E5%89%8D%E6%96%87%E4%BB%B6%E6%98%AF%E5%90%A6%E5%AD%98%E5%9C%A8%EF%BC%88exist%EF%BC%8Cexists%EF%BC%89)
71
+ - [4.4.1.7 判断当前文件是否上传完成（complete?）](#4417-%E5%88%A4%E6%96%AD%E5%BD%93%E5%89%8D%E6%96%87%E4%BB%B6%E6%98%AF%E5%90%A6%E4%B8%8A%E4%BC%A0%E5%AE%8C%E6%88%90%EF%BC%88complete%EF%BC%89)
72
+ - [4.4.1.8 获取当前文件的访问URL（url）](#4418-%E8%8E%B7%E5%8F%96%E5%BD%93%E5%89%8D%E6%96%87%E4%BB%B6%E7%9A%84%E8%AE%BF%E9%97%AEurl%EF%BC%88url%EF%BC%89)
73
+ - [4.4.1.9 下载当前文件（download）](#4419-%E4%B8%8B%E8%BD%BD%E5%BD%93%E5%89%8D%E6%96%87%E4%BB%B6%EF%BC%88download%EF%BC%89)
74
+ - [4.4.1.10 判断当前文件与本地文件是否相同](#44110-%E5%88%A4%E6%96%AD%E5%BD%93%E5%89%8D%E6%96%87%E4%BB%B6%E4%B8%8E%E6%9C%AC%E5%9C%B0%E6%96%87%E4%BB%B6%E6%98%AF%E5%90%A6%E7%9B%B8%E5%90%8C)
75
+ - [4.4.2 目录操作（COS::COSDir）](#442-%E7%9B%AE%E5%BD%95%E6%93%8D%E4%BD%9C%EF%BC%88coscosdir%EF%BC%89)
76
+ - [4.4.2.1 获取目录属性](#4421-%E8%8E%B7%E5%8F%96%E7%9B%AE%E5%BD%95%E5%B1%9E%E6%80%A7)
77
+ - [4.4.2.2 列举当前目录（前缀搜索）（list，ls）](#4422-%E5%88%97%E4%B8%BE%E5%BD%93%E5%89%8D%E7%9B%AE%E5%BD%95%EF%BC%88%E5%89%8D%E7%BC%80%E6%90%9C%E7%B4%A2%EF%BC%89%EF%BC%88list%EF%BC%8Cls%EF%BC%89)
78
+ - [4.4.2.3 创建子目录（create_folder，mkdir）](#4423-%E5%88%9B%E5%BB%BA%E5%AD%90%E7%9B%AE%E5%BD%95%EF%BC%88create_folder%EF%BC%8Cmkdir%EF%BC%89)
79
+ - [4.4.2.4 上传文件至当前目录（upload）](#4424-%E4%B8%8A%E4%BC%A0%E6%96%87%E4%BB%B6%E8%87%B3%E5%BD%93%E5%89%8D%E7%9B%AE%E5%BD%95%EF%BC%88upload%EF%BC%89)
80
+ - [4.4.2.5 批量上传本地目录中的所有文件至当前目录（upload_all）](#4425-%E6%89%B9%E9%87%8F%E4%B8%8A%E4%BC%A0%E6%9C%AC%E5%9C%B0%E7%9B%AE%E5%BD%95%E4%B8%AD%E7%9A%84%E6%89%80%E6%9C%89%E6%96%87%E4%BB%B6%E8%87%B3%E5%BD%93%E5%89%8D%E7%9B%AE%E5%BD%95%EF%BC%88upload_all%EF%BC%89)
81
+ - [4.4.2.6 批量下载当前目录下的所有文件（download_all）](#4426-%E6%89%B9%E9%87%8F%E4%B8%8B%E8%BD%BD%E5%BD%93%E5%89%8D%E7%9B%AE%E5%BD%95%E4%B8%8B%E7%9A%84%E6%89%80%E6%9C%89%E6%96%87%E4%BB%B6%EF%BC%88download_all%EF%BC%89)
82
+ - [4.4.2.7 当前目录属性（刷新）（stat）](#4427-%E5%BD%93%E5%89%8D%E7%9B%AE%E5%BD%95%E5%B1%9E%E6%80%A7%EF%BC%88%E5%88%B7%E6%96%B0%EF%BC%89%EF%BC%88stat%EF%BC%89)
83
+ - [4.4.2.8 更新当前目录属性（upadte）](#4428-%E6%9B%B4%E6%96%B0%E5%BD%93%E5%89%8D%E7%9B%AE%E5%BD%95%E5%B1%9E%E6%80%A7%EF%BC%88upadte%EF%BC%89)
84
+ - [4.4.2.9 删除当前目录（delete）](#4429-%E5%88%A0%E9%99%A4%E5%BD%93%E5%89%8D%E7%9B%AE%E5%BD%95%EF%BC%88delete%EF%BC%89)
85
+ - [4.4.2.10 删除当前目录（无异常）（delete!）](#44210-%E5%88%A0%E9%99%A4%E5%BD%93%E5%89%8D%E7%9B%AE%E5%BD%95%EF%BC%88%E6%97%A0%E5%BC%82%E5%B8%B8%EF%BC%89%EF%BC%88delete%EF%BC%89)
86
+ - [4.4.2.11 判断当前目录是否为空（empty?）](#44211-%E5%88%A4%E6%96%AD%E5%BD%93%E5%89%8D%E7%9B%AE%E5%BD%95%E6%98%AF%E5%90%A6%E4%B8%BA%E7%A9%BA%EF%BC%88empty%EF%BC%89)
87
+ - [4.4.2.12 判断当前目录是否存在（exist?，exists?）](#44212-%E5%88%A4%E6%96%AD%E5%BD%93%E5%89%8D%E7%9B%AE%E5%BD%95%E6%98%AF%E5%90%A6%E5%AD%98%E5%9C%A8%EF%BC%88exist%EF%BC%8Cexists%EF%BC%89)
88
+ - [4.4.2.13 获取当前目录下的Object树形结构（tree）](#44213-%E8%8E%B7%E5%8F%96%E5%BD%93%E5%89%8D%E7%9B%AE%E5%BD%95%E4%B8%8B%E7%9A%84object%E6%A0%91%E5%BD%A2%E7%BB%93%E6%9E%84%EF%BC%88tree%EF%BC%89)
89
+ - [4.4.2.14 获取当前目录下的Hash树形结构（hash_tree）](#44214-%E8%8E%B7%E5%8F%96%E5%BD%93%E5%89%8D%E7%9B%AE%E5%BD%95%E4%B8%8B%E7%9A%84hash%E6%A0%91%E5%BD%A2%E7%BB%93%E6%9E%84%EF%BC%88hash_tree%EF%BC%89)
90
+ - [4.4.2.15 获取当前目录下的资源个数详情（支持前缀搜索）（list_count）](#44215-%E8%8E%B7%E5%8F%96%E5%BD%93%E5%89%8D%E7%9B%AE%E5%BD%95%E4%B8%8B%E7%9A%84%E8%B5%84%E6%BA%90%E4%B8%AA%E6%95%B0%E8%AF%A6%E6%83%85%EF%BC%88%E6%94%AF%E6%8C%81%E5%89%8D%E7%BC%80%E6%90%9C%E7%B4%A2%EF%BC%89%EF%BC%88list_count%EF%BC%89)
91
+ - [4.4.2.16 获取当前目录下的资源个数（count, size）](#44216-%E8%8E%B7%E5%8F%96%E5%BD%93%E5%89%8D%E7%9B%AE%E5%BD%95%E4%B8%8B%E7%9A%84%E8%B5%84%E6%BA%90%E4%B8%AA%E6%95%B0%EF%BC%88count-size%EF%BC%89)
92
+ - [4.4.2.17 获取当前目录下的文件个数（count_files）](#44217-%E8%8E%B7%E5%8F%96%E5%BD%93%E5%89%8D%E7%9B%AE%E5%BD%95%E4%B8%8B%E7%9A%84%E6%96%87%E4%BB%B6%E4%B8%AA%E6%95%B0%EF%BC%88count_files%EF%BC%89)
93
+ - [4.4.2.18 获取当前目录下的子目录个数（count_dirs）](#44218-%E8%8E%B7%E5%8F%96%E5%BD%93%E5%89%8D%E7%9B%AE%E5%BD%95%E4%B8%8B%E7%9A%84%E5%AD%90%E7%9B%AE%E5%BD%95%E4%B8%AA%E6%95%B0%EF%BC%88count_dirs%EF%BC%89)
94
+ - [4.5 签名操作（COS::Signature）](#45-%E7%AD%BE%E5%90%8D%E6%93%8D%E4%BD%9C%EF%BC%88cossignature%EF%BC%89)
95
+ - [4.5.1 获取单次有效签名（once）](#451-%E8%8E%B7%E5%8F%96%E5%8D%95%E6%AC%A1%E6%9C%89%E6%95%88%E7%AD%BE%E5%90%8D%EF%BC%88once%EF%BC%89)
96
+ - [4.5.2 获取多次有效签名（multiple）](#452-%E8%8E%B7%E5%8F%96%E5%A4%9A%E6%AC%A1%E6%9C%89%E6%95%88%E7%AD%BE%E5%90%8D%EF%BC%88multiple%EF%BC%89)
97
+ - [5 底层API（COS::API）](#5-%E5%BA%95%E5%B1%82api%EF%BC%88cosapi%EF%BC%89)
98
+ - [5.1 创建目录(create_folder)](#51-%E5%88%9B%E5%BB%BA%E7%9B%AE%E5%BD%95create_folder)
99
+ - [5.2 目录列表（前缀搜索）(list)](#52-%E7%9B%AE%E5%BD%95%E5%88%97%E8%A1%A8%EF%BC%88%E5%89%8D%E7%BC%80%E6%90%9C%E7%B4%A2%EF%BC%89list)
100
+ - [5.3 上传文件（完整上传）(upload)](#53-%E4%B8%8A%E4%BC%A0%E6%96%87%E4%BB%B6%EF%BC%88%E5%AE%8C%E6%95%B4%E4%B8%8A%E4%BC%A0%EF%BC%89upload)
101
+ - [5.4 上传文件（分片上传）(upload_slice)](#54-%E4%B8%8A%E4%BC%A0%E6%96%87%E4%BB%B6%EF%BC%88%E5%88%86%E7%89%87%E4%B8%8A%E4%BC%A0%EF%BC%89upload_slice)
102
+ - [5.5 更新文件、目录属性(update)](#55-%E6%9B%B4%E6%96%B0%E6%96%87%E4%BB%B6%E3%80%81%E7%9B%AE%E5%BD%95%E5%B1%9E%E6%80%A7update)
103
+ - [5.6 删除文件、目录(delete)](#56-%E5%88%A0%E9%99%A4%E6%96%87%E4%BB%B6%E3%80%81%E7%9B%AE%E5%BD%95delete)
104
+ - [5.7 获取文件或目录属性(stat)](#57-%E8%8E%B7%E5%8F%96%E6%96%87%E4%BB%B6%E6%88%96%E7%9B%AE%E5%BD%95%E5%B1%9E%E6%80%A7stat)
105
+ - [5.8下载文件](#58%E4%B8%8B%E8%BD%BD%E6%96%87%E4%BB%B6)
106
+ - [6 CLI命令行工具](#6-cli%E5%91%BD%E4%BB%A4%E8%A1%8C%E5%B7%A5%E5%85%B7)
107
+ - [7 运行测试](#7-%E8%BF%90%E8%A1%8C%E6%B5%8B%E8%AF%95)
108
+
109
+ ## 1 运行环境
110
+
111
+ - Ruby版本：MRI >= 1.9.3, JRuby >= 1.9
112
+ - 操作系统：Windows/Linux/OS X
113
+
114
+ ## 2 安装SDK
115
+
116
+ 添加至应用程序的Gemfile文件：
117
+
118
+ ``` ruby
12
119
  gem 'cos'
13
120
  ```
14
121
 
15
- And then execute:
122
+ 然后执行：
123
+
124
+ ```
125
+ $ bundle
126
+ ```
127
+
128
+ 或手动安装gem：
129
+
130
+ ```
131
+ $ gem install cos
132
+ ```
133
+
134
+ ## 3 快速入门
135
+
136
+ ### 3.1 准备工作
137
+
138
+ 在[腾讯云COS控制台](http://console.qcloud.com/cos)创建Bucket并获取您的`app_id` `secret_id` `secret_key`
139
+
140
+ 🔍具体操作可参考[COS控制台使用说明](http://www.qcloud.com/wiki/COS%E6%8E%A7%E5%88%B6%E5%8F%B0%E4%BD%BF%E7%94%A8%E8%AF%B4%E6%98%8E)
141
+
142
+ ### 3.2 初始化
143
+
144
+ ``` ruby
145
+ require 'cos'
146
+
147
+ client = COS::Client.new({
148
+ app_id: 'your_app_id',
149
+ secret_id: 'your_secret_id',
150
+ secret_key: 'your_secret_key',
151
+ protocol: 'https' # 使用https
152
+ })
153
+ ```
154
+
155
+ 更多初始化参数及加载方式请见：4.1 初始化与配置
156
+
157
+ ### 3.3 指定Bucket
158
+
159
+ ``` ruby
160
+ bucket = client.bucket('your_bucket_name')
161
+ ```
162
+
163
+ 🎉【Tip】你也可以在初始化Client时通过`default_bucket`参数设置默认的Bucket：
164
+
165
+ ``` ruby
166
+ client = COS::Client.new({
167
+ app_id: 'your_app_id',
168
+ secret_id: 'your_secret_id',
169
+ secret_key: 'your_secret_key',
170
+ defualt_bucket: 'your_default_bucket',
171
+ })
172
+ # 取得默认Bucket
173
+ bucket = client.bucket
174
+ ```
175
+
176
+ ### 3.4 目录操作示例
177
+
178
+ ``` ruby
179
+ # 列举bucket根目录中的文件与目录
180
+ bucket.list do |res|
181
+ if res.is_a?(COS::COSDir) # 或 res.type == 'dir'
182
+ puts "Dir：#{res.name} #{res.biz_attr}"
183
+ # 设置目录属性
184
+ res.update('属性1')
185
+ else
186
+ # 文件 COS::COSFile 或 res.type == 'file'
187
+ puts "File：#{res.name}"
188
+ # 输出Hash参数
189
+ puts res.to_hash
190
+ end
191
+ end
192
+
193
+ # 可以按路径列出资源
194
+ bucket.list('/path/path2/') { |r| puts r.name }
195
+
196
+ # 只列出文件
197
+ bucket.list('/path/path2/', :pattern => :only_file) { |r| puts r.name }
198
+
199
+ # 倒序只列出目录
200
+ bucket.list('/path/path2/', :pattern => :only_dir, :order => :desc) { |r| puts r.name }
201
+
202
+ # 获取bucket信息
203
+ b = bucket.stat
204
+ puts b.refers
205
+
206
+ # 判断目录是否存在
207
+ puts bucket.exist?('dir')
208
+ # 获取目录信息
209
+ dir = bucket.stat('dir')
210
+ # 创建时间修改时间
211
+ puts dir.created_at
212
+ puts dir.updated_at
213
+ # 判断目录是否是空的
214
+ puts dir.empty?
215
+ # 目录中的文件及目录总数
216
+ puts dir.count
217
+ # 目录中的文件总数
218
+ puts dir.count_files
219
+ # 目录中的文件夹总数
220
+ puts dir.count_dirs
221
+ # 获取目录的树形结构
222
+ puts dir.hash_tree.to_json
223
+ # 删除目录
224
+ puts dir.delete!
225
+ # 上传文件至目录, 自动大文件分片多线程断点续传
226
+ dir.upload('file2', '~/path2/file2')
227
+ # 批量上传文件至目录，自动大文件分片多线程断点续传
228
+ dir.upload_all('~/path1')
229
+ # 下载目录中的所有文件，自动大文件分片多线程断点续传
230
+ puts bucket.stat('path3').download_all('~/path_store')
231
+ ```
232
+
233
+ ### 3.5 文件操作示例
234
+
235
+ ``` ruby
236
+ # 上传文件，自动大文件分片多线程断点续传
237
+ file = bucket.upload('path', 'file1', '~/local_path/file1') do |pr|
238
+ puts "上传进度 #{(pr*100).round(2)}%"
239
+ end
240
+ # 判断文件是否存在
241
+ puts bucket.exist?('path/file1')
242
+ # 获取文件信息
243
+ file = bucket.stat('path/file1')
244
+ puts file.name
245
+ puts file.biz_attr
246
+ # 更新文件属性
247
+ file.update('i am a biz attr')
248
+ # 判断文件是否上传完成
249
+ puts file.complete?
250
+ # 获取文件大小
251
+ puts file.size # file.file_size OR file.filesize
252
+ # 获取文件格式化的文件大小
253
+ puts file.format_size # 102KB, 3.1MB, 1.5GB
254
+ # 下载文件，自动大文件分片多线程断点续传
255
+ file.download('~/path/file1') do |pr|
256
+ puts "下载进度 #{(pr*100).round(2)}%"
257
+ end
258
+ # 获取文件访问URL，私有读取bucket自动添加签名
259
+ file.url(cname: 's.domain.com')
260
+ # 删除文件
261
+ file.delete
262
+ ```
263
+
264
+
265
+
266
+ ## 4 SDK详细说明
267
+
268
+ ### 4.1 初始化与配置
269
+
270
+ - 4.1.1 详细参数
271
+
272
+ ``` ruby
273
+ {
274
+ # COS分配的app_id
275
+ :app_id => 'app_id',
276
+ # COS分配的secret_id
277
+ :secret_id => 'secret_id',
278
+ # COS分配的secret_key
279
+ :secret_key => 'secret_key',
280
+ # COS Reatful API Host
281
+ :host => 'web.file.myqcloud.com',
282
+ # 使用协议,默认为http,可选https
283
+ :protocol => 'https',
284
+ # 接口通讯建立连接超时秒数
285
+ :open_timeout => 15,
286
+ # 接口通讯读取数据超时秒数
287
+ :read_timeout => 120,
288
+ # 加载配置文件路径
289
+ :config => '~/path/cos.yml',
290
+ # 日志输出位置，可以是文件路径也可为STDOUT、STDERR
291
+ :log_src => '/var/log/cos.log',
292
+ # 输出日志级别
293
+ :log_level => Logger::INFO,
294
+ # 默认bucket
295
+ :default_bucket => 'bucket_name',
296
+ # 多次签名过期时间(单位秒)
297
+ :multiple_sign_expire => 300
298
+ }
299
+ ```
300
+
301
+
302
+ - 4.1.2 标准方式初始化配置
303
+
304
+ ``` ruby
305
+ require 'cos'
306
+
307
+ @client = COS::Client.new(configs)
308
+ ```
309
+
310
+ - 4.1.3 实例方式初始化配置
311
+
312
+ ``` ruby
313
+ require 'cos'
314
+
315
+ # 程序启动时加载配置
316
+ COS.client(configs)
317
+ # 使用client
318
+ COS.client.bucket
319
+ ```
320
+
321
+ - 4.1.4 从配置文件加载配置
322
+
323
+ ``` ruby
324
+ require 'cos'
325
+
326
+ @client = COS::Client.new(config: './cos.yml')
327
+ # 或
328
+ COS.client(config: './cos.yml')
329
+ ```
330
+
331
+ Rails中会自动加载项目目录下的配置文件`log/cos.yml`
332
+
333
+ 🎉【Tip】可以使用CLI指令`cos init`创建默认的yml配置文件，`cos init [配置文件路径]`自定义配置文件的路径。
334
+
335
+ ### 4.2 指定Bucket
336
+
337
+ 所有的资源基本操作是基于一个bucket的，所有我们需要先指定一个bucket：
338
+
339
+ ``` ruby
340
+ @bucket = @client.bucket('bucket_name')
341
+ # 或使用配置的默认bucket
342
+ @bucket = @client.bucket
343
+ ```
344
+
345
+ 注：指定bucket时，SDK会获取一次bucket信息，获取权限类型等信息，如bucket不存在将会抛出异常。
346
+
347
+ ### 4.3 Bucket操作（COS::Bucket）
348
+
349
+ #### 4.3.1 获取Bucket属性
350
+
351
+ ``` ruby
352
+ # bucket名称
353
+ puts @bucket.bucket_name
354
+ # bucket权限
355
+ puts @bucket.authority
356
+ ```
357
+
358
+ | 属性 | 类型 | 描述 |
359
+ | --------------------- | ------------- | -------------------------------------- |
360
+ | bucket_name | String | bucket名称 |
361
+ | authority | String | eWPrivateRPublic私有写公共读，eWPrivate私有写私有读 |
362
+ | bucket_type | Integer | bucket_type |
363
+ | migrate_source_domain | String | 回源地址 |
364
+ | need_preview | String | need_preview |
365
+ | refers | Array<String> | refers |
366
+ | blackrefers | Array<String> | blackrefers |
367
+ | cnames | Array<String> | cnames |
368
+ | nugc_flag | String | nugc_flag |
369
+
370
+ #### 4.3.2 创建目录（create_folder，mkdir）
371
+
372
+ ``` ruby
373
+ @bucket.create_folder(path, options = {}) # 方法别名mkdir
374
+ ```
375
+
376
+ 参数：
377
+
378
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
379
+ | :----------------- | :----: | :--: | :--: | ---------------------------------------- |
380
+ | path | String | 是 | 无 | 需要创建的目录路径, 如: 'path1', 'path1/path2', sdk会补齐末尾的 '/'。 |
381
+ | options | Hash | | | |
382
+ | options[:biz_attr] | String | 否 | 无 | 目录属性, 业务端维护 |
383
+
384
+ 返回：
385
+
386
+ ``` ruby
387
+ COS::COSDir # 详见目录操作（COS::COSDir）
388
+ ```
389
+
390
+ 示例：
391
+
392
+ ``` ruby
393
+ @bucket.create_folder("test_dir1", biz_attr: '测试目录1')
394
+ ```
395
+
396
+ 更多示例详见：example/create_folder.rb
397
+
398
+ #### 4.3.3 列举目录（list，ls）
399
+
400
+ ``` ruby
401
+ @bucket.list(path = '', options = {}) # 方法别名ls
402
+ ```
403
+
404
+ 参数：
405
+
406
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
407
+ | :---------------- | :-----: | :--: | :---: | ---------------------------------------- |
408
+ | path | String | 否 | 空 | 需要列举的目录路径, 如: 'path1', 'path1/path2', sdk会补齐末尾的 '/'。 |
409
+ | options | Hash | | | |
410
+ | options[:prefix] | String | 否 | 无 | 搜索前缀，如果填写prefix, 则列出含此前缀的所有文件及目录 |
411
+ | options[:num] | Integer | 否 | 20 | |
412
+ | options[:pattern] | Symbol | 否 | :both | 获取模式，:dir_only 只获取目录, :file_only 只获取文件, 默认为 :both 全部获取 |
413
+ | options[:order] | Symbol | 否 | :asc | 排序方式 :asc 正序, :desc 倒序 默认为 :asc |
414
+
415
+ 返回：
416
+
417
+ ``` ruby
418
+ [Enumerator<Object>] 迭代器, 其中Object可能是COS::COSFile或COS::COSDir
419
+ ```
420
+
421
+ 示例：
422
+
423
+ ``` ruby
424
+ @bucket.list('test') do |res|
425
+ if res.is_a?(COS::COSDir)
426
+ puts "Dir: #{res.name} #{res.path}"
427
+ else
428
+ puts "File: #{res.name} #{res.format_size}"
429
+ end
430
+ end
431
+ ```
432
+
433
+ 更多示例详见：example/list.rb
434
+
435
+ #### 4.3.4 上传文件（upload）
436
+
437
+ ``` ruby
438
+ @bucket.upload(path_or_dir, file_name, file_src, options = {}, &block)
439
+ ```
440
+
441
+ 参数：
442
+
443
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
444
+ | :--------------------------- | :-----: | :---------: | :--------------: | --------------------------------------- |
445
+ | path_or_dir | String\ | COS::COSDir | 是 | 无 |
446
+ | file_name | String | 是 | 无 | 存储文件名 |
447
+ | file_src | String | 是 | 无 | 本地文件路径 |
448
+ | options | Hash | 否 | 无 | |
449
+ | options[:auto_create_folder] | Boolean | 否 | false | 自动创建远端目录 |
450
+ | options[:min_slice_size] | Integer | 否 | 10 * 1024 * 1024 | 完整上传最小文件大小,超过此大小将会使用分片多线程断点续传 |
451
+ | options[:upload_retry] | Integer | 否 | 10 | 上传重试次数 |
452
+ | options[:biz_attr] | String | 否 | 无 | 业务属性 |
453
+ | options[:disable_cpt] | Boolean | 否 | false | 是否禁用checkpoint，如禁用仍可通过服务端进行断点续传 |
454
+ | options[:threads] | Integer | 否 | 10 | 多线程上传线程数 |
455
+ | options[:slice_size] | Integer | 否 | 3 * 1024 * 1024 | 设置分片上传时每个分片的大小。默认为3 MB, 目前服务端最大限制也为3MB。 |
456
+ | options[:cpt_file] | String | 否 | 无 | 断点续传的checkpoint文件 |
457
+ | yield | Float | 否 | 无 | 上传进度百分比回调, 进度值是一个0-1之间的小数 |
458
+
459
+ 注：SDK会自动使用分片断点续传上传大文件。
460
+
461
+ 返回：
462
+
463
+ ``` ruby
464
+ COS::COSFile # 详见目录操作（COS::COSFile）
465
+ ```
466
+
467
+ 示例：
468
+
469
+ ``` ruby
470
+ file = @bucket.upload('/test', 'file1.txt', '~/test.txt') do |pr|
471
+ puts "上传进度 #{(pr*100).round(2)}%"
472
+ end
473
+ puts file.name
474
+ puts file.format_size
475
+ puts file.url
476
+ ```
477
+
478
+ 更多示例详见： example/upload.rb
479
+
480
+ #### 4.3.4 资源属性（stat）
481
+
482
+ ``` ruby
483
+ @bucket.stat(path)
484
+ ```
485
+
486
+ 参数：
487
+
488
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
489
+ | :--- | :----: | :--: | :--: | ------------------------------------ |
490
+ | path | String | 是 | 无 | 资源路径, 如: 目录'path1/', 文件'path1/file'。 |
491
+
492
+ 返回：
493
+
494
+ ``` ruby
495
+ 可能是COS::COSFile(文件)或COS::COSDir(目录)
496
+ ```
497
+
498
+ 示例：
499
+
500
+ ``` ruby
501
+ puts @bucket.stat('/test').name
502
+ ```
503
+
504
+ 更多示例详见： example/stat.rb
505
+
506
+ #### 4.3.5 更新资源属性（upadte）
507
+
508
+ ``` ruby
509
+ @bucket.update(path, biz_attr)
510
+ ```
511
+
512
+ 参数：
513
+
514
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
515
+ | :------- | :----: | :--: | :--: | ------------------------------------ |
516
+ | path | String | 是 | 无 | 资源路径, 如: 目录'path1/', 文件'path1/file'。 |
517
+ | biz_attr | String | 是 | 无 | 业务属性 |
518
+
519
+ 示例：
520
+
521
+ ``` ruby
522
+ @bucket.update('test/file1', 'new biz attr')
523
+ ```
524
+
525
+ 更多示例详见： example/update.rb
526
+
527
+ #### 4.3.6 删除资源（delete）
528
+
529
+ ``` ruby
530
+ @bucket.delete(path)
531
+ ```
532
+
533
+ 参数：
534
+
535
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
536
+ | :--- | :----: | :--: | :--: | ------------------------------------ |
537
+ | path | String | 是 | 无 | 资源路径, 如: 目录'path1/', 文件'path1/file'。 |
538
+
539
+ 注意：非空目录或根目录无法删除，会抛出异常
540
+
541
+ 示例：
542
+
543
+ ``` ruby
544
+ @bucket.delete('test/')
545
+ ```
546
+
547
+ 更多示例详见：example/delete.rb
548
+
549
+ #### 4.3.7 删除资源（无异常）（delete!）
550
+
551
+ ``` ruby
552
+ @bucket.delete!(path)
553
+ ```
554
+
555
+ 参数：
556
+
557
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
558
+ | :--- | :----: | :--: | :--: | ------------------------------------ |
559
+ | path | String | 是 | 无 | 资源路径, 如: 目录'path1/', 文件'path1/file'。 |
560
+
561
+ 注意：非空目录或根目录无法删除，返回是否成功的bool值。
562
+
563
+ 返回：
564
+
565
+ ``` ruby
566
+ Boolean
567
+ ```
568
+
569
+ 示例：
570
+
571
+ ``` ruby
572
+ puts @bucket.delete!('test/')
573
+ ```
574
+
575
+ 更多示例详见：example/delete.rb
576
+
577
+ #### 4.3.8 判断目录是否为空（empty?）
578
+
579
+ ``` ruby
580
+ @bucket.empty?(path)
581
+ ```
582
+
583
+ 参数：
584
+
585
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
586
+ | :--- | :----: | :--: | :--: | -------------------------------------- |
587
+ | path | String | 否 | 空 | 目录路径, 如: 目录'path1/'。如为空则会判断bucket是否为空。 |
588
+
589
+ 返回：
590
+
591
+ ``` ruby
592
+ Boolean
593
+ ```
594
+
595
+ 示例：
596
+
597
+ ``` ruby
598
+ # 目录是否为空
599
+ puts @bucket.empty?('test/')
600
+ # bucket是否为空
601
+ puts @bucket.empty?
602
+ ```
603
+
604
+ #### 4.3.9 判断资源是否存在（exist?，exists?）
605
+
606
+ ``` ruby
607
+ @bucket.exist?(path) # 别名 exists?
608
+ ```
609
+
610
+ 参数：
611
+
612
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
613
+ | :--- | :----: | :--: | :--: | ----------------------------------- |
614
+ | path | String | 是 | 无 | 资源路径, 如: 目录'path1/', 文件'path1/file' |
615
+
616
+ 返回：
617
+
618
+ ``` ruby
619
+ Boolean
620
+ ```
621
+
622
+ 示例：
623
+
624
+ ``` ruby
625
+ puts @bucket.exist?('test/')
626
+ puts @bucket.exist?('test/file1')
627
+ ```
628
+
629
+ #### 4.3.9 判断文件是否上传完成（complete?）
630
+
631
+ ``` ruby
632
+ @bucket.complete?(path)
633
+ ```
634
+
635
+ 参数：
636
+
637
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
638
+ | :--- | :----: | :--: | :--: | ----------------------- |
639
+ | path | String | 是 | 无 | 文件资源路径, 如: 'path1/file' |
640
+
641
+ 返回：
642
+
643
+ ``` ruby
644
+ Boolean
645
+ ```
646
+
647
+ 示例：
648
+
649
+ ``` ruby
650
+ puts @bucket.complete?('path/file1')
651
+ ```
652
+
653
+ #### 4.3.10 获取文件的访问URL（url）
654
+
655
+ ``` ruby
656
+ @bucket.url(path_or_file, options = {})
657
+ ```
658
+
659
+ 参数：
660
+
661
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
662
+ | :----------------------- | :-----: | :----------: | :---: | ------------------------------- |
663
+ | path_or_file | String\ | COS::COSFile | 否 | 空 |
664
+ | options | Hash | | | |
665
+ | options[:cname] | String | 否 | 无 | 获取使用cname的url。在cos控制台设置的cname域名 |
666
+ | options[:https] | Boolean | 否 | false | 是否获取https的url |
667
+ | options[:expire_seconds] | Integer | 否 | 600 | 签名有效时间(秒,私有读取bucket时需要) |
668
+
669
+ 返回：
670
+
671
+ ``` ruby
672
+ String
673
+ ```
674
+
675
+ 示例：
676
+
677
+ ``` ruby
678
+ puts bucket.url('path1/file1', https: true, cname: 'static.domain.com')
679
+ ```
680
+
681
+ #### 4.3.11 下载文件（download）
682
+
683
+ ``` ruby
684
+ @bucket.download(path_or_file, file_store, options = {}, &block)
685
+ ```
686
+
687
+ 参数：
688
+
689
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
690
+ | :----------------------- | :-----: | :----------: | :-----------: | ----------------------------- |
691
+ | path_or_file | String\ | COS::COSFile | 是 | 无 |
692
+ | file_store | String | 是 | 无 | 本地文件存储路径 |
693
+ | options | Hash | 否 | 无 | |
694
+ | options[:disable_mkdir] | Boolean | 否 | true | 禁止自动创建本地文件夹, 默认会创建 |
695
+ | options[:min_slice_size] | Integer | 否 | 5 * 10 * 1024 | 完整下载最小文件大小,超过此大小将会使用分片多线程断点续传 |
696
+ | options[:download_retry] | Integer | 否 | 10 | 下载重试次数 |
697
+ | options[:disable_cpt] | Boolean | 否 | false | 是否禁用checkpoint，如果禁用则不使用断点续传 |
698
+ | yield | Float | 否 | 无 | 下载进度百分比回调, 进度值是一个0-1之间的小数 |
699
+
700
+ 注：支持私有访问资源下载，SDK会自动携带鉴权签名。SDK会自动使用分片断点续传下载大文件。
701
+
702
+ 返回：
703
+
704
+ ``` ruby
705
+ String # 本地文件存储路径
706
+ ```
707
+
708
+ 示例：
16
709
 
17
- $ bundle
710
+ ``` ruby
711
+ file = bucket.download('path/file1', '~/test/file1') do |p|
712
+ puts "下载进度: #{(p*100).round(2)}%")
713
+ end
714
+ puts file
715
+ ```
716
+
717
+ 更多示例详见：example/download.rb
718
+
719
+ #### 4.3.12 获取Object树形结构（tree）
720
+
721
+ ``` ruby
722
+ @bucket.tree(path_or_dir = '', options = {})
723
+ ```
724
+
725
+ 参数：
726
+
727
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
728
+ | :-------------- | :-----: | :---------: | :--: | ---------- |
729
+ | path_or_dir | String\ | COS::COSDir | 否 | 空 |
730
+ | options | Hash | | | |
731
+ | options[:depth] | Integer | 否 | 5 | 子目录深度,默认为5 |
732
+
733
+ 返回：
734
+
735
+ ```
736
+ {
737
+ :resource => Object<COS::COSDir>,
738
+ :children => [
739
+ {:resource => Object<COS::COSDir>, :children => [...]},
740
+ {:resource => Object<COS::COSFile>, :children => [...]},
741
+ ...
742
+ ]
743
+ }
744
+ ```
745
+
746
+ 示例：
747
+
748
+ ``` ruby
749
+ tree = @bucket.tree
750
+ puts tree[:resource].name
751
+ tree[:children].each do |r|
752
+ puts r[:resource].name
753
+ end
754
+ ```
755
+
756
+ #### 4.3.13 获取Hash树形结构（hash_tree）
757
+
758
+ ``` ruby
759
+ @bucket.hash_tree(path_or_dir = '', options = {})
760
+ ```
761
+
762
+ 参数：
763
+
764
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
765
+ | :-------------- | :-----: | :---------: | :--: | ---------- |
766
+ | path_or_dir | String\ | COS::COSDir | 否 | 空 |
767
+ | options | Hash | | | |
768
+ | options[:depth] | Integer | 否 | 5 | 子目录深度,默认为5 |
769
+
770
+ 返回：
771
+
772
+ ```
773
+ {
774
+ :resource => {:name...},
775
+ :children => [
776
+ {:resource => {:name...}, :children => [...]},
777
+ {:resource => {:name...}, :children => [...]},
778
+ ...
779
+ ]
780
+ }
781
+ ```
782
+
783
+ 示例：
784
+
785
+ ``` ruby
786
+ tree = @bucket.hash_tree
787
+ puts tree[:resource][:name]
788
+ tree[:children].each do |r|
789
+ puts r[:resource][:name]
790
+ end
791
+ puts tree.to_json # 可直接转为json
792
+ ```
793
+
794
+ #### 4.3.14 批量下载目录下的所有文件（download_all）
795
+
796
+ ``` ruby
797
+ @bucket.download_all(path_or_dir, file_store_path, options = {}, &block)
798
+ ```
799
+
800
+ 参数：
801
+
802
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
803
+ | :----------------------- | :-----: | :---------: | :-----------: | ----------------------------- |
804
+ | path_or_dir | String\ | COS::COSDir | 是 | 无 |
805
+ | file_store_path | String | 是 | 无 | 本地文件存储目录 |
806
+ | options | Hash | 否 | 无 | |
807
+ | options[:disable_mkdir] | Boolean | 否 | true | 禁止自动创建本地文件夹, 默认会创建 |
808
+ | options[:min_slice_size] | Integer | 否 | 5 * 10 * 1024 | 完整下载最小文件大小,超过此大小将会使用分片多线程断点续传 |
809
+ | options[:download_retry] | Integer | 否 | 10 | 下载重试次数 |
810
+ | options[:disable_cpt] | Boolean | 否 | false | 是否禁用checkpoint，如果禁用则不使用断点续传 |
811
+ | yield | Float | 否 | 无 | 下载进度百分比回调, 进度值是一个0-1之间的小数 |
812
+
813
+ 注：不包含子目录。支持私有访问资源下载，SDK会自动携带鉴权签名。SDK会自动使用分片断点续传下载大文件。
814
+
815
+ 返回：
816
+
817
+ ``` ruby
818
+ Array<String> # 本地文件存储路径数组
819
+ ```
820
+
821
+ 示例：
822
+
823
+ ``` ruby
824
+ files = bucket.download_all('path/', '~/test/path/') do |p|
825
+ puts "下载进度: #{(p*100).round(2)}%")
826
+ end
827
+ puts files
828
+ ```
829
+
830
+ #### 4.3.15 批量上传目录中的所有文件（upload_all）
831
+
832
+ ``` ruby
833
+ @bucket.upload(path_or_dir, file_src_path, options = {}, &block)
834
+ ```
835
+
836
+ 参数：
837
+
838
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
839
+ | :--------------------------- | :-----: | :---------: | :--------------: | --------------------------------------- |
840
+ | path_or_dir | String\ | COS::COSDir | 是 | 无 |
841
+ | file_src_path | String | 是 | 无 | 本地文件夹路径 |
842
+ | options | Hash | 否 | 无 | |
843
+ | options[:skip_error] | Boolean | 否 | false | 是否跳过错误仍继续上传下一个文件 |
844
+ | options[:auto_create_folder] | Boolean | 否 | false | 自动创建远端目录 |
845
+ | options[:min_slice_size] | Integer | 否 | 10 * 1024 * 1024 | 完整上传最小文件大小,超过此大小将会使用分片多线程断点续传 |
846
+ | options[:upload_retry] | Integer | 否 | 10 | 上传重试次数 |
847
+ | options[:biz_attr] | String | 否 | 无 | 业务属性 |
848
+ | options[:disable_cpt] | Boolean | 否 | false | 是否禁用checkpoint，如禁用仍可通过服务端进行断点续传 |
849
+ | options[:threads] | Integer | 否 | 10 | 多线程上传线程数 |
850
+ | options[:slice_size] | Integer | 否 | 3 * 1024 * 1024 | 设置分片上传时每个分片的大小。默认为3 MB, 目前服务端最大限制也为3MB。 |
851
+ | options[:cpt_file] | String | 否 | 无 | 断点续传的checkpoint文件 |
852
+ | yield | Float | 否 | 无 | 上传进度百分比回调, 进度值是一个0-1之间的小数 |
853
+
854
+ 注：不包含子目录。SDK会自动使用分片断点续传上传大文件。
855
+
856
+ 返回：
857
+
858
+ ``` ruby
859
+ Array<COS::COSFile> # 详见目录操作（COS::COSFile）
860
+ ```
861
+
862
+ 示例：
863
+
864
+ ``` ruby
865
+ files = @bucket.upload_all('/test', '~/path') do |pr|
866
+ puts "上传进度 #{(pr*100).round(2)}%"
867
+ end
868
+ puts files
869
+ ```
18
870
 
19
- Or install it yourself as:
871
+ #### 4.3.16 获取资源个数详情（支持前缀搜索）（list_count）
20
872
 
21
- $ gem install cos
873
+ ``` ruby
874
+ @bucket.list_count(path = '', options = {})
875
+ ```
876
+
877
+ 参数：
878
+
879
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
880
+ | :--------------- | :----: | :--: | :--: | ---------------------------------------- |
881
+ | path | String | 否 | 空 | 目录路径, 如: 'path1', 'path1/path2', sdk会补齐末尾的 '/'。默认获取bucket根目录 |
882
+ | options | Hash | | | |
883
+ | options[:prefix] | String | 否 | 无 | 前缀搜索 |
884
+
885
+ 返回：
886
+
887
+ ``` ruby
888
+ Hash
889
+ {
890
+ :total => 5, # 目录及文件总数
891
+ :files => 2, # 文件总数
892
+ :dirs => 3, # 目录总数
893
+ }
894
+ ```
895
+
896
+ 示例：
897
+
898
+ ``` ruby
899
+ puts @bucket.list_count[:files]
900
+ ```
901
+
902
+ #### 4.3.17 获取资源个数（count, size）
903
+
904
+ ``` ruby
905
+ @bucket.count(path = '') # 别名 size
906
+ ```
22
907
 
23
- ## Usage
908
+ 参数：
24
909
 
25
- TODO: Write usage instructions here
910
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
911
+ | :--- | :----: | :--: | :--: | ---------------------------------------- |
912
+ | path | String | 否 | 空 | 目录路径, 如: 'path1', 'path1/path2', sdk会补齐末尾的 '/'。默认获取bucket根目录 |
26
913
 
27
- ## Development
914
+ 返回：
28
915
 
29
- After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
916
+ ``` ruby
917
+ Integer # 目录及文件总数
918
+ ```
919
+
920
+ 示例：
921
+
922
+ ``` ruby
923
+ puts @bucket.count
924
+ ```
30
925
 
31
- To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
926
+ #### 4.3.18 获取文件个数（count_files）
32
927
 
33
- ## Contributing
928
+ ``` ruby
929
+ @bucket.count_files(path = '')
930
+ ```
931
+
932
+ 参数：
933
+
934
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
935
+ | :--- | :----: | :--: | :--: | ---------------------------------------- |
936
+ | path | String | 否 | 空 | 目录路径, 如: 'path1', 'path1/path2', sdk会补齐末尾的 '/'。默认获取bucket根目录 |
937
+
938
+ 返回：
939
+
940
+ ``` ruby
941
+ Integer # 文件总数
942
+ ```
943
+
944
+ 示例：
945
+
946
+ ``` ruby
947
+ puts @bucket.count_files
948
+ ```
949
+
950
+ #### 4.3.19 获取目录个数（count_dirs）
951
+
952
+ ``` ruby
953
+ @bucket.count_dirs(path = '')
954
+ ```
955
+
956
+ 参数：
957
+
958
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
959
+ | :--- | :----: | :--: | :--: | ---------------------------------------- |
960
+ | path | String | 否 | 空 | 目录路径, 如: 'path1', 'path1/path2', sdk会补齐末尾的 '/'。默认获取bucket根目录 |
961
+
962
+ 返回：
963
+
964
+ ``` ruby
965
+ Integer # 目录总数
966
+ ```
967
+
968
+ 示例：
969
+
970
+ ``` ruby
971
+ puts @bucket.count_dirs
972
+ ```
973
+
974
+ ### 4.4 资源操作
975
+
976
+ #### 4.4.1 文件操作（COS::COSFile）
977
+
978
+ ##### 4.4.1.1 获取文件属性
979
+
980
+ ``` ruby
981
+ # 文件名称
982
+ puts file.name
983
+ # 文件格式化大小 1B 1KB 1.1MB 1.12GB...
984
+ puts file.format_size
985
+ ```
986
+
987
+ | 属性 | 类型 | 描述 |
988
+ | ------------------------- | ------- | --------------------------- |
989
+ | name | String | 名称 |
990
+ | path | String | 存储路径 |
991
+ | ctime | String | 创建时间unix时间戳 |
992
+ | mtime | String | 修改时间unix时间戳 |
993
+ | created_at | Time | 创建时间Time |
994
+ | updated_at | Time | 修改时间Time |
995
+ | biz_attr | String | 业务属性 |
996
+ | filesize（file_size, size） | Integer | 文件大小 |
997
+ | filelen | Integer | 已上传的文件大小 |
998
+ | sha | String | 文件sha1值 |
999
+ | access_url | String | 文件访问url |
1000
+ | type | String | 类型，固定为file |
1001
+ | format_size | String | 格式化文件大小 1B 1KB 1.1MB 1.12GB |
1002
+
1003
+ ##### 4.4.1.2 获取当前文件属性（刷新）（stat）
1004
+
1005
+ ``` ruby
1006
+ file.stat
1007
+ ```
1008
+
1009
+ 返回：
1010
+
1011
+ ``` ruby
1012
+ COS::COSFile
1013
+ ```
1014
+
1015
+ 示例：
1016
+
1017
+ ``` ruby
1018
+ puts file.stat.to_hash
1019
+ ```
1020
+
1021
+ ##### 4.4.1.3 更新当前文件属性（upadte）
1022
+
1023
+ ``` ruby
1024
+ file.update(biz_attr)
1025
+ ```
1026
+
1027
+ 参数：
1028
+
1029
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
1030
+ | :------- | :----: | :--: | :--: | ---- |
1031
+ | biz_attr | String | 是 | 无 | 业务属性 |
1032
+
1033
+ 示例：
1034
+
1035
+ ``` ruby
1036
+ file.update('new biz attr')
1037
+ ```
1038
+
1039
+ ##### 4.4.1.4 删除当前文件（delete）
1040
+
1041
+ ``` ruby
1042
+ file.delete
1043
+ ```
1044
+
1045
+ 注意：删除失败将抛出异常
1046
+
1047
+ 示例：
1048
+
1049
+ ``` ruby
1050
+ file.delete
1051
+ ```
1052
+
1053
+ ##### 4.4.1.5 删除当前文件（无异常）（delete!）
1054
+
1055
+ ``` ruby
1056
+ file.delete!
1057
+ ```
1058
+
1059
+ 注意：删除失败不会抛出异常，返回是否成功的bool值。
1060
+
1061
+ 返回：
1062
+
1063
+ ``` ruby
1064
+ Boolean
1065
+ ```
1066
+
1067
+ 示例：
1068
+
1069
+ ``` ruby
1070
+ puts file.delete!
1071
+ ```
1072
+
1073
+ ##### 4.4.1.6 判断当前文件是否存在（exist?，exists?）
1074
+
1075
+ ``` ruby
1076
+ file.exist? # 别名 exists?
1077
+ ```
1078
+
1079
+ 返回：
1080
+
1081
+ ``` ruby
1082
+ Boolean
1083
+ ```
1084
+
1085
+ 示例：
1086
+
1087
+ ``` ruby
1088
+ puts file.exist?
1089
+ ```
1090
+
1091
+ ##### 4.4.1.7 判断当前文件是否上传完成（complete?）
1092
+
1093
+ ``` ruby
1094
+ file.complete?
1095
+ ```
1096
+
1097
+ 返回：
1098
+
1099
+ ``` ruby
1100
+ Boolean
1101
+ ```
1102
+
1103
+ 示例：
1104
+
1105
+ ``` ruby
1106
+ puts file.complete?
1107
+ ```
1108
+
1109
+ ##### 4.4.1.8 获取当前文件的访问URL（url）
1110
+
1111
+ ``` ruby
1112
+ file.url(options = {})
1113
+ ```
1114
+
1115
+ 参数：
1116
+
1117
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
1118
+ | :----------------------- | :-----: | :--: | :---: | ------------------------------- |
1119
+ | options | Hash | | | |
1120
+ | options[:cname] | String | 否 | 无 | 获取使用cname的url。在cos控制台设置的cname域名 |
1121
+ | options[:https] | Boolean | 否 | false | 是否获取https的url |
1122
+ | options[:expire_seconds] | Integer | 否 | 600 | 签名有效时间(秒,私有读取bucket时需要) |
1123
+
1124
+ 返回：
1125
+
1126
+ ``` ruby
1127
+ String
1128
+ ```
1129
+
1130
+ 示例：
1131
+
1132
+ ``` ruby
1133
+ puts file.url(https: true, cname: 'static.domain.com')
1134
+ ```
1135
+
1136
+ ##### 4.4.1.9 下载当前文件（download）
1137
+
1138
+ ``` ruby
1139
+ file.download(file_store, options = {}, &block)
1140
+ ```
1141
+
1142
+ 参数：
1143
+
1144
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
1145
+ | :----------------------- | :-----: | :--: | :-----------: | ----------------------------- |
1146
+ | file_store | String | 是 | 无 | 本地文件存储路径 |
1147
+ | options | Hash | 否 | 无 | |
1148
+ | options[:disable_mkdir] | Boolean | 否 | true | 禁止自动创建本地文件夹, 默认会创建 |
1149
+ | options[:min_slice_size] | Integer | 否 | 5 * 10 * 1024 | 完整下载最小文件大小,超过此大小将会使用分片多线程断点续传 |
1150
+ | options[:download_retry] | Integer | 否 | 10 | 下载重试次数 |
1151
+ | options[:disable_cpt] | Boolean | 否 | false | 是否禁用checkpoint，如果禁用则不使用断点续传 |
1152
+ | yield | Float | 否 | 无 | 下载进度百分比回调, 进度值是一个0-1之间的小数 |
1153
+
1154
+ 注：支持私有访问资源下载，SDK会自动携带鉴权签名。SDK会自动使用分片断点续传下载大文件。
1155
+
1156
+ 返回：
1157
+
1158
+ ``` ruby
1159
+ String # 本地文件存储路径
1160
+ ```
1161
+
1162
+ 示例：
1163
+
1164
+ ``` ruby
1165
+ file = file.download('~/test/file1') do |p|
1166
+ puts "下载进度: #{(p*100).round(2)}%")
1167
+ end
1168
+ puts file
1169
+ ```
1170
+
1171
+ ##### 4.4.1.10 判断当前文件与本地文件是否相同
1172
+
1173
+ ``` ruby
1174
+ file.sha1_match?(file)
1175
+ ```
1176
+
1177
+ 参数：
1178
+
1179
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
1180
+ | :--- | :----: | :--: | :--: | ------ |
1181
+ | file | String | 是 | 无 | 本地文件路径 |
1182
+
1183
+ 返回：
1184
+
1185
+ ``` ruby
1186
+ Boolean
1187
+ ```
1188
+
1189
+ 示例：
1190
+
1191
+ ``` ruby
1192
+ puts file.sha1_match?('~/file1')
1193
+ ```
1194
+
1195
+
1196
+
1197
+ #### 4.4.2 目录操作（COS::COSDir）
1198
+
1199
+ ##### 4.4.2.1 获取目录属性
1200
+
1201
+ ``` ruby
1202
+ # 目录名称
1203
+ puts dir.name
1204
+ # 目录存储路径
1205
+ puts dir.path
1206
+ ```
1207
+
1208
+ | 属性 | 类型 | 描述 |
1209
+ | ---------- | ------ | ----------- |
1210
+ | name | String | 名称 |
1211
+ | path | String | 存储路径 |
1212
+ | ctime | String | 创建时间unix时间戳 |
1213
+ | mtime | String | 修改时间unix时间戳 |
1214
+ | created_at | Time | 创建时间Time |
1215
+ | updated_at | Time | 修改时间Time |
1216
+ | biz_attr | String | 业务属性 |
1217
+ | type | String | 类型，固定为dir |
1218
+
1219
+ ##### 4.4.2.2 列举当前目录（前缀搜索）（list，ls）
1220
+
1221
+ ``` ruby
1222
+ dir.list(options = {}) # 方法别名ls
1223
+ ```
1224
+
1225
+ 参数：
1226
+
1227
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
1228
+ | :---------------- | :-----: | :--: | :---: | ---------------------------------------- |
1229
+ | options | Hash | | | |
1230
+ | options[:prefix] | String | 否 | 无 | 搜索前缀，如果填写prefix, 则列出含此前缀的所有文件及目录 |
1231
+ | options[:num] | Integer | 否 | 20 | |
1232
+ | options[:pattern] | Symbol | 否 | :both | 获取模式，:dir_only 只获取目录, :file_only 只获取文件, 默认为 :both 全部获取 |
1233
+ | options[:order] | Symbol | 否 | :asc | 排序方式 :asc 正序, :desc 倒序 默认为 :asc |
1234
+
1235
+ 返回：
1236
+
1237
+ ``` ruby
1238
+ [Enumerator<Object>] 迭代器, 其中Object可能是COS::COSFile或COS::COSDir
1239
+ ```
1240
+
1241
+ 示例：
1242
+
1243
+ ``` ruby
1244
+ dir.list do |res|
1245
+ if res.is_a?(COS::COSDir)
1246
+ puts "Dir: #{res.name} #{res.path}"
1247
+ else
1248
+ puts "File: #{res.name} #{res.format_size}"
1249
+ end
1250
+ end
1251
+ ```
1252
+
1253
+ ##### 4.4.2.3 创建子目录（create_folder，mkdir）
1254
+
1255
+ ``` ruby
1256
+ dir.create_folder(dir_name, options = {}) # 方法别名mkdir
1257
+ ```
1258
+
1259
+ 参数：
1260
+
1261
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
1262
+ | :----------------- | :----: | :--: | :--: | --------------------- |
1263
+ | dir_name | String | 是 | 无 | 需要创建的子目录名称，不包含父系目录路径。 |
1264
+ | options | Hash | | | |
1265
+ | options[:biz_attr] | String | 否 | 无 | 目录属性, 业务端维护 |
1266
+
1267
+ 返回：
1268
+
1269
+ ``` ruby
1270
+ COS::COSDir
1271
+ ```
1272
+
1273
+ 示例：
1274
+
1275
+ ``` ruby
1276
+ dir.create_folder("test_dir2", biz_attr: '测试目录1-2')
1277
+ ```
1278
+
1279
+ ##### 4.4.2.4 上传文件至当前目录（upload）
1280
+
1281
+ ``` ruby
1282
+ dir.upload(file_name, file_src, options = {}, &block)
1283
+ ```
1284
+
1285
+ 参数：
1286
+
1287
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
1288
+ | :--------------------------- | :-----: | :--: | :--------------: | --------------------------------------- |
1289
+ | file_name | String | 是 | 无 | 存储文件名 |
1290
+ | file_src | String | 是 | 无 | 本地文件路径 |
1291
+ | options | Hash | 否 | 无 | |
1292
+ | options[:auto_create_folder] | Boolean | 否 | false | 自动创建远端目录 |
1293
+ | options[:min_slice_size] | Integer | 否 | 10 * 1024 * 1024 | 完整上传最小文件大小,超过此大小将会使用分片多线程断点续传 |
1294
+ | options[:upload_retry] | Integer | 否 | 10 | 上传重试次数 |
1295
+ | options[:biz_attr] | String | 否 | 无 | 业务属性 |
1296
+ | options[:disable_cpt] | Boolean | 否 | false | 是否禁用checkpoint，如禁用仍可通过服务端进行断点续传 |
1297
+ | options[:threads] | Integer | 否 | 10 | 多线程上传线程数 |
1298
+ | options[:slice_size] | Integer | 否 | 3 * 1024 * 1024 | 设置分片上传时每个分片的大小。默认为3 MB, 目前服务端最大限制也为3MB。 |
1299
+ | options[:cpt_file] | String | 否 | 无 | 断点续传的checkpoint文件 |
1300
+ | yield | Float | 否 | 无 | 上传进度百分比回调, 进度值是一个0-1之间的小数 |
1301
+
1302
+ 注：SDK会自动使用分片断点续传上传大文件。
1303
+
1304
+ 返回：
1305
+
1306
+ ``` ruby
1307
+ COS::COSFile
1308
+ ```
1309
+
1310
+ 示例：
1311
+
1312
+ ``` ruby
1313
+ file = dir.upload('file1.txt', '~/test.txt') do |pr|
1314
+ puts "上传进度 #{(pr*100).round(2)}%"
1315
+ end
1316
+ puts file.name
1317
+ puts file.format_size
1318
+ puts file.url
1319
+ ```
1320
+
1321
+ ##### 4.4.2.5 批量上传本地目录中的所有文件至当前目录（upload_all）
1322
+
1323
+ ``` ruby
1324
+ dir.upload(file_src_path, options = {}, &block)
1325
+ ```
1326
+
1327
+ 参数：
1328
+
1329
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
1330
+ | :--------------------------- | :-----: | :--: | :--------------: | --------------------------------------- |
1331
+ | file_src_path | String | 是 | 无 | 本地文件夹路径 |
1332
+ | options | Hash | 否 | 无 | |
1333
+ | options[:skip_error] | Boolean | 否 | false | 是否跳过错误仍继续上传下一个文件 |
1334
+ | options[:auto_create_folder] | Boolean | 否 | false | 自动创建远端目录 |
1335
+ | options[:min_slice_size] | Integer | 否 | 10 * 1024 * 1024 | 完整上传最小文件大小,超过此大小将会使用分片多线程断点续传 |
1336
+ | options[:upload_retry] | Integer | 否 | 10 | 上传重试次数 |
1337
+ | options[:biz_attr] | String | 否 | 无 | 业务属性 |
1338
+ | options[:disable_cpt] | Boolean | 否 | false | 是否禁用checkpoint，如禁用仍可通过服务端进行断点续传 |
1339
+ | options[:threads] | Integer | 否 | 10 | 多线程上传线程数 |
1340
+ | options[:slice_size] | Integer | 否 | 3 * 1024 * 1024 | 设置分片上传时每个分片的大小。默认为3 MB, 目前服务端最大限制也为3MB。 |
1341
+ | options[:cpt_file] | String | 否 | 无 | 断点续传的checkpoint文件 |
1342
+ | yield | Float | 否 | 无 | 上传进度百分比回调, 进度值是一个0-1之间的小数 |
1343
+
1344
+ 注：不包含子目录。SDK会自动使用分片断点续传上传大文件。
1345
+
1346
+ 返回：
1347
+
1348
+ ``` ruby
1349
+ Array<COS::COSFile>
1350
+ ```
1351
+
1352
+ 示例：
1353
+
1354
+ ``` ruby
1355
+ files = dir.upload_all('~/path') do |pr|
1356
+ puts "上传进度 #{(pr*100).round(2)}%"
1357
+ end
1358
+ ```
1359
+
1360
+ ##### 4.4.2.6 批量下载当前目录下的所有文件（download_all）
1361
+
1362
+ ``` ruby
1363
+ dir.download_all(file_store_path, options = {}, &block)
1364
+ ```
1365
+
1366
+ 参数：
1367
+
1368
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
1369
+ | :----------------------- | :-----: | :--: | :-----------: | ----------------------------- |
1370
+ | file_store_path | String | 是 | 无 | 本地文件存储目录 |
1371
+ | options | Hash | 否 | 无 | |
1372
+ | options[:disable_mkdir] | Boolean | 否 | true | 禁止自动创建本地文件夹, 默认会创建 |
1373
+ | options[:min_slice_size] | Integer | 否 | 5 * 10 * 1024 | 完整下载最小文件大小,超过此大小将会使用分片多线程断点续传 |
1374
+ | options[:download_retry] | Integer | 否 | 10 | 下载重试次数 |
1375
+ | options[:disable_cpt] | Boolean | 否 | false | 是否禁用checkpoint，如果禁用则不使用断点续传 |
1376
+ | yield | Float | 否 | 无 | 下载进度百分比回调, 进度值是一个0-1之间的小数 |
1377
+
1378
+ 注：不包含子目录。支持私有访问资源下载，SDK会自动携带鉴权签名。SDK会自动使用分片断点续传下载大文件。
1379
+
1380
+ 返回：
1381
+
1382
+ ``` ruby
1383
+ Array<String> # 本地文件存储路径数组
1384
+ ```
1385
+
1386
+ 示例：
1387
+
1388
+ ``` ruby
1389
+ files = dir.download_all('~/test/path/') do |p|
1390
+ puts "下载进度: #{(p*100).round(2)}%")
1391
+ end
1392
+ ```
1393
+
1394
+ ##### 4.4.2.7 当前目录属性（刷新）（stat）
1395
+
1396
+ ``` ruby
1397
+ dir.stat
1398
+ ```
1399
+
1400
+ 返回：
1401
+
1402
+ ``` ruby
1403
+ COS::COSDir
1404
+ ```
1405
+
1406
+ 示例：
1407
+
1408
+ ``` ruby
1409
+ puts dir.stat.to_hash
1410
+ ```
1411
+
1412
+ ##### 4.4.2.8 更新当前目录属性（upadte）
1413
+
1414
+ ``` ruby
1415
+ dir.update(biz_attr)
1416
+ ```
1417
+
1418
+ 参数：
1419
+
1420
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
1421
+ | :------- | :----: | :--: | :--: | ---- |
1422
+ | biz_attr | String | 是 | 无 | 业务属性 |
1423
+
1424
+ 示例：
1425
+
1426
+ ``` ruby
1427
+ dir.update('new biz attr')
1428
+ ```
1429
+
1430
+ ##### 4.4.2.9 删除当前目录（delete）
1431
+
1432
+ ``` ruby
1433
+ dir.delete
1434
+ ```
1435
+
1436
+ 注意：非空目录或根目录无法删除，会抛出异常
1437
+
1438
+ 示例：
1439
+
1440
+ ``` ruby
1441
+ dir.delete
1442
+ ```
1443
+
1444
+ ##### 4.4.2.10 删除当前目录（无异常）（delete!）
1445
+
1446
+ ``` ruby
1447
+ dir.delete!
1448
+ ```
1449
+
1450
+ 注意：非空目录或根目录无法删除，返回是否成功的bool值。
1451
+
1452
+ 返回：
1453
+
1454
+ ``` ruby
1455
+ Boolean
1456
+ ```
1457
+
1458
+ 示例：
1459
+
1460
+ ``` ruby
1461
+ puts dir.delete!
1462
+ ```
1463
+
1464
+ ##### 4.4.2.11 判断当前目录是否为空（empty?）
1465
+
1466
+ ``` ruby
1467
+ dir.empty?
1468
+ ```
1469
+
1470
+ 返回：
1471
+
1472
+ ``` ruby
1473
+ Boolean
1474
+ ```
1475
+
1476
+ 示例：
1477
+
1478
+ ``` ruby
1479
+ puts dir.empty?
1480
+ ```
1481
+
1482
+ ##### 4.4.2.12 判断当前目录是否存在（exist?，exists?）
1483
+
1484
+ ``` ruby
1485
+ dir.exist? # 别名 exists?
1486
+ ```
1487
+
1488
+ 返回：
1489
+
1490
+ ``` ruby
1491
+ Boolean
1492
+ ```
1493
+
1494
+ 示例：
1495
+
1496
+ ``` ruby
1497
+ puts dir.exist?
1498
+ ```
1499
+
1500
+ ##### 4.4.2.13 获取当前目录下的Object树形结构（tree）
1501
+
1502
+ ``` ruby
1503
+ dir.tree(options = {})
1504
+ ```
1505
+
1506
+ 参数：
1507
+
1508
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
1509
+ | :-------------- | :-----: | :--: | :--: | ---------- |
1510
+ | options | Hash | | | |
1511
+ | options[:depth] | Integer | 否 | 5 | 子目录深度,默认为5 |
1512
+
1513
+ 返回：
1514
+
1515
+ ```
1516
+ {
1517
+ :resource => Object<COS::COSDir>,
1518
+ :children => [
1519
+ {:resource => Object<COS::COSDir>, :children => [...]},
1520
+ {:resource => Object<COS::COSFile>, :children => [...]},
1521
+ ...
1522
+ ]
1523
+ }
1524
+ ```
1525
+
1526
+ 示例：
1527
+
1528
+ ``` ruby
1529
+ tree = dir.tree
1530
+ puts tree[:resource].name
1531
+ tree[:children].each do |r|
1532
+ puts r[:resource].name
1533
+ end
1534
+ ```
1535
+
1536
+ ##### 4.4.2.14 获取当前目录下的Hash树形结构（hash_tree）
1537
+
1538
+ ``` ruby
1539
+ dir.hash_tree(options = {})
1540
+ ```
1541
+
1542
+ 参数：
1543
+
1544
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
1545
+ | :-------------- | :-----: | :--: | :--: | ---------- |
1546
+ | options | Hash | | | |
1547
+ | options[:depth] | Integer | 否 | 5 | 子目录深度,默认为5 |
1548
+
1549
+ 返回：
1550
+
1551
+ ```
1552
+ {
1553
+ :resource => {:name...},
1554
+ :children => [
1555
+ {:resource => {:name...}, :children => [...]},
1556
+ {:resource => {:name...}, :children => [...]},
1557
+ ...
1558
+ ]
1559
+ }
1560
+ ```
1561
+
1562
+ 示例：
1563
+
1564
+ ``` ruby
1565
+ tree = dir.hash_tree
1566
+ puts tree[:resource][:name]
1567
+ tree[:children].each do |r|
1568
+ puts r[:resource][:name]
1569
+ end
1570
+ puts tree.to_json # 可直接转为json
1571
+ ```
1572
+
1573
+ ##### 4.4.2.15 获取当前目录下的资源个数详情（支持前缀搜索）（list_count）
1574
+
1575
+ ``` ruby
1576
+ dir.list_count(options = {})
1577
+ ```
1578
+
1579
+ 参数：
1580
+
1581
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
1582
+ | :--------------- | :----: | :--: | :--: | ---- |
1583
+ | options | Hash | | | |
1584
+ | options[:prefix] | String | 否 | 无 | 前缀搜索 |
1585
+
1586
+ 返回：
1587
+
1588
+ ``` ruby
1589
+ Hash
1590
+ {
1591
+ :total => 5, # 目录及文件总数
1592
+ :files => 2, # 文件总数
1593
+ :dirs => 3, # 目录总数
1594
+ }
1595
+ ```
1596
+
1597
+ 示例：
1598
+
1599
+ ``` ruby
1600
+ puts dir.list_count[:files]
1601
+ ```
1602
+
1603
+ ##### 4.4.2.16 获取当前目录下的资源个数（count, size）
1604
+
1605
+ ``` ruby
1606
+ dir.count # 别名 size
1607
+ ```
1608
+
1609
+ 返回：
1610
+
1611
+ ``` ruby
1612
+ Integer # 目录及文件总数
1613
+ ```
1614
+
1615
+ 示例：
1616
+
1617
+ ``` ruby
1618
+ puts dir.count
1619
+ ```
1620
+
1621
+ ##### 4.4.2.17 获取当前目录下的文件个数（count_files）
1622
+
1623
+ ``` ruby
1624
+ dir.count_files
1625
+ ```
1626
+
1627
+ 返回：
1628
+
1629
+ ``` ruby
1630
+ Integer # 文件总数
1631
+ ```
1632
+
1633
+ 示例：
1634
+
1635
+ ``` ruby
1636
+ puts dir.count_files
1637
+ ```
1638
+
1639
+ ##### 4.4.2.18 获取当前目录下的子目录个数（count_dirs）
1640
+
1641
+ ``` ruby
1642
+ dir.count_dirs
1643
+ ```
1644
+
1645
+ 返回：
1646
+
1647
+ ``` ruby
1648
+ Integer # 目录总数
1649
+ ```
1650
+
1651
+ 示例：
1652
+
1653
+ ``` ruby
1654
+ puts dir.count_dirs
1655
+ ```
1656
+
1657
+
1658
+
1659
+ ### 4.5 签名操作（COS::Signature）
1660
+
1661
+ 腾讯移动服务通过签名来验证请求的合法性。开发者通过将签名授权给客户端，使其具备上传下载及管理指定资源的能力。签名分为**多次有效签名**和**单次有效签名**
1662
+
1663
+ 🔍具体适用场景参见[签名适用场景](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#4_.E7.AD.BE.E5.90.8D.E9.80.82.E7.94.A8.E5.9C.BA.E6.99.AF)
1664
+
1665
+ #### 4.5.1 获取单次有效签名（once）
1666
+
1667
+ 签名中绑定文件fileid，此签名只可使用一次，且只能应用于被绑定的文件。
1668
+
1669
+ ``` ruby
1670
+ puts @client.signature.once(bucket_name, path)
1671
+ # path 为操作资源的路径
1672
+ ```
1673
+
1674
+
1675
+
1676
+ #### 4.5.2 获取多次有效签名（multiple）
1677
+
1678
+ 签名中不绑定文件fileid，有效期内此签名可多次使用，有效期最长可设置三个月。
1679
+
1680
+ ``` ruby
1681
+ puts @client.signature.multiple(bucket_name, expire_seconds)
1682
+ # expire_seconds 为从获取时间起得有效时间单位秒，必须大于0。
1683
+ ```
1684
+
1685
+
1686
+
1687
+ ## 5 底层API（COS::API）
1688
+
1689
+ ### 5.1 创建目录(create_folder)
1690
+
1691
+ ``` ruby
1692
+ @client.api.create_folder(path, options = {})
1693
+ ```
1694
+
1695
+ 参数：
1696
+
1697
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
1698
+ | :----------------- | :----: | :--: | :--: | ---------------------------------------- |
1699
+ | path | String | 是 | 无 | 需要创建的目录路径, 如: 'path1', 'path1/path2', sdk会补齐末尾的 '/'。 |
1700
+ | options | Hash | | | |
1701
+ | options[:biz_attr] | String | 否 | 无 | 目录属性, 业务端维护 |
1702
+ | options[:bucket] | String | 否 | 无 | bucket名称，如未配置default_bucket则必须制定 |
1703
+
1704
+ 返回：
1705
+
1706
+ `Hash`
1707
+
1708
+ | 参数名 | 类型 | 必须 | 参数描述 |
1709
+ | :------------ | :----: | :--: | :---------: |
1710
+ | ctime | String | 是 | 创建时间Unix时间戳 |
1711
+ | resource_path | String | 是 | 创建的资源路径 |
1712
+
1713
+ 示例：
1714
+
1715
+ ``` ruby
1716
+ puts @client.api.create_folder("test_dir5", biz_attr: '测试目录5')
1717
+ ```
1718
+
1719
+
1720
+
1721
+ ### 5.2 目录列表（前缀搜索）(list)
1722
+
1723
+ ``` ruby
1724
+ @client.api.list(path, options = {})
1725
+ ```
1726
+
1727
+ 参数：
1728
+
1729
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
1730
+ | :---------------- | :-----: | :--: | :---: | ---------------------------------------- |
1731
+ | path | String | 是 | 否 | 需要列举的目录路径, 如: 'path1', 'path1/path2', sdk会补齐末尾的 '/'。 |
1732
+ | options | Hash | | | |
1733
+ | options[:prefix] | String | 否 | 无 | 搜索前缀，如果填写prefix, 则列出含此前缀的所有文件及目录 |
1734
+ | options[:num] | Integer | 否 | 20 | |
1735
+ | options[:pattern] | Symbol | 否 | :both | 获取模式，:dir_only 只获取目录, :file_only 只获取文件, 默认为 :both 全部获取 |
1736
+ | options[:order] | Symbol | 否 | :asc | 排序方式 :asc 正序, :desc 倒序 默认为 :asc |
1737
+ | options[:context] | String | 否 | 空 | 若需要翻页，需要将前一页返回值中的context透传到参数中 |
1738
+ | options[:bucket] | String | 否 | 无 | bucket名称，如未配置default_bucket则必须制定 |
1739
+
1740
+ 返回：
1741
+
1742
+ `Hash`
1743
+
1744
+ | 参数名 | 类型 | 必须 | 参数描述 |
1745
+ | :-------------- | :---------: | :--: | :--------------------------------------: |
1746
+ | context | String | 是 | 透传字段,用于翻页,需要往前/往后翻页则透传回来 |
1747
+ | has_more | Boolean | 是 | 是否有内容可以继续往前/往后翻页 |
1748
+ | dircount | Integer | 是 | 子目录数量(总) |
1749
+ | filecount | Integer | 是 | 子文件数量(总) |
1750
+ | infos | Array<Hash> | 是 | 列表结果(可能为空) |
1751
+ | 子属性 :name | String | 是 | 目录名/文件名 |
1752
+ | 子属性 :biz_attr | String | 是 | 目录/文件属性，业务端维护 |
1753
+ | 子属性 :filesize | Integer | 否 | 文件大小(当类型为文件时返回) |
1754
+ | 子属性 :filelen | Integer | 否 | 文件已传输大小(通过与filesize对比可知文件传输进度,当类型为文件时返回) |
1755
+ | 子属性 :sha | String | 否 | 文件sha1(当类型为文件时返回) |
1756
+ | 子属性 :ctime | String | 是 | 创建时间(Unix时间戳) |
1757
+ | 子属性 :mtime | String | 是 | 修改时间(Unix时间戳) |
1758
+ | 子属性 :access_url | String | 否 | 生成的资源可访问的url(当类型为文件时返回) |
1759
+
1760
+ 示例：
1761
+
1762
+ ``` ruby
1763
+ puts @client.api.list('/test', pattern: :dir_only, order: :desc, prefix: 'abc', context: '')
1764
+ ```
1765
+
1766
+
1767
+
1768
+ ### 5.3 上传文件（完整上传）(upload)
1769
+
1770
+ ``` ruby
1771
+ @client.api.upload(path, file_name, file_src, options = {})
1772
+ ```
1773
+
1774
+ 参数：
1775
+
1776
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
1777
+ | :----------------- | :----: | :--: | :--: | ---------------------------------------- |
1778
+ | path | String | 是 | 无 | 目录路径, 如: '/', 'path1', 'path1/path2', sdk会补齐末尾的 '/' |
1779
+ | file_name | String | 是 | 无 | 存储文件名 |
1780
+ | file_src | String | 是 | 无 | 本地文件路径 |
1781
+ | options | Hash | 否 | 无 | |
1782
+ | options[:biz_attr] | String | 否 | 无 | 文件属性, 业务端维护 |
1783
+ | options[:bucket] | String | 否 | 无 | bucket名称，如未配置default_bucket则必须制定 |
1784
+
1785
+ 返回：
1786
+
1787
+ `Hash`
1788
+
1789
+ | 参数名 | 类型 | 必须 | 参数描述 |
1790
+ | :------------ | :----: | :--: | :--------: |
1791
+ | access_url | String | 是 | 生成的文件下载url |
1792
+ | url | String | 是 | 操作文件的url |
1793
+ | resource_path | String | 是 | 资源路径 |
1794
+
1795
+ 示例：
1796
+
1797
+ ``` ruby
1798
+ puts @client.api.upload('/test', 'file1.txt', '~/test.txt')
1799
+ ```
1800
+
1801
+
1802
+
1803
+ ### 5.4 上传文件（分片上传）(upload_slice)
1804
+
1805
+ ``` ruby
1806
+ @client.api.upload_slice(path, file_name, file_src, options = {})
1807
+ ```
1808
+
1809
+ 参数：
1810
+
1811
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
1812
+ | :-------------------- | :-----: | :--: | :-------------: | ---------------------------------------- |
1813
+ | path | String | 是 | 无 | 目录路径, 如: '/', 'path1', 'path1/path2', sdk会补齐末尾的 '/' |
1814
+ | file_name | String | 是 | 无 | 存储文件名 |
1815
+ | file_src | String | 是 | 无 | 本地文件路径 |
1816
+ | options | Hash | 否 | 无 | |
1817
+ | options[:biz_attr] | String | 否 | 无 | 业务属性 |
1818
+ | options[:disable_cpt] | Boolean | 否 | false | 是否禁用checkpoint，如禁用仍可通过服务端进行断点续传 |
1819
+ | options[:threads] | Integer | 否 | 10 | 多线程上传线程数 |
1820
+ | options[:slice_size] | Integer | 否 | 3 * 1024 * 1024 | 设置分片上传时每个分片的大小。默认为3 MB, 目前服务端最大限制也为3MB。 |
1821
+ | options[:cpt_file] | String | 否 | 无 | 断点续传的checkpoint文件 |
1822
+ | options[:bucket] | String | 否 | 无 | bucket名称，如未配置default_bucket则必须制定 |
1823
+ | yield | Float | 否 | 无 | 上传进度百分比回调, 进度值是一个0-1之间的小数 |
1824
+
1825
+ 返回：
1826
+
1827
+ `Hash`
1828
+
1829
+ | 参数名 | 类型 | 必须 | 参数描述 |
1830
+ | :------------ | :----: | :--: | :--------: |
1831
+ | access_url | String | 是 | 生成的文件下载url |
1832
+ | url | String | 是 | 操作文件的url |
1833
+ | resource_path | String | 是 | 资源路径 |
1834
+
1835
+ 示例：
1836
+
1837
+ ``` ruby
1838
+ puts @client.api.upload_slice('/test', 'file1.txt', '~/test.txt') do |pr|
1839
+ puts "上传进度 #{(pr*100).round(2)}%"
1840
+ end
1841
+ ```
1842
+
1843
+
1844
+
1845
+ ### 5.5 更新文件、目录属性(update)
1846
+
1847
+ ``` ruby
1848
+ @client.api.update(path, biz_attr, options = {})
1849
+ ```
1850
+
1851
+ 参数：
1852
+
1853
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
1854
+ | :--------------- | :----: | :--: | :--: | ---------------------------------------- |
1855
+ | path | String | 是 | 无 | 需要创建的目录路径, 如: 'path1', 'path1/path2', sdk会补齐末尾的 '/'。 |
1856
+ | biz_attr | String | 是 | 无 | 目录属性, 业务端维护 |
1857
+ | options | Hash | | | |
1858
+ | options[:bucket] | String | 否 | 无 | bucket名称，如未配置default_bucket则必须制定 |
1859
+
1860
+ 返回：无
1861
+
1862
+ 示例：
1863
+
1864
+ ``` ruby
1865
+ @client.api.update('test/file1', 'new biz attr')
1866
+ ```
1867
+
1868
+ ### 5.6 删除文件、目录(delete)
1869
+
1870
+ ``` ruby
1871
+ @client.api.delete(path, options = {})
1872
+ ```
1873
+
1874
+ 参数：
1875
+
1876
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
1877
+ | :--------------- | :----: | :--: | :--: | ---------------------------------------- |
1878
+ | path | String | 是 | 无 | 需要创建的目录路径, 如: 'path1', 'path1/path2', sdk会补齐末尾的 '/'。 |
1879
+ | options | Hash | | | |
1880
+ | options[:bucket] | String | 否 | 无 | bucket名称，如未配置default_bucket则必须制定 |
1881
+
1882
+ 返回：无
1883
+
1884
+ 示例：
1885
+
1886
+ ``` ruby
1887
+ @client.api.delete('test/file1')
1888
+ ```
1889
+
1890
+ ### 5.7 获取文件或目录属性(stat)
1891
+
1892
+ ``` ruby
1893
+ @client.api.update(path, options = {})
1894
+ ```
1895
+
1896
+ 参数：
1897
+
1898
+ | | 类型 | 必须 | 默认值 | 参数描述 |
1899
+ | :--------------- | :----: | :--: | :--: | ---------------------------------------- |
1900
+ | path | String | 是 | 无 | 需要创建的目录路径, 如: 'path1', 'path1/path2', sdk会补齐末尾的 '/'。 |
1901
+ | options | Hash | | | |
1902
+ | options[:bucket] | String | 否 | 无 | bucket名称，如未配置default_bucket则必须制定 |
1903
+
1904
+ 返回：
1905
+
1906
+ `Hash`
1907
+
1908
+ | 参数名 | 类型 | 必须 | 参数描述 |
1909
+ | :--------- | :-----: | :--: | :--------------------------------------: |
1910
+ | name | String | 是 | 目录名/文件名 |
1911
+ | biz_attr | String | 是 | 目录/文件属性，业务端维护 |
1912
+ | filesize | Integer | 否 | 文件大小(当类型为文件时返回) |
1913
+ | filelen | Integer | 否 | 文件已传输大小(通过与filesize对比可知文件传输进度,当类型为文件时返回) |
1914
+ | sha | String | 否 | 文件sha1(当类型为文件时返回) |
1915
+ | ctime | String | 是 | 创建时间(Unix时间戳) |
1916
+ | mtime | String | 是 | 修改时间(Unix时间戳) |
1917
+ | access_url | String | 否 | 生成的资源可访问的url(当类型为文件时返回) |
1918
+
1919
+ 示例：
1920
+
1921
+ ``` ruby
1922
+ puts @client.api.stat('/test/file')
1923
+ ```
1924
+
1925
+ ### 5.8下载文件
1926
+
1927
+ ``` ruby
1928
+ @client.api.download(access_url, file_store, options = {})
1929
+ ```
1930
+
1931
+ 参数：
1932
+
1933
+ | 参数名 | 类型 | 必须 | 默认值 | 参数描述 |
1934
+ | :---------------- | :----: | :--: | :--: | -------------------------------- |
1935
+ | access_url | String | 是 | 无 | 资源的下载URL地址可以从list,stat接口中获取 |
1936
+ | file_store | String | 是 | 无 | 本地文件存储路径 |
1937
+ | options | Hash | 否 | 无 | |
1938
+ | options[:bucket] | String | 否 | 无 | bucket名称，如未配置default_bucket则必须制定 |
1939
+ | options[:headers] | Hash | 否 | 无 | 设置下载请求头,如:rang |
1940
+
1941
+ 示例：
1942
+
1943
+ ``` ruby
1944
+ @client.api.download('/test/file', '~/test.txt')
1945
+ ```
1946
+
1947
+
1948
+
1949
+ ## 6 CLI命令行工具
1950
+
1951
+ SDK提供了一套包含所有API调用的CLI工具，方便开发者更好的调试与更便捷的使用COS。
1952
+
1953
+ 获取CLI指令列表：
1954
+
1955
+ ``` shell
1956
+ $ cos
1957
+
1958
+ COS Ruby SDK CLI commands:
1959
+ cos count [PATH] # 获取文件及目录数
1960
+ cos count_dirs [PATH] # 获取目录数
1961
+ cos count_files [PATH] # 获取文件数
1962
+ cos create_folder [PATH] # 创建目录
1963
+ cos delete [PATH] # 删除目录或文件
1964
+ cos download [PATH] [FILE_STORE] # 下载文件(大文件自动分片下载,支持多线程断点续传)
1965
+ cos download_all [PATH] [FILE_STORE_PATH] # 下载目录下的所有文件(不含子目录)
1966
+ cos is_exist [PATH] # 判断文件或目录是否存在
1967
+ cos help [COMMAND] # 获取指令的使用帮助
1968
+ cos init # 创建默认配置文件
1969
+ cos is_complete [PATH] # 判断文件是否上传完整
1970
+ cos is_empty [PATH] # 判断目录是否为空
1971
+ cos list [PATH] # 获取目录列表
1972
+ cos sign_multi [EXPIRE] # 生成多次可用签名
1973
+ cos sign_once [PATH] # 生成单次可用签名
1974
+ cos stat [PATH] # 获取目录或文件信息
1975
+ cos tree [PATH] # 显示树形结构
1976
+ cos update [PATH] [BIZ_ATTR] # 更新业务属性
1977
+ cos upload [PATH] [FILE_NAME] [FILE_SRC] # 上传文件(大文件自动分片上传,支持多线程断点续传)
1978
+ cos upload_all [PATH] [FILE_SRC_PATH] # 上传目录下的所有文件(不含子目录)
1979
+ cos url [PATH] # 获取文件的访问URL
1980
+
1981
+ Options:
1982
+ -c, [--config=CONFIG] # 加载配置文件
1983
+ # Default: ~/.cos.yml
1984
+ -b, [--bucket=BUCKET] # 指定Bucket
1985
+ ```
1986
+
1987
+ 获取指令的详细参数如：
1988
+
1989
+ ``` shell
1990
+ $ cos help upload
1991
+
1992
+ Usage:
1993
+ cos upload [PATH] [FILE_NAME] [FILE_SRC]
1994
+
1995
+ Options:
1996
+ -r, [--biz-attr=BIZ_ATTR] # 业务属性
1997
+ -m, [--min-slice-size=bytes] # 最小完整上传大小
1998
+ -f, [--auto-create-folder], [--no-auto-create-folder] # 自动创建目录
1999
+ -d, [--disable-cpt], [--no-disable-cpt] # 禁用断点续传(分片上传时有效)
2000
+ -t, [--threads=N] # 线程数(分片上传时有效)
2001
+ -n, [--upload-retry=N] # 重试次数(分片上传时有效)
2002
+ -s, [--slice-size=N] # 分片上传时每个分片的大小(分片上传时有效)
2003
+ -e, [--cpt-file=CPT_FILE] # 指定断点续传记录(分片上传时有效)
2004
+ -c, [--config=CONFIG] # 加载配置文件
2005
+ # Default: ~/.cos.yml
2006
+ -b, [--bucket=BUCKET] # 指定Bucket
2007
+
2008
+ 上传文件(大文件自动分片上传,支持多线程上传,断点续传)
2009
+ ```
2010
+
2011
+ 初始化创建配置文件：(默认创建于`~/.cos.yml`)
2012
+
2013
+ ``` shell
2014
+ $ cos init
2015
+ ```
2016
+
2017
+ 使用CLI:
2018
+
2019
+ ``` shell
2020
+ $ cos upload path/path2 file1 ~/file1
2021
+ ```
2022
+
2023
+ ## 7 运行测试
2024
+
2025
+ ```
2026
+ rspec
2027
+ ```
34
2028
 
35
- Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/cos.
2029
+ 或
36
2030
 
2031
+ ```
2032
+ bundle exec rake spec
2033
+ ```