UPYUN sdk for Ruby
UPYUN 官方 Rest API 以及 Form API SDK !
注:
0.x.x
版本为之前第三方开发者 veggie89 开发,后续将不会维护,如果您有使用0.x.x
版本,请尽快切换至1.x.x
版本,以获得最新的官方 SDK 支持
安装
在 Gemfile
中加入以下代码
gem 'upyun', '~> 1.0.3'
然后执行如下命令安装:
$ bundle
或者可以使用 gem
手动安装:
$ gem install upyun
基本使用
在使用本 SDK 之前,您需要拥有一个有效的 UPYUN 空间,并做好操作员的授权。详情可见 开发者指南
Rest API 使用
初始化一个实例
require 'upyun'
upyun = Upyun::Rest.new('bucket', 'operator', 'password', 'options', 'endpoint')
参数
bucket
: UPYUN 空间名称operator
: 授权操作员帐号password
: 授权操作员密码options
: 连接选项,可用的选项见RestClient::Resource, 默认设置超时时间 60sendpoint
(可选)(默认:Upyun::ED_AUTO
): API接入点,可根据具体网络情况设置最优的接入点,详情见 API 域名
其中 endpoint
可选值如下:
Upyun::ED_AUTO # 自动判断最优线路
Upyun::ED_TELECOM # 电信接入点
Upyun::ED_UNION # 联通(网通)接入点
Upyun::ED_CMCC # 移动(铁通)接入点
在初始化实例后,也可以重新切换 API 接入点,方法如下:
upyun.endpoint = Upyun::ED_CMCC
上传文件
默认方式
默认使用 Upyun 基本 Header 头上传文件:
注: 这种方式只指定了又拍云必选的
Date
,Content-Length
两个 Header,其它 Header 信息均未指定
upyun.put('/save/to/path', 'file or binary')
参数
/save/to/path
: 文件在 UPYUN 空间的保存路径file or binary
:本地文件路径或文件内容
自定义方式
您也可以选择使用 API 允许的额外可选 HTTP Header 参数,以使用 API 提供的预处理等功能:
headers = {'Content-Type' => 'image/jpeg', 'x-gmkerl-type' => 'fix_width', 'x-gmkerl-value' => 1080}
upyun.put('/save/to/path', 'file or binary', headers)
其中, /save/to/path
和 file or binary
和默认上传方式中一致,headers
参数即为额外的可选 HTTP Header 参数,详情查阅 Rest API
返回
上传成功返回 true
,失败返回一个 Hash
结构: {request_id: request_id, error: {code: code, message: message}}
,
其中:
request_id
为本次请求的请求码,由 UPYUN 本台返回,可用该值查询 UPYUN 日志;code
为又拍云返回的错误码;message
为错误信息;
下载文件
获取文件内容
file = upyun.get('/path/to/file')
参数
'/path/to/file'
: 文件在 UPYUN 空间中的路径
返回
下载成功返回文件信息,失败返回一个 Hash
: {request_id: request_id, error: {code: code, message: message}}
,
其中:
request_id
为本次请求的请求码,由 UPYUN 本台返回,可用该值查询 UPYUN 日志;code
为又拍云返回的错误码;message
为错误信息;
保存文件至本地
upyun.get('/path/to/file', 'saved/foo.png')
参数
'/path/to/file'
: 文件在 UPYUN 空间中的路径saved/foo.png
: 文件本地保存路径
返回 下载成功返回获取的文件长度, 失败返回内容和上例一致。
获取文件信息
upyun.getinfo('/path/to/file')
参数
'/path/to/file'
: 文件在 UPYUN 空间中的路径
返回
成功返回 Hash
结构:
{file_type: "file", file_size: 397190, file_date: 1415954066}
其中
:file_type
说明是文件("file"
)还是目录("folder"
):file_size
是文件的大小:file_date
是文件最后的更改时间。
失败返回一个 Hash
: {request_id: request_id, error: {code: code, message: message}}
。
删除文件或者目录
upyun.delete('/path/to/file')
参数
'/path/to/file'
: 文件在 UPYUN 空间中的路径
返回
成功返回: true
,
失败返回一个 Hash
: {request_id: request_id, error: {code: code, message: message}}
。
创建目录
upyun.mkdir('/path/to/dir')
参数
'/path/to/dir'
: 文件在 UPYUN 空间中的路径
返回
成功返回: true
,
失败返回一个 Hash
: {request_id: request_id, error: {code: code, message: message}}
。
获取目录文件列表
upyun.getlist('/path/to/dir')
参数
'/path/to/dir'
: 文件在 UPYUN 空间中的路径
返回 成功返回一个数组,每个数组成员为一个文件/目录:
[{:name=>"foo", :type=>:folder, :length=>0, :last_modified=>1416193624},
{:name=>"bar.txt", :type=>:file, :length=>25, :last_modified=>1415261057}]
失败返回一个 Hash
: {request_id: request_id, error: {code: code, message: message}}
。
获取空间使用情况
upyun.usage
返回
成功返回空间使用量(单位为 Byte
): 12400
,
失败返回一个 Hash
: {request_id: request_id, error: {code: code, message: message}}
。
Form API 使用
初始化一个实例
require 'upyun'
upyun = Upyun::Form.new('form-api-secret', 'bucket', 'options')
参数
form-api-secret
: 表单 API 密钥,可通过 UPYUN 用户控制面板获取bucket
: UPYUN 空间名称options
: 连接选项,可用的选项见RestClient::Resource, 默认设置超时时间 60s
与 Rest API 相似, 表单 API 也有个实例变量 endpoint
代表又拍云基本域名,默认设置为 Upyun::ED_AUTO
,也可以在初始化一个实例之后通过如下方式切换:
upyun.endpoint = Upyun::ED_CMCC
上传文件
简化版
为了简化使用,又拍云文档必选的参数中:
save-key
默认设置为:'/{year}/{mon}/{day}/{filename}{.suffix}'
expiration
默认设置为10分钟:Time.now.to_i + 600
使用简化版本,将不使用额外的策略参数:
upyun.upload('file')
返回
上传结果返回一个 Hash
结构:
{
:code=>200,
:message=>"ok",
:url=>"/2014/11/17/upyun.jpg",
:time=>1416208715,
:sign=>"f5165b35df431065ca54490a34028635"
}
其中
code
: 返回的状态码,200
为成功,其它为失败message
: 错误信息,具体查阅 表单 API 状态代码表url
: 上传文件保存路径time
: 请求的时间戳sign
: 签名参数,详情见 sign与non-sign参数说明- 如果在请求中指定了
ext-param
, 那么返回的结构中也会有ext-param
字段,详情见 ext-param
自定义参数
可以在上传的时候指定一些策略参数:
opts = {
'save_key' => '/foo/bar.jpg',
'content-type' => 'image/jpeg',
'image-width-range' => '0,1024',
'return-url' => 'http://www.example.com'
}
upyun.upload('file', opts)
特别地,如果指定了 return-url
, 那么返回的是需要跳转的地址,
详情查阅 通知规则
贡献
- Fork 本仓库 ( https://github.com/upyun/ruby-sdk/fork )
- 创建您的新特性分支 (
git checkout -b my-new-feature
) - 提交你的更新 (
git commit -am 'Add some feature'
) - 同步你的代码到 GitHub 远程仓库 (
git push origin my-new-feature
) - 发起 Pull Request 给我们