aliyun-oss-ruby-sdk 0.4.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +7 -0
- data/CHANGELOG.md +95 -0
- data/README.md +423 -0
- data/examples/aliyun/oss/bucket.rb +144 -0
- data/examples/aliyun/oss/callback.rb +61 -0
- data/examples/aliyun/oss/object.rb +182 -0
- data/examples/aliyun/oss/resumable_download.rb +42 -0
- data/examples/aliyun/oss/resumable_upload.rb +49 -0
- data/examples/aliyun/oss/streaming.rb +124 -0
- data/examples/aliyun/oss/using_sts.rb +48 -0
- data/examples/aliyun/sts/assume_role.rb +59 -0
- data/lib/aliyun_sdk/common.rb +6 -0
- data/lib/aliyun_sdk/common/exception.rb +18 -0
- data/lib/aliyun_sdk/common/logging.rb +46 -0
- data/lib/aliyun_sdk/common/struct.rb +56 -0
- data/lib/aliyun_sdk/oss.rb +16 -0
- data/lib/aliyun_sdk/oss/bucket.rb +661 -0
- data/lib/aliyun_sdk/oss/client.rb +106 -0
- data/lib/aliyun_sdk/oss/config.rb +39 -0
- data/lib/aliyun_sdk/oss/download.rb +255 -0
- data/lib/aliyun_sdk/oss/exception.rb +108 -0
- data/lib/aliyun_sdk/oss/http.rb +338 -0
- data/lib/aliyun_sdk/oss/iterator.rb +92 -0
- data/lib/aliyun_sdk/oss/multipart.rb +74 -0
- data/lib/aliyun_sdk/oss/object.rb +15 -0
- data/lib/aliyun_sdk/oss/protocol.rb +1499 -0
- data/lib/aliyun_sdk/oss/struct.rb +208 -0
- data/lib/aliyun_sdk/oss/upload.rb +238 -0
- data/lib/aliyun_sdk/oss/util.rb +89 -0
- data/lib/aliyun_sdk/sts.rb +9 -0
- data/lib/aliyun_sdk/sts/client.rb +38 -0
- data/lib/aliyun_sdk/sts/config.rb +22 -0
- data/lib/aliyun_sdk/sts/exception.rb +53 -0
- data/lib/aliyun_sdk/sts/protocol.rb +130 -0
- data/lib/aliyun_sdk/sts/struct.rb +64 -0
- data/lib/aliyun_sdk/sts/util.rb +48 -0
- data/lib/aliyun_sdk/version.rb +7 -0
- data/spec/aliyun/oss/bucket_spec.rb +597 -0
- data/spec/aliyun/oss/client/bucket_spec.rb +554 -0
- data/spec/aliyun/oss/client/client_spec.rb +297 -0
- data/spec/aliyun/oss/client/resumable_download_spec.rb +220 -0
- data/spec/aliyun/oss/client/resumable_upload_spec.rb +413 -0
- data/spec/aliyun/oss/http_spec.rb +83 -0
- data/spec/aliyun/oss/multipart_spec.rb +686 -0
- data/spec/aliyun/oss/object_spec.rb +785 -0
- data/spec/aliyun/oss/service_spec.rb +142 -0
- data/spec/aliyun/oss/util_spec.rb +50 -0
- data/spec/aliyun/sts/client_spec.rb +150 -0
- data/spec/aliyun/sts/util_spec.rb +39 -0
- data/tests/config.rb +31 -0
- data/tests/test_content_encoding.rb +54 -0
- data/tests/test_content_type.rb +95 -0
- data/tests/test_custom_headers.rb +70 -0
- data/tests/test_encoding.rb +77 -0
- data/tests/test_large_file.rb +66 -0
- data/tests/test_multipart.rb +97 -0
- data/tests/test_object_acl.rb +49 -0
- data/tests/test_object_key.rb +68 -0
- data/tests/test_object_url.rb +69 -0
- data/tests/test_resumable.rb +40 -0
- metadata +240 -0
checksums.yaml
ADDED
@@ -0,0 +1,7 @@
|
|
1
|
+
---
|
2
|
+
SHA1:
|
3
|
+
metadata.gz: 05de25693f6349e62e52ef5c9ec587a5b5ca864f
|
4
|
+
data.tar.gz: 066cd3660f8143a6d2a5438b1c124c6ae5e0c787
|
5
|
+
SHA512:
|
6
|
+
metadata.gz: 0f33cf8941b7e03cf72b869a35b369f99cc6d2f1e081914414e22e89f5a5f675646b2a55ed0bf3bc1b2eead4345ed93d165b47dadc3f198a1e04dea35500e6ba
|
7
|
+
data.tar.gz: 83dec408d84b6518415dc42f9894ca16732a1c6b9fe08feae62570ac4245717633224748be04688af5fe24ad3eaeecf9d427b5fbdffca15a75f3b2db2cc53809
|
data/CHANGELOG.md
ADDED
@@ -0,0 +1,95 @@
|
|
1
|
+
## Change Log
|
2
|
+
|
3
|
+
### v0.4.1 / 2016-07-19
|
4
|
+
|
5
|
+
- Support signature object url with STS
|
6
|
+
|
7
|
+
### v0.4.0 / 2016-05-19
|
8
|
+
|
9
|
+
- Enable copy objects of different buckets(but in the same region)
|
10
|
+
|
11
|
+
### v0.3.7
|
12
|
+
|
13
|
+
- Remove monkey patch for Hash
|
14
|
+
|
15
|
+
### v0.3.6
|
16
|
+
|
17
|
+
- Fix Zlib::Inflate in ruby-1.9.x
|
18
|
+
- Add function test(tests/) in travis CI
|
19
|
+
- Add Gem version badge
|
20
|
+
- Support IP endpoint
|
21
|
+
|
22
|
+
### v0.3.5
|
23
|
+
|
24
|
+
- Fix the issue that StreamWriter will read more bytes than wanted
|
25
|
+
|
26
|
+
### v0.3.4
|
27
|
+
|
28
|
+
- Fix handling gzip/deflate response
|
29
|
+
- Change the default accept-encoding to 'identity'
|
30
|
+
- Allow setting custom HTTP headers in get_object
|
31
|
+
|
32
|
+
### v0.3.3
|
33
|
+
|
34
|
+
- Fix object key problem in batch_delete
|
35
|
+
|
36
|
+
### v0.3.2
|
37
|
+
|
38
|
+
- Allow setting custom HTTP headers in put/append/resumable_upload
|
39
|
+
- Allow setting object acl in put/append
|
40
|
+
|
41
|
+
### v0.3.1
|
42
|
+
|
43
|
+
- Fix frozen string issue in OSSClient/STSClient config
|
44
|
+
|
45
|
+
### v0.3.0
|
46
|
+
|
47
|
+
- Add support for OSS Callback
|
48
|
+
|
49
|
+
### v0.2.0
|
50
|
+
|
51
|
+
- Add aliyun/sts
|
52
|
+
- OSS::Client support STS
|
53
|
+
|
54
|
+
### v0.1.8
|
55
|
+
|
56
|
+
- Fix StreamWriter string encoding problem
|
57
|
+
- Add ruby version and os version in User-Agent
|
58
|
+
- Some comments & examples refine
|
59
|
+
|
60
|
+
### v0.1.7
|
61
|
+
|
62
|
+
- Fix StreamWriter#inspect bug
|
63
|
+
- Fix wrong in README
|
64
|
+
|
65
|
+
### v0.1.6
|
66
|
+
|
67
|
+
- Required ruby version >= 1.9.3 due to 1.9.2 has String encoding
|
68
|
+
compatibility problems
|
69
|
+
- Add travis & overalls
|
70
|
+
- Open source to github.com
|
71
|
+
|
72
|
+
### v0.1.5
|
73
|
+
|
74
|
+
- Add open_timeout and read_timeout config
|
75
|
+
- Fix a concurrency bug in resumable_upload/download
|
76
|
+
|
77
|
+
### v0.1.4
|
78
|
+
|
79
|
+
- Fix object key encoding problem
|
80
|
+
- Fix Content-Type problem
|
81
|
+
- Add list_uploads & abort_uploads methods
|
82
|
+
- Make resumable_upload/download faster by multi-threading
|
83
|
+
- Enable log rotate
|
84
|
+
|
85
|
+
### v0.1.3
|
86
|
+
|
87
|
+
- Include request id in exception message
|
88
|
+
|
89
|
+
### v0.1.2
|
90
|
+
|
91
|
+
- Fix yard doc unresolved link
|
92
|
+
|
93
|
+
### v0.1.1
|
94
|
+
|
95
|
+
- Add README.md CHANGELOG.md in gem
|
data/README.md
ADDED
@@ -0,0 +1,423 @@
|
|
1
|
+
# Aliyun OSS SDK for Ruby
|
2
|
+
|
3
|
+
[![Gem Version](https://badge.fury.io/rb/aliyun-sdk.svg)](https://badge.fury.io/rb/aliyun-sdk)
|
4
|
+
[![Build Status](https://travis-ci.org/aliyun/aliyun-oss-ruby-sdk.svg?branch=master)](https://travis-ci.org/aliyun/aliyun-oss-ruby-sdk?branch=master)
|
5
|
+
[![Coverage Status](https://coveralls.io/repos/aliyun/aliyun-oss-ruby-sdk/badge.svg?branch=master&service=github)](https://coveralls.io/github/aliyun/aliyun-oss-ruby-sdk?branch=master)
|
6
|
+
|
7
|
+
-----
|
8
|
+
|
9
|
+
Aliyun OSS SDK for Ruby是用于方便访问阿里云OSS(Object Storage Service)
|
10
|
+
RESTful API的Ruby客户端程序。了解OSS的的更多信息请访问OSS官网:
|
11
|
+
http://www.aliyun.com/product/oss
|
12
|
+
|
13
|
+
## 运行环境
|
14
|
+
|
15
|
+
- Ruby版本 >= 1.9.3
|
16
|
+
- 支持Ruby运行环境的Windows/Linux/OS X
|
17
|
+
|
18
|
+
安装Ruby请参考:https://www.ruby-lang.org/zh_cn/downloads/
|
19
|
+
|
20
|
+
## 快速开始
|
21
|
+
|
22
|
+
### 开通OSS账号
|
23
|
+
|
24
|
+
登录官网:http://www.aliyun.com/product/oss ,点击“立即开通”。按照提示
|
25
|
+
开通OSS服务。开通服务之后请在“管理控制台”中查看您的AccessKeyId和
|
26
|
+
AccessKeySecret,在使用Aliyun OSS SDK时需要提供您的这两个信息。
|
27
|
+
|
28
|
+
### 安装Aliyun OSS SDK for Ruby
|
29
|
+
|
30
|
+
gem install aliyun-sdk
|
31
|
+
|
32
|
+
并在你的程序中或者`irb`命令下包含:
|
33
|
+
|
34
|
+
require 'aliyun_sdk/oss'
|
35
|
+
|
36
|
+
**注意:**
|
37
|
+
|
38
|
+
1. SDK依赖的一些gem是本地扩展的形式,因此安装完Ruby之后还需要安装
|
39
|
+
ruby-dev以支持编译本地扩展的gem
|
40
|
+
2. SDK依赖的处理XML的gem(nokogiri)要求环境中包含zlib库
|
41
|
+
|
42
|
+
以Ubuntu为例,安装上述依赖的方法:
|
43
|
+
|
44
|
+
sudo apt-get install ruby-dev
|
45
|
+
sudo apt-get install zlib1g-dev
|
46
|
+
|
47
|
+
其他系统类似。
|
48
|
+
|
49
|
+
### 创建Client
|
50
|
+
|
51
|
+
client = AliyunSDK::OSS::Client.new(
|
52
|
+
:endpoint => 'endpoint',
|
53
|
+
:access_key_id => 'access_key_id',
|
54
|
+
:access_key_secret => 'access_key_secret')
|
55
|
+
|
56
|
+
其中`endpoint`是OSS服务的地址,根据节点区域不同,这个地址可能不一样,例如
|
57
|
+
杭州节点的地址是:`http://oss-cn-hangzhou.aliyuncs.com`,其他节点的地址见:
|
58
|
+
[节点列表][region-list]
|
59
|
+
|
60
|
+
`access_key_id`和`access_key_secret`是您的服务凭证,在官网的“管理控制
|
61
|
+
台”上面可以查看。**请妥善保管您的AccessKeySecret,泄露之后可能影响您的
|
62
|
+
数据安全**
|
63
|
+
|
64
|
+
#### 使用用户绑定的域名作为endpoint
|
65
|
+
|
66
|
+
OSS支持自定义域名绑定,允许用户将自己的域名指向阿里云OSS的服务地址
|
67
|
+
(CNAME),这样用户迁移到OSS上时应用内资源的路径可以不用修改。绑定的域
|
68
|
+
名指向OSS的一个bucket。绑定域名的操作只能在OSS控制台进行。更多关于自定
|
69
|
+
义域名绑定的内容请到官网了解:[OSS自定义域名绑定][custom-domain]
|
70
|
+
|
71
|
+
用户绑定了域名后,使用SDK时指定的endpoint可以使用标准的OSS服务地址,也
|
72
|
+
可以使用用户绑定的域名:
|
73
|
+
|
74
|
+
client = AliyunSDK::OSS::Client.new(
|
75
|
+
:endpoint => 'http://img.my-domain.com',
|
76
|
+
:access_key_id => 'access_key_id',
|
77
|
+
:access_key_secret => 'access_key_secret',
|
78
|
+
:cname => true)
|
79
|
+
|
80
|
+
有以下几点需要注意:
|
81
|
+
|
82
|
+
1. 在Client初始化时必须指定:cname为true
|
83
|
+
2. 自定义域名绑定了OSS的一个bucket,所以用这种方式创建的client不能进行
|
84
|
+
list_buckets操作
|
85
|
+
3. 在{AliyunSDK::OSS::Client#get_bucket}时仍需要指定bucket名字,并且要与
|
86
|
+
域名所绑定的bucket名字相同
|
87
|
+
|
88
|
+
#### 使用STS创建Client
|
89
|
+
|
90
|
+
OSS支持用户使用STS进行访问,更多有关STS的内容,请参考 [阿里云STS][aliyun-sts]。
|
91
|
+
在使用STS之前需要先向STS申请一个临时token,
|
92
|
+
aliyun-sdk中包含了STS的SDK,使用时只需要`require 'aliyun/sts'`即可:
|
93
|
+
|
94
|
+
require 'aliyun/sts'
|
95
|
+
sts = AliyunSDK::STS::Client.new(
|
96
|
+
access_key_id: 'access_key_id',
|
97
|
+
access_key_secret: 'access_key_secret')
|
98
|
+
|
99
|
+
token = sts.assume_role('role-arn', 'my-app')
|
100
|
+
|
101
|
+
client = AliyunSDK::OSS::Client.new(
|
102
|
+
:endpoint => 'http://oss-cn-hangzhou.aliyuncs.com',
|
103
|
+
:access_key_id => token.access_key_id,
|
104
|
+
:access_key_secret => token.access_key_secret,
|
105
|
+
:sts_token => token.security_token)
|
106
|
+
|
107
|
+
注意使用STS时必须指定`:sts_token`参数。用户还可以通过`STS::Client`申请
|
108
|
+
带Policy的token,细节请参考[API文档][sdk-api]。
|
109
|
+
|
110
|
+
### 列出当前所有的Bucket
|
111
|
+
|
112
|
+
buckets = client.list_buckets
|
113
|
+
buckets.each{ |b| puts b.name }
|
114
|
+
|
115
|
+
`list_buckets`返回的是一个迭代器,用户依次获取每个Bucket的信息。Bucket
|
116
|
+
对象的结构请查看API文档中的{AliyunSDK::OSS::Bucket}
|
117
|
+
|
118
|
+
### 创建一个Bucket
|
119
|
+
|
120
|
+
bucket = client.create_bucket('my-bucket')
|
121
|
+
|
122
|
+
### 列出Bucket中所有的Object
|
123
|
+
|
124
|
+
bucket = client.get_bucket('my-bucket')
|
125
|
+
objects = bucket.list_objects
|
126
|
+
objects.each{ |o| puts o.key }
|
127
|
+
|
128
|
+
`list_objects`返回的是一个迭代器,用户依次获取每个Object的信息。Object
|
129
|
+
对象的结构请查看API文档中的{AliyunSDK::OSS::Object}
|
130
|
+
|
131
|
+
### 在Bucket中创建一个Object
|
132
|
+
|
133
|
+
bucket.put_object(object_key){ |stream| stream << 'hello world' }
|
134
|
+
|
135
|
+
用户也可以通过上传本地文件创建一个Object:
|
136
|
+
|
137
|
+
bucket.put_object(object_key, :file => local_file)
|
138
|
+
|
139
|
+
### 从Bucket中下载一个Object
|
140
|
+
|
141
|
+
bucket.get_object(object_key){ |content| puts content }
|
142
|
+
|
143
|
+
用户也可以将Object下载到本地文件中:
|
144
|
+
|
145
|
+
bucket.get_object(object_key, :file => local_file)
|
146
|
+
|
147
|
+
### 拷贝Object
|
148
|
+
|
149
|
+
bucket.copy_object(from_key, to_key)
|
150
|
+
|
151
|
+
### 判断一个Object是否存在
|
152
|
+
|
153
|
+
bucket.object_exists?(object_key)
|
154
|
+
|
155
|
+
更多Bucket的操作请参考API文档中的{AliyunSDK::OSS::Bucket}
|
156
|
+
|
157
|
+
## 模拟目录结构
|
158
|
+
|
159
|
+
OSS是Object存储服务,本身不支持目录结构,所有的object都是“平”的。但是
|
160
|
+
用户可以通过设置object的key为"foo/bar/file"这样的形式来模拟目录结构。
|
161
|
+
假设现在有以下Objects:
|
162
|
+
|
163
|
+
foo/x
|
164
|
+
foo/bar/f1
|
165
|
+
foo/bar/dir/file
|
166
|
+
foo/hello/file
|
167
|
+
|
168
|
+
列出"foo/"目录下的所有文件就是以"foo/"为prefix进行`list_objects`,但
|
169
|
+
是这样也会把"foo/bar/"下的所有object也列出来。为此需要用到delimiter参
|
170
|
+
数,其含义是从prefix往后遇到第一个delimiter时停止,这中间的key作为
|
171
|
+
Object的common prefix,包含在`list_objects`的结果中。
|
172
|
+
|
173
|
+
objs = bucket.list_objects(:prefix => 'foo/', :delimiter => '/')
|
174
|
+
objs.each do |i|
|
175
|
+
if i.is_a?(AliyunSDK::OSS::Object) # a object
|
176
|
+
puts "object: #{i.key}"
|
177
|
+
else
|
178
|
+
puts "common prefix: #{i}"
|
179
|
+
end
|
180
|
+
end
|
181
|
+
# output
|
182
|
+
object: foo/x
|
183
|
+
common prefix: foo/bar/
|
184
|
+
common prefix: foo/hello/
|
185
|
+
|
186
|
+
Common prefix让用户不需要遍历所有的object(可能数量巨大)而找出前缀,
|
187
|
+
在模拟目录结构时非常有用。
|
188
|
+
|
189
|
+
## 上传回调
|
190
|
+
|
191
|
+
在`put_object`和`resumable_upload`时可以指定一个`Callback`,这样在文件
|
192
|
+
成功上传到OSS之后,OSS会向用户提供的服务器地址发起一个HTTP POST请求,
|
193
|
+
以通知用户相应的事件发生了。用户可以在收到这个通知之后进行相应的动作,
|
194
|
+
例如更新数据库、统计行为等。更多有关上传回调的内容请参考[OSS上传回调][oss-callback]。
|
195
|
+
|
196
|
+
下面的例子将演示如何使用上传回调:
|
197
|
+
|
198
|
+
callback = AliyunSDK::OSS::Callback.new(
|
199
|
+
url: 'http://10.101.168.94:1234/callback',
|
200
|
+
query: {user: 'put_object'},
|
201
|
+
body: 'bucket=${bucket}&object=${object}'
|
202
|
+
)
|
203
|
+
|
204
|
+
begin
|
205
|
+
bucket.put_object('files/hello', callback: callback)
|
206
|
+
rescue AliyunSDK::OSS::CallbackError => e
|
207
|
+
puts "Callback failed: #{e.message}"
|
208
|
+
end
|
209
|
+
|
210
|
+
**注意**
|
211
|
+
|
212
|
+
1. callback的url**不能**包含query string,而应该在`:query`参数中指定
|
213
|
+
2. 可能出现文件上传成功,但是执行回调失败的情况,此时client会抛出
|
214
|
+
`CallbackError`,用户如果要忽略此错误,需要显式接住这个异常。
|
215
|
+
3. 详细的例子可以参考[callback.rb](examples/aliyun/oss/callback.rb)
|
216
|
+
4. 接受回调的server可以参考[callback_server.rb](rails/aliyun_oss_callback_server.rb)
|
217
|
+
|
218
|
+
## 断点上传/下载
|
219
|
+
|
220
|
+
OSS支持大文件的存储,用户如果上传/下载大文件(Object)的时候中断了(网络
|
221
|
+
闪断、程序崩溃、机器断电等),重新上传/下载是件很费资源的事情。OSS支持
|
222
|
+
Multipart的功能,可以在上传/下载时将大文件进行分片传输。Aliyun OSS SDK
|
223
|
+
基于此提供了断点上传/下载的功能。如果发生中断,可以从上次中断的地方继
|
224
|
+
续进行上传/下载。对于文件大小超过100MB的文件,都建议采用断点上传/下载
|
225
|
+
的方式进行。
|
226
|
+
|
227
|
+
### 断点上传
|
228
|
+
|
229
|
+
bucket.resumable_upload(object_key, local_file, :cpt_file => cpt_file)
|
230
|
+
|
231
|
+
其中`:cpt_file`指定保存上传中间状态的checkpoint文件所在的位置,如果用户
|
232
|
+
没有指定,SDK将为用户在`local_file`所在的目录生成一个
|
233
|
+
`local_file.cpt`。上传中断后,只需要提供相同的cpt文件,上传将会从
|
234
|
+
中断的点继续上传。所以典型的上传代码是:
|
235
|
+
|
236
|
+
retry_times = 5
|
237
|
+
retry_times.times do
|
238
|
+
begin
|
239
|
+
bucket.resumable_upload(object_key, local_file)
|
240
|
+
rescue => e
|
241
|
+
logger.error(e.message)
|
242
|
+
end
|
243
|
+
end
|
244
|
+
|
245
|
+
注意:
|
246
|
+
|
247
|
+
1. SDK会将上传的中间状态信息记录在cpt文件中,所以要确保用户对cpt文
|
248
|
+
件有写权限
|
249
|
+
2. cpt文件记录了上传的中间状态信息并自带了校验,用户不能去编辑它,如
|
250
|
+
果cpt文件损坏则上传无法继续。整个上传完成后cpt文件会被删除。
|
251
|
+
|
252
|
+
### 断点下载
|
253
|
+
|
254
|
+
bucket.resumable_download(object_key, local_file, :cpt_file => cpt_file)
|
255
|
+
|
256
|
+
其中`:cpt_file`指定保存下载中间状态的checkpoint文件所在的位置,如果用户
|
257
|
+
没有指定,SDK将为用户在`local_file`所在的目录生成一个
|
258
|
+
`local_file.cpt`。下载中断后,只需要提供相同的cpt文件,下载将会从
|
259
|
+
中断的点继续下载。所以典型的下载代码是:
|
260
|
+
|
261
|
+
retry_times = 5
|
262
|
+
retry_times.times do
|
263
|
+
begin
|
264
|
+
bucket.resumable_download(object_key, local_file)
|
265
|
+
rescue => e
|
266
|
+
logger.error(e.message)
|
267
|
+
end
|
268
|
+
end
|
269
|
+
|
270
|
+
注意:
|
271
|
+
|
272
|
+
1. 在下载过程中,对于下载完成的每个分片,会在`local_file`所在的目录生
|
273
|
+
成一个`local_file.part.N`的临时文件。整个下载完成后这些文件会被删除。
|
274
|
+
用户不能去编辑或删除part文件,否则下载不能继续。
|
275
|
+
2. SDK会将下载的中间状态信息记录在cpt文件中,所以要确保用户对cpt文
|
276
|
+
件有写权限
|
277
|
+
3. cpt文件记录了下载的中间状态信息并自带了校验,用户不能去编辑它,如
|
278
|
+
果cpt文件损坏则下载无法继续。整个下载完成后cpt文件会被删除。
|
279
|
+
|
280
|
+
|
281
|
+
## 可追加的文件
|
282
|
+
|
283
|
+
阿里云OSS中的Object分为两种类型:Normal和Appendable。
|
284
|
+
|
285
|
+
- 对于Normal Object,每次上传都是作为一个整体,如果一个Object已存在,
|
286
|
+
两次上传相同key的Object将会覆盖原有的Object
|
287
|
+
- 对于Appendable Object,第一次通过`append_object`创建它,后续的
|
288
|
+
`append_object`不会覆盖原有的内容,而是在Object末尾追加内容
|
289
|
+
- 不能向Normal Object追加内容
|
290
|
+
- 不能拷贝一个Appendable Object
|
291
|
+
|
292
|
+
### 创建一个Appendable Object
|
293
|
+
|
294
|
+
bucket.append_object(object_key, 0){ |stream| stream << "hello world" }
|
295
|
+
|
296
|
+
第二个参数是追加的位置,对一个Object第一次追加时,这个参数为0。后续的
|
297
|
+
追加这个参数要求是追加前Object的长度。
|
298
|
+
|
299
|
+
当然,也可以从文件中读取追加的内容:
|
300
|
+
|
301
|
+
bucket.append_object(object_key, 0, :file => local_file)
|
302
|
+
|
303
|
+
### 向Object追加内容
|
304
|
+
|
305
|
+
pos = bucket.get_object(object_key).size
|
306
|
+
next_pos = bucket.append_object(object_key, pos, :file => local_file)
|
307
|
+
|
308
|
+
程序第一次追加时,可以通过{AliyunSDK::OSS::Bucket#get_object}获取文件的长度,
|
309
|
+
后续追加时,可以根据{AliyunSDK::OSS::Bucket#append_object}返回的下次追加长度。
|
310
|
+
|
311
|
+
注意:如果并发地`append_object`,`next_pos`并不总是对的。
|
312
|
+
|
313
|
+
## Object meta信息
|
314
|
+
|
315
|
+
在上传Object时,除了Object内容,OSS还允许用户为Object设置一些"meta信息
|
316
|
+
",这些meta信息是一个个的Key-Value对,用于标识Object特有的属性信息。这
|
317
|
+
些meta信息会跟Object一起存储,并在`get_object`和`get_object`时返
|
318
|
+
回给用户。
|
319
|
+
|
320
|
+
bucket.put_object(object_key, :file => local_file,
|
321
|
+
:metas => {
|
322
|
+
'key1' => 'value1',
|
323
|
+
'key2' => 'value2'})
|
324
|
+
|
325
|
+
obj = bucket.get_object(object_key, :file => localfile)
|
326
|
+
puts obj.metas
|
327
|
+
|
328
|
+
关于meta信息有以下几点需要注意:
|
329
|
+
|
330
|
+
1. meta信息的key和value都只能是简单的ASCII非换行字符,并且总的大小不能超过8KB。
|
331
|
+
2. Copy object时默认将拷贝源object的meta信息,如果用户不希望这么做,需要
|
332
|
+
显式地将`:meta_directive`设置成{AliyunSDK::OSS::MetaDirective::REPLACE}
|
333
|
+
|
334
|
+
## 权限控制
|
335
|
+
|
336
|
+
OSS允许用户对Bucket和Object分别设置访问权限,方便用户控制自己的资源可
|
337
|
+
以被如何访问。对于Bucket,有三种访问权限:
|
338
|
+
|
339
|
+
- public-read-write 允许匿名用户向该Bucket中创建/获取/删除Object
|
340
|
+
- public-read 允许匿名用户获取该Bucket中的Object
|
341
|
+
- private 不允许匿名访问,所有的访问都要经过签名
|
342
|
+
|
343
|
+
创建Bucket时,默认是private权限。之后用户可以通过`bucket.acl=`来设置
|
344
|
+
Bucket的权限。
|
345
|
+
|
346
|
+
bucket.acl = AliyunSDK::OSS::ACL::PUBLIC_READ
|
347
|
+
puts bucket.acl # public-read
|
348
|
+
|
349
|
+
对于Object,有四种访问权限:
|
350
|
+
|
351
|
+
- default 继承所属的Bucket的访问权限,即与所属Bucket的权限值一样
|
352
|
+
- public-read-write 允许匿名用户读写该Object
|
353
|
+
- public-read 允许匿名用户读该Object
|
354
|
+
- private 不允许匿名访问,所有的访问都要经过签名
|
355
|
+
|
356
|
+
创建Object时,默认为default权限。之后用户可以通过
|
357
|
+
`bucket.set_object_acl`来设置Object的权限。
|
358
|
+
|
359
|
+
acl = bucket.get_object_acl(object_key)
|
360
|
+
puts acl # default
|
361
|
+
bucket.set_object_acl(object_key, AliyunSDK::OSS::ACL::PUBLIC_READ)
|
362
|
+
acl = bucket.get_object_acl(object_key)
|
363
|
+
puts acl # public-read
|
364
|
+
|
365
|
+
需要注意的是:
|
366
|
+
|
367
|
+
1. 如果设置了Object的权限,则访问该Object时进行权限认证时会优先判断
|
368
|
+
Object的权限,而Bucket的权限设置会被忽略。
|
369
|
+
2. 允许匿名访问时(设置了public-read或者public-read-write权限),用户
|
370
|
+
可以直接通过浏览器访问,例如:
|
371
|
+
|
372
|
+
http://bucket-name.oss-cn-hangzhou.aliyuncs.com/object.jpg
|
373
|
+
|
374
|
+
3. 访问具有public权限的Bucket/Object时,也可以通过创建匿名的Client来进行:
|
375
|
+
|
376
|
+
# 不填access_key_id和access_key_secret,将创建匿名Client,只能访问
|
377
|
+
# 具有public权限的Bucket/Object
|
378
|
+
client = Client.new(:endpoint => 'oss-cn-hangzhou.aliyuncs.com')
|
379
|
+
bucket = client.get_bucket('public-bucket')
|
380
|
+
obj = bucket.get_object('public-object', :file => local_file)
|
381
|
+
|
382
|
+
## 运行examples
|
383
|
+
|
384
|
+
SDK的examples/目录下有一些展示SDK功能的示例程序,用户稍加配置就可以直
|
385
|
+
接运行。examples需要的权限信息和bucket信息从用户`HOME`目录下的配置文件
|
386
|
+
`~/.oss.yml`中读取,其中应该包含以下字段(**注意冒号后面需要有一个空格**):
|
387
|
+
|
388
|
+
endpoint: oss-cn-hangzhou.aliyuncs.com
|
389
|
+
cname: false
|
390
|
+
access_key_id: <ACCESS KEY ID>
|
391
|
+
access_key_secret: <ACCESS KEY SECRET>
|
392
|
+
bucket: <BUCKET NAME>
|
393
|
+
|
394
|
+
用户需要创建(如果不存在)或者修改其中的内容,然后运行:
|
395
|
+
|
396
|
+
ruby examples/aliyun/oss/bucket.rb
|
397
|
+
|
398
|
+
## 运行测试
|
399
|
+
|
400
|
+
```bash
|
401
|
+
bundle exec rake spec
|
402
|
+
|
403
|
+
export RUBY_SDK_OSS_ENDPOINT=endpoint
|
404
|
+
export RUBY_SDK_OSS_ID=AccessKeyId
|
405
|
+
export RUBY_SDK_OSS_KEY=AccessKeySecret
|
406
|
+
export RUBY_SDK_OSS_BUCKET=bucket-name
|
407
|
+
|
408
|
+
bundle exec rake test
|
409
|
+
```
|
410
|
+
|
411
|
+
## 更多
|
412
|
+
|
413
|
+
更多文档请查看:
|
414
|
+
|
415
|
+
- 阿里云官网文档:http://help.aliyun.com/product/8314910_oss.html
|
416
|
+
- OSS官网SDK文档:https://help.aliyun.com/document_detail/oss/sdk/ruby-sdk/install.html
|
417
|
+
|
418
|
+
|
419
|
+
[region-list]: https://help.aliyun.com/document_detail/oss/user_guide/endpoint_region.html
|
420
|
+
[custom-domain]: https://help.aliyun.com/document_detail/oss/user_guide/oss_concept/oss_cname.html
|
421
|
+
[aliyun-sts]: https://help.aliyun.com/document_detail/ram/intro/concepts.html
|
422
|
+
[sdk-api]: http://www.rubydoc.info/gems/aliyun-sdk/
|
423
|
+
[oss-callback]: https://help.aliyun.com/document_detail/oss/user_guide/upload_object/upload_callback.html
|