cos 0.1.0 → 0.1.1

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.
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
+ ```