Merge pull request #41 from why404/release/v3.4.2

Release/v3.4.2 - uploadToken[:return_body]
update README.md
2026-08-10 05:18:37 +10:00 · 2013-02-05 03:45:03 -08:00 · 2013-02-05 14:59:26 +08:00 · 2013-02-04 15:38:11 +08:00 · 2013-01-24 18:38:37 -08:00 · 2013-01-23 06:23:49 -08:00
25 changed files with 731 additions and 678 deletions
@@ -10,3 +10,6 @@ rvm:
  - ruby-head
  - jruby-head
  - ree
+before_script:
+  - export QINIU_ACCESS_KEY=iN7NgwM31j4-BZacMjPrOQBs34UG1maYCAQmhdCV
+  - export QINIU_SECRET_KEY=6QTOr2Jg1gcZEWDQXKOGZh5PziC2MCV5KsntT70j
@@ -0,0 +1,70 @@
+## CHANGE LOG
+
+### v3.4.2
+
+- `Qiniu::RS.generate_upload_token()` 方法新增 `:return_body` 选项。
+
+该选项（`:return_body`）可设置文件上传成功后，执行七牛云存储规定的回调API，并以 JSON 响应格式返回其执行结果。参考 [uploadToken 之 returnBody 说明](http://docs.qiniutek.com/v3/api/io/#uploadToken-returnBody)。
+
+### v3.4.1
+
+增加为上传文件进行预转的选项，参见 [uploadToken 之 asyncOps 说明](http://docs.qiniutek.com/v3/api/io/#uploadToken-asyncOps)
+
+- `Qiniu::RS.generate_upload_token()` 方法新增 `:async_options` 选项用于进行预转操作。
+
+### v3.4.0
+
+增加文件复制/移动方法，包括批量复制/移动文件
+
+- `Qiniu::RS.copy(source_bucket, source_key, target_bucket, target_key)`
+- `Qiniu::RS.move(source_bucket, source_key, target_bucket, target_key)`
+- `Qiniu::RS.batch_copy [source_bucket, source_key, target_bucket, target_key], ...`
+- `Qiniu::RS.batch_move [source_bucket, source_key, target_bucket, target_key], ...`
+
+### v3.3.1
+
+确保单元测试里边用到的测试 Bucket 全局唯一
+
+使得10多种不通的 Ruby 宿主环境能隔离互不影响地执行单元/集成测试
+
+Ruby 宿主环境如下
+
+1.8.7, 1.9.2, 1.9.3, jruby-18mode, jruby-19mode, rbx-18mode, rbx-19mode, ruby-head, jruby-head, ree
+
+详见 <https://travis-ci.org/qiniu/ruby-sdk>
+
+### v3.3.0
+
+私有资源下载新版实现，添加 Qiniu::RS.generate_download_token() 方法。参考 [downloadToken](http://docs.qiniutek.com/v3/api/io/#get)
+
+详见 [Ruby SDK 使用文档之私有资源下载](http://docs.qiniutek.com/v3/sdk/ruby/#download-private-files)
+
+### v3.2.2
+
+fixed E701 error
+
+断点续上传根据 mkblk 返回的 host 字段进行 bput 和 mkfile ，规避由于DNS智能解析造成的分布式并行块上传会出现上下文不连贯导致的 E701 问题。
+
+### v3.2.1
+
+allow images uploaded auto-orient.
+
+允许图片上传成功后自动旋转。
+
+参考：
+
+1. [[API] multipart/form-data 上传文件之 action 字段详解](http://docs.qiniutek.com/v3/api/io/#upload-action)
+2. [[SDK] Qiniu::RS.upload_file() 方法中的参数增加了 :rotate 选项](http://docs.qiniutek.com/v3/sdk/ruby/#upload-server-side)
+
+### v3.2.0
+
+2012-11-06
+
+allow files uploaded auto callback some APIs (like imageInfo, exif, etc…), and add those APIs callback results as part of the custom data for POST biz-server.
+
+允许上传文件(图片)成功后执行回调指定的 API (比如 imageInfo, exif 接口等)，并将指定API的回调结果一并 POST 发送给客户方的业务服务器。
+
+参考：
+
+1. [[API] 生成上传授权凭证 uploadToken 之 escape 参数详解](http://docs.qiniutek.com/v3/api/io/#escape-expression)
+2. [[SDK] Qiniu::RS.generate_upload_token() 方法中的参数增加了 :escape 选项](http://docs.qiniutek.com/v3/sdk/ruby/#generate-upload-token)
@@ -1,7 +1,7 @@
 PATH
  remote: .
  specs:
-    qiniu-rs (3.2.1)
+    qiniu-rs (3.4.2)
      json (~> 1.7)
      mime-types (~> 1.19)
      rest-client (~> 1.6)
@@ -12,19 +12,19 @@ GEM
  specs:
    diff-lcs (1.1.3)
    fakeweb (1.3.0)
-    json (1.7.5)
-    mime-types (1.19)
-    rake (0.9.2.2)
+    json (1.7.6)
+    mime-types (1.20.1)
+    rake (10.0.3)
    rest-client (1.6.7)
      mime-types (>= 1.16)
-    rspec (2.11.0)
-      rspec-core (~> 2.11.0)
-      rspec-expectations (~> 2.11.0)
-      rspec-mocks (~> 2.11.0)
-    rspec-core (2.11.1)
-    rspec-expectations (2.11.3)
+    rspec (2.12.0)
+      rspec-core (~> 2.12.0)
+      rspec-expectations (~> 2.12.0)
+      rspec-mocks (~> 2.12.0)
+    rspec-core (2.12.2)
+    rspec-expectations (2.12.1)
      diff-lcs (~> 1.1.3)
-    rspec-mocks (2.11.3)
+    rspec-mocks (2.12.2)
    ruby-hmac (0.4.0)

 PLATFORMS
@@ -33,5 +33,5 @@ PLATFORMS
 DEPENDENCIES
  fakeweb (~> 1.3)
  qiniu-rs!
-  rake (~> 0.9)
-  rspec (~> 2.11)
+  rake (>= 0.9)
+  rspec (>= 2.11)
@@ -1,4 +1,4 @@
-Copyright (c) 2012 why404
+Copyright (c) 2012-2013 qiniutek.com

 MIT License

@@ -1,4 +1,4 @@
-# Qiniu Resource (Cloud) Storage SDK for Ruby - [![Build Status](https://secure.travis-ci.org/why404/qiniu-rs-for-ruby.png?branch=master)](http://travis-ci.org/why404/qiniu-rs-for-ruby) [![Dependency Status](https://gemnasium.com/why404/qiniu-rs-for-ruby.png)](https://gemnasium.com/why404/qiniu-rs-for-ruby)
+# Qiniu Resource (Cloud) Storage SDK for Ruby - [![Build Status](https://api.travis-ci.org/qiniu/ruby-sdk.png?branch=master)](https://travis-ci.org/qiniu/ruby-sdk) [![Dependency Status](https://gemnasium.com/why404/qiniu-rs-for-ruby.png)](https://gemnasium.com/why404/qiniu-rs-for-ruby)

 # 关于

@@ -32,7 +32,7 @@

 ## 许可证

-Copyright (c) 2012 qiniutek.com
+Copyright (c) 2012-2013 qiniutek.com

 基于 MIT 协议发布:

@@ -1,25 +0,0 @@
-## CHANGE LOG
-
-### v3.2.1
-
-allow images uploaded auto-orient.
-
-允许图片上传成功后自动旋转。
-
-参考：
-
-1. [[API] multipart/form-data 上传文件之 action 字段详解](http://docs.qiniutek.com/v3/api/io/#upload-action)
-2. [[SDK] Qiniu::RS.upload_file() 方法中的参数增加了 :rotate 选项](http://docs.qiniutek.com/v3/sdk/ruby/#upload-server-side)
-
-### v3.2.0
-
-2012-11-06
-
-allow files uploaded auto callback some APIs (like imageInfo, exif, etc…), and add those APIs callback results as part of the custom data for POST biz-server.
-
-允许上传文件(图片)成功后执行回调指定的 API (比如 imageInfo, exif 接口等)，并将指定API的回调结果一并 POST 发送给客户方的业务服务器。
-
-参考：
-
-1. [[API] 生成上传授权凭证 uploadToken 之 escape 参数详解](http://docs.qiniutek.com/v3/api/io/#escape-expression)
-2. [[SDK] Qiniu::RS.generate_upload_token() 方法中的参数增加了 :escape 选项](http://docs.qiniutek.com/v3/sdk/ruby/#generate-upload-token)
@@ -6,58 +6,53 @@ title: Ruby SDK 使用指南 | 七牛云存储

 此 Ruby SDK 适用于 Ruby 1.8.x, 1.9.x, jruby, rbx, ree 版本，基于 [七牛云存储官方API](/v3/api/) 构建。使用此 SDK 构建您的网络应用程序，能让您以非常便捷地方式将数据安全地存储到七牛云存储上。无论您的网络应用是一个网站程序，还是包括从云端（服务端程序）到终端（手持设备应用）的架构的服务或应用，通过七牛云存储及其 SDK，都能让您应用程序的终端用户高速上传和下载，同时也让您的服务端更加轻盈。

-七牛云存储 Ruby SDK 源码地址：[https://github.com/qiniu/ruby-sdk](https://github.com/qiniu/ruby-sdk)
+七牛云存储 Ruby SDK 源码地址：<https://github.com/qiniu/ruby-sdk> [![Build Status](https://api.travis-ci.org/qiniu/ruby-sdk.png?branch=master)](https://travis-ci.org/qiniu/ruby-sdk) [![Dependency Status](https://gemnasium.com/why404/qiniu-rs-for-ruby.png)](https://gemnasium.com/why404/qiniu-rs-for-ruby)

-**文档大纲**
+**目录**

 - [安装](#Installation)
+- [接入](#turn-on)
+    - [配置密钥（AccessKey / SecretKey）](#establish_connection!)
+    - [针对 Ruby On Rails 网站应用初始化设置](#ror-init)
 - [使用](#Usage)
-    - [应用接入](#establish_connection!)
-    - [Ruby On Rails 应用初始化设置](#ror-init)
-    - [上传文件](#upload)
-        - [获取用于上传文件的临时授权凭证](#generate-upload-token)
-        - [服务端上传文件](#upload-server-side)
-            - [断点续上传](#resumable-upload)
-            - [针对 NotFound 场景处理](#upload-file-for-not-found)
-        - [客户端直传文件](#upload-client-side)
-    - [查看文件属性信息](#stat)
-    - [获取文件下载链接（含文件属性信息）](#get)
-    - [只获取文件下载链接](#download)
-    - [删除指定文件](#delete)
-    - [删除所有文件（单个 bucket）](#drop)
-    - [批量操作](#batch)
-        - [批量获取文件属性信息（含下载链接）](#batch_get)
-        - [批量获取文件下载链接](#batch_download)
-        - [批量删除文件](#batch_delete)
-    - [创建公开外链](#publish)
-    - [取消公开外链](#unpublish)
-    - [Bucket（资源表）管理](#buckets)
-        - [创建 Bucket](#mkbucket)
-        - [列出所有 Bucket](#list-all-buckets)
-        - [访问控制](#set-protected)
-    - [图像处理](#op-image)
-        - [查看图片属性信息](#image_info)
-        - [查看图片EXIF信息](#image_exif)
-        - [获取指定规格的缩略图预览地址](#image_preview_url)
-        - [高级图像处理（缩略、裁剪、旋转、转化）](#image_mogrify_preview_url)
-        - [高级图像处理（缩略、裁剪、旋转、转化）并持久化](#image_mogrify_save_as)
-        - [高级图像处理（水印）](#image-watermarking)
-            - [水印准备工作](#watermarking-pre-work)
-                - [设置原图保护](#watermarking-set-protected)
-                - [设置水印预览图URL分隔符](#watermarking-set-sep)
-                - [设置水印预览图规格别名](#watermarking-set-style)
-            - [设置水印模板](#watermarking-set-template)
-            - [获取水印模板](#watermarking-get-template)
-
+    - [文件上传](#upload)
+        - [生成上传授权凭证（uploadToken）](#generate-upload-token)
+        - [Ruby 服务端上传文件](#upload-server-side)
+            - [开启断点续上传](#resumable-upload)
+        - [iOS / Android / Web 端直传文件说明](#upload-client-side)
+    - [文件下载](#download)
+        - [公有资源下载](#download-public-files)
+        - [私有资源下载](#download-private-files)
+            - [生成下载授权凭证（downloadToken）](#download-token)
+        - [高级特性](#other-download-features)
+            - [断点续下载](#resumable-download)
+            - [自定义 404 NotFound](#upload-file-for-not-found)
+    - [文件管理](#file-management)
+        - [查看单个文件属性信息](#stat)
+        - [复制单个文件](#copy)
+        - [移动单个文件](#move)
+        - [删除单个文件](#delete)
+        - [批量操作](#batch)
+            - [批量获取文件属性信息](#batch-get)
+            - [批量复制文件](#batch-copy)
+            - [批量移动文件](#batch-move)
+            - [批量删除文件](#batch-delete)
+    - [云处理](#cloud-processing)
+        - [图像](#image-processing)
+            - [查看图片属性信息](#image-info)
+            - [查看图片EXIF信息](#image-exif)
+            - [图像在线处理（缩略、裁剪、旋转、转化）](#image-mogrify-for-preview)
+            - [图像在线处理（缩略、裁剪、旋转、转化）后并持久化存储](#image-mogrify-for-save-as)
+        - 音频(TODO)
+        - 视频(TODO)
 - [贡献代码](#Contributing)
 - [许可证](#License)

+
 <a name="Installation"></a>

 ## 安装

-<a name="Usage"></a>
-
 在您 Ruby 应用程序的 `Gemfile` 文件中，添加如下一行代码：

    gem 'qiniu-rs'
@@ -71,11 +66,13 @@ title: Ruby SDK 使用指南 | 七牛云存储
    $ gem install qiniu-rs


-## 使用
+<a name="turn-on"></a>
+
+## 接入

 <a name="establish_connection!"></a>

-### 应用接入
+### 配置密钥（AccessKey / SecretKey）

 要接入七牛云存储，您需要拥有一对有效的 Access Key 和 Secret Key 用来进行签名认证。可以通过如下步骤获得：

@@ -89,7 +86,7 @@ title: Ruby SDK 使用指南 | 七牛云存储

 <a name="ror-init"></a>

-### Ruby On Rails 应用初始化设置
+### 针对 Ruby On Rails 网站应用初始化设置

 如果您使用的是 [Ruby on Rails](http://rubyonrails.org/) 框架，我们建议您在应用初始化启动的过程中，依次调用上述两个函数即可，操作如下：

@@ -104,13 +101,20 @@ title: Ruby SDK 使用指南 | 七牛云存储

 接下来，我们会逐一介绍此 SDK 提供的其他方法。

+
+<a name="Usage"></a>
+
+## 使用
+
 <a name="upload"></a>

-### 上传文件
+### 文件上传
+
+**注意**：如果您只是想要上传已存在您电脑本地或者是服务器上的文件到七牛云存储，可以直接使用七牛提供的 [qrsync](/v3/tools/qrsync/) 上传工具。如果是需要通过您的网站或是移动应用(App)上传文件，则可以接入使用此 SDK，详情参考如下文档说明。

 <a name="generate-upload-token"></a>

-#### 获取用于上传文件的临时授权凭证
+#### 生成上传授权凭证（uploadToken）

 要上传一个文件，首先需要调用 SDK 提供的 `Qiniu::RS.generate_upload_token` 函数来获取一个经过授权用于临时匿名上传的 `upload_token`——经过数字签名的一组数据信息，该 `upload_token` 作为文件上传流中 `multipart/form-data` 的一部分进行传输。

@@ -121,7 +125,9 @@ title: Ruby SDK 使用指南 | 七牛云存储
                                    :callback_url       => callback_url,
                                    :callback_body_type => callback_body_type,
                                    :customer           => end_user_id,
-                                    :escape             => allow_upload_callback_api
+                                    :escape             => allow_upload_callback_api,
+                                    :async_options      => async_callback_api_commands,
+                                    :return_body        => custom_response_body

 **参数**

@@ -153,13 +159,20 @@ title: Ruby SDK 使用指南 | 七牛云存储

    `foo=bar&w=$(imageInfo.width)&h=$(imageInfo.height)&exif=$(exif)`

+:async_options
+: 可选，字符串类型（String），用于设置文件上传成功后，执行指定的预转指令。参考 [uploadToken 之 asyncOps 说明](http://docs.qiniutek.com/v3/api/io/#uploadToken-asyncOps)
+
+:return_body
+: 可选，字符串类型（String），用于设置文件上传成功后，执行七牛云存储规定的回调API，并以 JSON 响应格式返回其执行结果。参考 [uploadToken 之 returnBody 说明](/v3/api/io/#uploadToken-returnBody)。
+
+
 **返回值**

 返回一个字符串类型（String）的用于上传文件用的临时授权 `upload_token`。

 <a name="upload-server-side"></a>

-#### 服务端上传文件
+#### Ruby 服务端上传文件

 通过 `Qiniu::RS.upload_file()` 方法可在客户方的业务服务器上直接往七牛云存储上传文件。该函数规格如下：

@@ -182,10 +195,10 @@ title: Ruby SDK 使用指南 | 七牛云存储
 : 必须，字符串类型（String），本地文件可被读取的有效路径

 :bucket
-: 必须，字符串类型（String），类似传统数据库里边的表名称，我们暂且将其叫做“资源表”，指定将该数据属性信息存储到具体的资源表中 。
+: 必须，字符串类型（String），空间名称。

 :key
-: 必须，字符串类型（String），类似传统数据库里边某个表的主键ID，给每一个文件一个UUID用于进行标示。
+: 必须，字符串类型（String），若把 Bucket 理解为关系性数据库的某个表，那么 key 类似数据库里边某个表的主键ID，需给每一个文件一个UUID用于进行标示。

 :mime_type
 : 可选，字符串类型（String），文件的 mime-type 值。如若不传入，SDK 会自行计算得出，若计算失败缺省使用 application/octet-stream 代替之。
@@ -212,7 +225,7 @@ title: Ruby SDK 使用指南 | 七牛云存储

 <a name="resumable-upload"></a>

-##### 断点续上传
+##### 开启断点续上传

 无需任何额外改动，SDK 提供的 `Qiniu::RS.upload_file()` 方法缺省支持断点续上传。默认情况下，SDK 会自动启用断点续上传的方式来上传超过 4MB 大小的文件。您也可以在 [应用接入](/v3/sdk/ruby/#establish_connection!) 时通过修改缺省配置来设置该阀值：

@@ -248,13 +261,93 @@ title: Ruby SDK 使用指南 | 七牛云存储
 : 整型，指定每次 http 若请求失败最多可以重试的次数，缺省为3次。该参数 SDK 全局有效。


+<a name="upload-client-side"></a>
+
+#### iOS / Android / Web 端直传文件说明
+
+客户端 iOS / Android / Web 上传流程和服务端上传类似，差别在于：客户端直传文件所需的 `uploadToken` 选择在客户方的业务服务器端生成，然后将其生成的 `uploadToken` 颁发给客户端。
+
+简单来讲，客户端上传流程分为两步：
+
+1. [服务端生成上传授权凭证（uploadToken）](#generate-upload-token)
+2. 客户端程序调用 [iOS](/v3/sdk/objc/) / [Android](/v3/sdk/android/) SDK 的文件上传方法进行上传
+
+如果是网页直传文件到七牛云存储，网页可以使用 JavaScript 动态实现 [七牛云存储上传API](/v3/api/io/#upload-file-by-html-form)。
+
+通过客户端直传文件，您的终端用户即可把数据（比如图片或视频）直接上传到七牛云存储服务器上，而无须经由您的服务端中转，终端用户上传数据始终是离他物理距离最近的七牛存储节点。当终端用户上传成功后，七牛云存储服务端会向您指定的 `callback_url` （一般在 [uploadToken](#generate-upload-token) 里边指定）发送回调数据（回调数据在客户端程序里边指定）。如果 `callback_url` 所指向的服务端处理完毕后输出 `JSON` 格式的数据，七牛云存储服务端会将该回调请求所得的 JSON 响应信息原封不动地返回给客户端应用程序。
+
+
+<a name="download"></a>
+
+### 文件下载
+
+七牛云存储上的资源下载分为 [公有资源下载](#download-public-files) 和 [私有资源下载](#download-private-files) 。
+
+私有（private）是 Bucket（空间）的一个属性，一个私有 Bucket 中的资源为私有资源，私有资源不可匿名下载。
+
+新创建的空间（Bucket）缺省为私有，也可以将某个 Bucket 设为公有，公有 Bucket 中的资源为公有资源，公有资源可以匿名下载。
+
+<a name="download-public-files"></a>
+
+#### 公有资源下载
+
+    [GET] http://<bucket>.qiniudn.com/<key>
+
+或者，
+
+    [GET] http://<绑定域名>/<key>
+
+绑定域名可以是自定义域名，可以在 [七牛云存储开发者自助网站](https://dev.qiniutek.com/buckets) 进行域名绑定操作。
+
+注意，尖括号不是必需，代表替换项。
+
+<a name="download-private-files"></a>
+
+#### 私有资源下载
+
+私有资源只能通过临时下载授权凭证(downloadToken)下载，下载链接格式如下：
+
+    [GET] http://<bucket>.qiniudn.com/<key>?token=<downloadToken>
+
+或者，
+
+    [GET] http://<绑定域名>/<key>?token=<downloadToken>
+
+<a name="download-token"></a>
+
+##### 生成下载授权凭证（downloadToken）
+
+`<downloadToken>` 可以使用 SDK 提供的如下方法生成：
+
+    Qiniu::RS.generate_download_token :expires_in => expires_in_seconds,
+                                      :pattern    => download_url_patterns
+
+**参数**
+
+expires_in
+: 可选，数字类型，用于设置上传 URL 的有效期，单位：秒，缺省为 3600 秒，即 1 小时后该下载授权凭证（downloadToken）不再有效。
+
+pattern
+: 必须，字符串类型，用于设置可匹配的下载链接。参考：[downloadToken pattern 详解](/v3/api/io/#download-token-pattern)
+
+
+<a name="other-download-features"></a>
+
+#### 高级特性
+
+<a name="resumable-download"></a>
+
+##### 断点续下载
+
+七牛云存储支持标准的断点续下载，参考：[云存储API之断点续下载](/v3/api/io/#download-by-range-bytes)
+
 <a name="upload-file-for-not-found"></a>

-##### 针对 NotFound 场景处理
+##### 自定义 404 NotFound

-您可以上传一个应对 HTTP 404 出错处理的文件，当您 [创建公开外链](#publish) 后，若公开的外链找不到该文件，即可使用您上传的“自定义404文件”代替之。要这么做，您只须使用 `Qiniu::RS.upload_file` 函数上传一个 `key` 为固定字符串类型的值 `errno-404` 即可。
+您可以上传一个应对 HTTP 404 出错处理的文件，当用户访问一个不存在的文件时，即可使用您上传的“自定义404文件”代替之。要这么做，您只须使用 `Qiniu::RS.upload_file` 函数上传一个 `key` 为固定字符串类型的值 `errno-404` 即可。

-除了使用 SDK 提供的方法，同样也可以借助七牛云存储提供的命令行辅助工具 [qboxrsctl](https://github.com/qiniu/devtools/tags) 达到同样的目的：
+除了使用 SDK 提供的方法，同样也可以借助七牛云存储提供的命令行辅助工具 [qboxrsctl](/v3/tools/qboxrsctl/) 达到同样的目的：

    qboxrsctl put <Bucket> <Key> <LocalFile>

@@ -262,23 +355,16 @@ title: Ruby SDK 使用指南 | 七牛云存储

 注意，每个 `<Bucket>` 里边有且只有一个 `errno-404` 文件，上传多个，最后的那一个会覆盖前面所有的。

-<a name="upload-client-side"></a>

-#### 客户端直传文件
+<a name="file-management"></a>

-客户端上传流程和服务端上传类似，差别在于：客户端直传文件所需的 `upload_token` 可以选择在客户方的业务服务器端生成，也可以选择在客户方的客户端程序里边生成。选择前者，可以和客户方的业务揉合得更紧密和安全些，比如防伪造请求。
-
-简单来讲，客户端上传流程也分为两步：
-
-1. 获取 `upload_token`（[用于上传文件的临时授权凭证](#generate-upload-token)）
-2. 将该 `upload_token` 作为文件上传流 `multipart/form-data` 中的一部分实现上传操作
-
-如果您的网络程序是从云端（服务端程序）到终端（手持设备应用）的架构模型，且终端用户有使用您移动端App上传文件（比如照片或视频）的需求，可以把您服务器得到的此 `upload_token` 返回给手持设备端的App，然后您的移动 App 可以使用 [七牛云存储 Objective-SDK （iOS）](http://docs.qiniutek.com/v3/sdk/objc/) 或 [七牛云存储 Android-SDK](http://docs.qiniutek.com/v3/sdk/android/) 的相关上传函数或参照 [七牛云存储API之文件上传](http://docs.qiniutek.com/v3/api/io/#upload) 直传文件。这样，您的终端用户即可把数据（比如图片或视频）直接上传到七牛云存储服务器上无须经由您的服务端中转，而且在上传之前，七牛云存储做了智能加速，终端用户上传数据始终是离他物理距离最近的存储节点。当终端用户上传成功后，七牛云存储服务端会向您指定的 `callback_url` 发送回调数据。如果 `callback_url` 所在的服务处理完毕后输出 `JSON` 格式的数据，七牛云存储服务端会将该回调请求所得的响应信息原封不动地返回给终端应用程序。
+### 文件管理

+文件管理包括对存储在七牛云存储上的文件进行查看、复制、移动和删除处理。

 <a name="stat"></a>

-### 查看文件属性信息
+#### 查看单个文件属性信息

    Qiniu::RS.stat(bucket, key)

@@ -287,10 +373,10 @@ title: Ruby SDK 使用指南 | 七牛云存储
 **参数**

 bucket
-: 必须，字符串类型（String），类似传统数据库里边的表名称，我们暂且将其叫做“资源表”，每份数据是属性信息都存储到具体的 bucket（资源表）中 。
+: 必须，字符串类型（String），空间名称。

 key
-: 必须，字符串类型（String），类似传统数据库里边某个表的主键ID，每一个文件最终都用一个唯一 `key` 进行标示。
+: 必须，字符串类型（String），若把 Bucket 理解为关系性数据库的某个表，那么 key 类似数据库里边某个表的主键ID，需给每一个文件一个UUID用于进行标示。

 **返回值**

@@ -315,69 +401,64 @@ mimeType
 putTime
 : 上传时间，单位是 百纳秒

-<a name="get"></a>

-### 获取文件下载链接（含文件属性信息）
+<a name="copy"></a>

-    Qiniu::RS.get(bucket, key, save_as = nil, expires_in = nil, version = nil)
+#### 复制单个文件

-`Qiniu::RS.get` 函数除了能像 `Qiniu::RS.stat` 一样返回文件的属性信息外，还能返回具体的下载链接及其有效时间。
+    Qiniu::RS.copy(source_bucket, source_key, target_bucket, target_key)
+
+可以通过 SDK 提供的 `Qiniu::RS.copy` 函数进行文件复制操作。

 **参数**

-bucket
-: 必须，字符串类型（String），类似传统数据库里边的表名称，我们暂且将其叫做“资源表”，每份数据是属性信息都存储到具体的 bucket（资源表）中 。
+source_bucket
+: 必须，字符串类型（String），指定源空间。

-key
-: 必须，字符串类型（String），类似传统数据库里边某个表的主键ID，每一个文件最终都用一个唯一 `key` 进行标示。
+source_key
+: 必须，字符串类型（String），指定源文件。

-save_as
-: 可选，字符串类型（String），文件下载时保存的具体名称
+target_bucket
+: 必须，字符串类型（String），指定要复制到的目标空间。

-expires_in
-: 可选，整型，用于设置下载 URL 的有效期，单位：秒，缺省为 3600 秒
-
-version
-: 可选，字符串类型（String），值为 `Qiniu::RS.stat` 或 `Qiniu::RS.get` 函数返回的 `hash` 字段的值，可用于断点续下载。
+target_key
+: 必须，字符串类型（String），指定要复制到目标空间的目标文件名。

 **返回值**

-如果请求失败，返回 `false`；否则返回如下一个 `Hash` 类型的结构：
+如果请求失败，返回 `false`；否则返回 `true` 。

-    {
-        "fsize"    => 3053,
-        "hash"     => "Fu9lBSwQKbWNlBLActdx8-toAajv",
-        "mimeType" => "application/x-ruby",
-        "url"      => "http://iovip.qbox.me/file/<an-authorized-token>",
-        "expires"  => 3600
-    }

-fsize
-: 表示文件总大小，单位是 Byte
+<a name="move"></a>

-hash
-: 文件的特征值，可以看做是基版本号
+#### 移动单个文件

-mimeType
-: 文件的 mime-type
+    Qiniu::RS.move(source_bucket, source_key, target_bucket, target_key)

-url
-: 文件的临时有效下载链接
+可以通过 SDK 提供的 `Qiniu::RS.move` 函数进行文件移动操作。

-expires
-: 文件下载链接的有效期，单位为 秒，过了 `expires` 秒之后，下载 `url` 将不再有效
+**参数**

-<a name="download"></a>
+source_bucket
+: 必须，字符串类型（String），指定源空间。

-### 只获取文件下载链接
+source_key
+: 必须，字符串类型（String），指定源文件。

-    Qiniu::RS.download(bucket, key, save_as = nil, expires_in = nil, version = nil)
+target_bucket
+: 必须，字符串类型（String），指定要移动到的目标空间。
+
+target_key
+: 必须，字符串类型（String），指定要移动到目标空间的目标文件名。
+
+**返回值**
+
+如果请求失败，返回 `false`；否则返回 `true` 。

-`Qiniu::RS.download` 函数参数与 `Qiniu::RS.get` 一样，差别在于，`Qiniu::RS.download` 只返回文件的下载链接。

 <a name="delete"></a>

-### 删除指定文件
+### 删除单个文件

    Qiniu::RS.delete(bucket, key)

@@ -386,31 +467,15 @@ expires
 **参数**

 bucket
-: 必须，字符串类型（String），类似传统数据库里边的表名称，我们暂且将其叫做“资源表”，每份数据是属性信息都存储到具体的 bucket（资源表）中 。
+: 必须，字符串类型（String），空间名称。

 key
-: 必须，字符串类型（String），类似传统数据库里边某个表的主键ID，每一个文件最终都用一个唯一 `key` 进行标示。
+: 必须，字符串类型（String），若把 Bucket 理解为关系性数据库的某个表，那么 key 类似数据库里边某个表的主键ID，需给每一个文件一个UUID用于进行标示。

 **返回值**

 如果删除成功，返回 `true`，否则返回 `false` 。

-<a name="drop"></a>
-
-### 删除所有文件（单个 bucket）
-
-    Qiniu::RS.drop(bucket)
-
-`Qiniu::RS.drop` 提供了删除整个 `bucket` 及其里边的所有 `key`，以及这些 `key` 关联的所有文件都将被删除。
-
-**参数**
-
-bucket
-: 必须，字符串类型（String），类似传统数据库里边的表名称，我们暂且将其叫做“资源表”，每份数据是属性信息都存储到具体的 bucket（资源表）中 。
-
-**返回值**
-
-如果删除成功，返回 `true`，否则返回 `false` 。

 <a name="batch"></a>

@@ -426,7 +491,7 @@ command
 : 必须，字符串类型（String），其值可以是 `stat`, `get`, `delete` 中的一种

 bucket
-: 必须，字符串类型（String），类似传统数据库里边的表名称，我们暂且将其叫做“资源表”，每份数据是属性信息都存储到具体的 bucket（资源表）中 。
+: 必须，字符串类型（String），空间名称。

 keys
 : 必须，数组类型（Array），所要操作 `key` 的集合。
@@ -449,9 +514,9 @@ keys
        ...
    ]

-<a name="batch_get"></a>
+<a name="batch-get"></a>

-#### 批量获取文件属性信息（含下载链接）
+#### 批量获取文件属性信息

    Qiniu::RS.batch_get(bucket, keys)

@@ -460,7 +525,7 @@ keys
 **参数**

 bucket
-: 必须，字符串类型（String），类似传统数据库里边的表名称，我们暂且将其叫做“资源表”，每份数据是属性信息都存储到具体的 bucket（资源表）中 。
+: 必须，字符串类型（String），空间名称。

 keys
 : 必须，数组类型（Array），所要操作 `key` 的集合。
@@ -483,23 +548,42 @@ keys
        ...
    ]

-<a name="batch_download"></a>

-#### 批量获取文件下载链接
+<a name="batch-copy"></a>

-    Qiniu::RS.batch_download(bucket, keys)
+#### 批量复制文件

-`Qiniu::RS.batch_download` 函数也是在 `Qiniu::RS.batch` 之上的封装，提供批量获取文件下载链接的功能。
+    Qiniu::RS.batch_copy(*args)

-参数同 `Qiniu::RS.batch_get` 的参数一样。
+等价于，
+
+    Qiniu::RS.batch_copy [source_bucket, source_key, target_bucket, target_key], ...
+
+`Qiniu::RS.batch_copy()` 的参数是一个可变长数组，其中每个数组其元素含义同 `Qiniu::RS.copy` 的参数一样。

 **返回值**

-如果请求失败，返回 `false`，否则返回一个 `Array` 类型的结构，其中每个元素是一个字符串类型的下载链接：
+如果批量删除成功，返回 `true` ，否则为 `false` 。

-    ["<download-link-1>", "<download-link-2>", …, "<download-link-N>"]

-<a name="batch_delete"></a>
+<a name="batch-move"></a>
+
+#### 批量移动文件
+
+    Qiniu::RS.batch_move(*args)
+
+等价于，
+
+    Qiniu::RS.batch_move [source_bucket, source_key, target_bucket, target_key], ...
+
+`Qiniu::RS.batch_move()` 的参数是一个可变长数组，其中每个数组其元素含义同 `Qiniu::RS.move` 的参数一样。
+
+**返回值**
+
+如果批量删除成功，返回 `true` ，否则为 `false` 。
+
+
+<a name="batch-delete"></a>

 #### 批量删除文件

@@ -513,112 +597,18 @@ keys

 如果批量删除成功，返回 `true` ，否则为 `false` 。

-<a name="publish"></a>

-### 创建公开外链
+<a name="cloud-processing"></a>

-    Qiniu::RS.publish(domain, bucket)
+### 云处理

-调用 `Qiniu::RS.publish` 函数可以将您在七牛云存储中的资源表 `bucket` 发布到某个 `domain` 下，`domain` 需要在 DNS 管理里边 CNAME 到 `iovip.qbox.me` 。
+<a name="image-processing"></a>

-这样，用户就可以通过 `http://<domain>/<key>` 来访问资源表 `bucket` 中的文件。键值为 `foo/bar/file` 的文件对应访问 URL 为 `http://<domain>/foo/bar/file`。 另外，`domain` 可以是一个真实的域名，比如 `www.example.com`，也可以是七牛云存储的二级路径，比如 `iovip.qbox.me/example` 。
+#### 图像

-例如：执行 `Qiniu::RS.publish("cdn.example.com", "EXAMPLE_BUCKET")` 后，那么键名为 `foo/bar/file` 的文件可以通过 `http://cdn.example.com/foo/bar/file` 访问。
+<a name="image-info"></a>

-**参数**
-
-domain
-: 必须，字符串类型（String），资源表发布的目标域名，例如：`cdn.example.com`
-
-bucket
-: 必须，字符串类型（String），要公开发布的资源表名称。
-
-**返回值**
-
-如果发布成功，返回 `true`，否则返回 `false` 。
-
-<a name="unpublish"></a>
-
-### 取消公开外链
-
-    Qiniu::RS.unpublish(domain)
-
-可以通过 SDK 提供的 `Qiniu::RS.unpublish` 函数来取消指定 `bucket` 的在某个 `domain` 域下的所有公开外链访问。
-
-**参数**
-
-domain
-: 必须，字符串类型（String），资源表已发布的目标域名名称，例如：`cdn.example.com`
-
-**返回值**
-
-如果撤销成功，返回 `true`，否则返回 `false` 。
-
-<a name="buckets"></a>
-
-### Bucket（资源表）管理
-
-<a name="mkbucket"></a>
-
-#### 创建 Bucket
-
-    Qiniu::RS.mkbucket(bucket_name)
-
-可以通过 SDK 提供的 `Qiniu::RS.mkbucket` 函数创建一个 bucket（资源表）。
-
-**参数**
-
-bucket_name
-: 必须，字符串类型（String），资源表 bucket 的名称。
-
-**返回值**
-
-如果指定 bucket 创建成功，返回 `true`，否则返回 `false` 。
-
-<a name="list-all-buckets"></a>
-
-#### 列出所有 Bucket
-
-    Qiniu::RS.buckets
-
-可以通过 SDK 提供的 `Qiniu::RS.buckets` 函数列出当前登录客户的所有 buckets（资源表）。
-
-**返回值**
-
-如果请求成功，返回一个 buckets 的列表（Array），否则返回 `false` 。
-
-    ["Bucket1", "Bucket2", …, "BucketN"]
-
-<a name="set-protected"></a>
-
-#### 访问控制
-
-    Qiniu::RS.set_protected(bucket_name, protected_mode)
-
-可以通过 SDK 提供的 `Qiniu::RS.set_protected` 函数来设置指定 bucket 的访问属性，一般在水印处理时作原图保护用。
-
-**参数**
-
-bucket_name
-: 必须，字符串类型（String），指定资源表 bucket 的名称。
-
-protected_mode
-: 必须，整型，值为 1 或者 0，值为 1 表示启用保护模式，反之亦然。
-
-该函数不常用，一般在特殊场景下会用到。比如给图片打水印时，首先要设置原图保护，禁用公开的图像处理操作，采用水印的特殊图像处理，而保护原图就可以通过该函数操作实现。
-
-**返回值**
-
-如果设置成功，返回 `true`，否则返回 `false` 。
-
-
-<a name="op-image"></a>
-
-### 图像处理
-
-<a name="image_info"></a>
-
-#### 查看图片属性信息
+##### 查看图片属性信息

    Qiniu::RS.image_info(url)

@@ -652,9 +642,9 @@ height
 colorModel
 : 原始图片着色模式

-<a name="image_exif"></a>
+<a name="image-exif"></a>

-#### 查看图片EXIF信息
+##### 查看图片EXIF信息

    Qiniu::RS.image_exif(url)

@@ -669,32 +659,9 @@ url

 如果参数 `url` 所代表的图片没有 EXIF 信息，返回 `false`。否则，返回一个包含 EXIF 信息的 Hash 结构。

+<a name="image-mogrify-for-preview"></a>

-<a name="image_preview_url"></a>
-
-#### 获取指定规格的缩略图预览地址
-
-    Qiniu::RS.image_preview_url(url, spec)
-
-使用 SDK 提供的 `Qiniu::RS.image_preview_url` 方法，可以基于一张存储于七牛云存储服务器上的图片，针对其下载链接，以及指定的缩略图规格类型，来获取该张图片的缩略图地址。
-
-**参数**
-
-url
-: 必须，字符串类型（String），图片的下载链接，需是 `Qiniu::RS.get`（或`Qiniu::RS.batch_get`）函数返回值中 `url` 字段的值，或者是 `Qiniu::RS.download`（或`Qiniu::RS.batch_download`）函数返回的下载链接。且文件本身必须是图片。
-
-spec
-: 可选，字符串或整型的枚举值，指定缩略图的具体规格，参考 [七牛云存储API之缩略图预览](/v3/api/foimg/#fo-imagePreview) 和 [自定义缩略图规格](/v3/api/foimg/#fo-imagePreviewEx) 。该值缺省为 0 （即输出宽800px高600px图片质量为85的缩略图）
-
-**返回值**
-
-返回一个字符串类型的缩略图 URL
-
-
-
-<a name="image_mogrify_preview_url"></a>
-
-#### 高级图像处理（缩略、裁剪、旋转、转化）
+##### 图像在线处理（缩略、裁剪、旋转、转化）

 `Qiniu::RS.image_mogrify_preview_url()` 方法支持将一个存储在七牛云存储的图片进行缩略、裁剪、旋转和格式转化处理，该方法返回一个可以直接预览缩略图的URL。

@@ -726,10 +693,9 @@ mogrify_options

 返回一个可以预览最终缩略图的URL，String 类型。

+<a name="image-mogrify-for-save-as"></a>

-<a name="image_mogrify_save_as"></a>
-
-#### 高级图像处理（缩略、裁剪、旋转、转化）并持久化存储处理结果
+#### 图像在线处理（缩略、裁剪、旋转、转化）后并持久化存储

 `Qiniu::RS.image_mogrify_save_as()` 方法支持将一个存储在七牛云存储的图片进行缩略、裁剪、旋转和格式转化处理，并且将处理后的缩略图作为一个新文件持久化存储到七牛云存储服务器上，这样就可以供后续直接使用而不用每次都传入参数进行图像处理。

@@ -792,245 +758,20 @@ mogrify_options
      thumbnail = Qiniu::RS.get(target_bucket, target_key)
      puts thumbnail["url"]

-      # 您可以选择将存放缩略图的 bucket 公开，这样就可以直接以外链的形式访问到缩略图，而不用走API获取下载URL。
-      result = Qiniu::RS.publish("pic.example.com", target_bucket)
+      # 您可以选择将存放缩略图的 bucket 公开，这样就可以直接以外链的形式访问到缩略图，而不用走API获取下载URL，就可以直接以如下方式访问缩略图：

-      # 然后将 pic.example.com CNAME 到 iovip.qbox.me ，就可以直接以如下方式访问缩略图
-      # [GET] http://pic.example.com/<target_key>
+      # [GET] http://<bucket>.qiniudn.com/<target_key>
    end


-<a name="image-watermarking"></a>
-
-## 高级图像处理（水印）
-
-<a name="watermarking-pre-work"></a>
-
-### 水印准备工作
-
-为了保护用户原图和方便用户访问打过水印之后的图片，在经水印作用之前，需进行以下一些设置：
-
-1. [设置原图保护](#watermarking-set-protected)
-2. [设置水印预览图URL分隔符](#watermarking-set-sep)
-3. [设置水印预览图规格别名](#watermarking-set-style)
-
-<a name="watermarking-set-protected"></a>
-
-#### 1. 设置原图保护
-
-用户的图片打上水印后，其原图不可见。通过给原图所在的 Bucket（资源表）设置访问控制，可以达到保护原图的目的，详情请参考 [Bucket（资源表）管理之访问控制](set-protected)。
-
-设置原图保护也可以借助七牛云存储提供的命令行辅助工具 [qboxrsctl](https://github.com/qiniu/devtools/tags) 来实现：
-
-    // 为<Bucket>下面的所有图片设置原图保护
-    qboxrsctl protected <Bucket> <Protected>
-
-<a name="watermarking-set-sep"></a>
-
-#### 2. 设置水印预览图URL分隔符
-
-没有设置水印前，用户可以通过如下公开链接的形式访问原图（[创建公开外链后的情况下](/v3/api/io/#rs-Publish)）：
-
-    http://<Domain>/<Key>
-
-设置水印后，其原图属性为私有，不能再通过这种形式访问。但是用户可以在原图的 `<Key>` 后面加上“分隔符”，以及相应的水印风格样式来访问打水印后的图片。例如，假设您为用户设定的访问水印图的分隔符为中划线 “-”，那么用户可以通过这种形式来访问打水印后的图片：
-
-    http://<Domain>/<Key>-/imageView/<Mode>/w/<Width>/h/<Height>/q/<Quality>/format/<Format>/sharpen/<Sharpen>/watermark/<HasWatermark>
-
-其中，`HasWatermark` 参数为 `0` （或者没有）表示不打水印，为 `1` 表示给图片打水印。
-
-通过 SDK 提供的 `Qiniu::RS.set_separator` 函数可以设置水印预览图URL分隔符：
-
-    Qiniu::RS.set_separator(bucket_name, separator)
-
-**参数**
-
-bucket_name
-: 必须，字符串类型（String），图片所在的 Bucket（资源表） 名称
-
-separator
-: 必须，字符串类型（String），源图片与预览图规格之间的分割符
-
-**返回值**
-
-操作成功返回 `true`，否则返回 `false`。
-
-除了使用 SDK 提供的方法，同样可以借助七牛云存储提供的命令行辅助工具 [qboxrsctl](https://github.com/qiniu/devtools/tags) 达到同样的目的：
-
-    // 设置预览图分隔符
-    qboxrsctl separator <Bucket> <Sep>
-
-<a name="watermarking-set-style"></a>
-
-#### 3. 设置水印预览图规格别名
-
-通过步骤2中所描述的水印预览图 URL 来访问打水印后的图片毕竟较为繁琐，因此可以通过为该水印预览图规格设置“别名”的形式来访问。如：
-
-别名（Name） | 规格（Style） | 说明
----------- | ------------ | -------
-small.jpg   | imageView/0/w/120/h/90 | 大小为 120x90，不打水印
-middle.jpg  | imageView/0/w/440/h/330/watermark/1 | 大小为 440x330，打水印
-large.jpg   | imageView/0/w/1280/h/760/watermark/1 | 大小为 1280x760，打水印
-
-
-SDK 提供了 `Qiniu::RS.set_style` 函数可以定义预览图规格别名，该函数原型如下：
-
-    Qiniu::RS.set_style(bucket, name, style)
-
-**参数**
-
-bucket
-: 必须，字符串类型（String），图片所在的 Bucket（资源表） 名称
-
-name
-: 必须，字符串类型（String），预览图规格名称（别名）
-
-style
-: 必须，字符串类型（String），具体的规格样式
-
-**返回值**
-
-操作成功返回 `true`，否则返回 `false` 。
-
-除了使用 SDK 提供的方法，同样也可以借助七牛云存储提供的命令行辅助工具 [qboxrsctl](https://github.com/qiniu/devtools/tags) 达到同样的目的：
-
-    // 为 <Buecket> 下面的所有图片设置名为 <Name> 的 <Style>
-    qboxrsctl style <Bucket> <Name> <Style>
-
-无论是通过 SDK 提供的方法还是命令行辅助工具操作，在设置完成后，即可通过通过以下方式来访问设定规格后的图片：
-
-	// 其中 “-” 为分隔符，“small.jpg” 为预览图规格别名
-	[GET] http://<Domain>/<Key>-small.jpg
-
-	// 其中 “!” 为分隔符，“middle.jpg” 为预览图规格别名
-	[GET] http://<Domain>/<Key>!middle.jpg
-
-	// 其中 “@” 为分隔符，“large.jpg” 为预览图规格别名
-    [GET] http://<Domain>/<Key>@large.jpg
-
-以上这些设置水印模板前的准备只需操作一次，即可对后续设置的所有水印模板生效。由于是一次性操作，建议使用 qboxrsctl 命令行辅助工具进行相关设置。
-
-**取消水印预览图规格设置**
-
-您也可以为某个水印预览图规格取消“别名”设置，SDK 提供了相应的方法：
-
-    Qiniu::RS.unset_style(bucket, name)
-
-**参数**
-
-bucket
-: 必须，字符串类型（String），图片所在的 Bucket（资源表） 名称
-
-name
-: 必须，字符串类型（String），预览图规格名称（别名）
-
-**返回值**
-
-操作成功返回 `true`，否则返回 `false` 。
-
-除了使用 SDK 提供的方法，同样也可以借助七牛云存储提供的命令行辅助工具 [qboxrsctl](https://github.com/qiniu/devtools/tags) 达到同样的目的：
-
-    // 取消预览图规格别名为 <Name> 的 Style
-    qboxrsctl unstyle <Bucket> <Name>
-
-
-<a name="watermarking-set-template"></a>
-
-### 设置水印模板
-
-给图片加水印，SDK 提供了设置水印模板的函数：`Qiniu::RS.set_watermark` ，通过该函数操作，客户方可以设置通用的水印模板，也可以为客户方的每一个终端用户分别设置一个水印模板。
-
-`Qiniu::RS.set_watermark` 函数原型如下：
-
-    Qiniu::RS.set_watermark(customer_id, {
-        :font     => <FontName>,
-        :fontsize => <FontSize>,
-        :fill     => <FillColor>,
-        :text     => <WatermarkText>,
-        :bucket   => <LogoBucket>,
-        :dissolve => <Dissolve>,
-        :gravity  => <Gravity>,
-        :dx       => <DistanceX>,
-        :dy       => <DistanceY>
-    })
-
-**参数**：
-
-1. `customer_id = <EndUserID>`
-: 客户方终端用户标识。如果`customer_id`为 `nil`，则表示设置默认水印模板。作为面向终端用户的服务提供商，您可以为不同的用户设置不同的水印模板，只需在设置水印模板的时候传入`customer_id`参数。如果该参数未设置，则表示为终端用户设置一个默认模板。举例：假如您为终端用户提供的是一个手机拍照软件，用户拍照后图片存储于七牛云存储服务器。为了给每个用户所上传的图片打上标有该用户用户名的水印，您可以为该用户设置一个水印模板，其水印文字可以是该终端用户的用户名。但如果您未给该终端用户设置模板，那么水印上的所有设置都是默认的（其文字部分可能是你们自己设置的企业标识）。该 `customer_id` 和 [Qiniu::RS.generate_upload_token](#generate-upload-token) 中的 `customer` 参数含义一致，结合这点，您很容易想明白为什么 `Qiniu::RS.generate_upload_token` 函数中会有 `customer` 这个可选参数还有 `Qiniu::RS.set_watermark` 函数中会有 `customer_id` 参考以及两者间的关系。
-
-2. `:font => <FontName>`
-: 为水印上的文字设置一个默认的字体名，可选。
-
-3. `:fontsize => <FontSize>`
-: 字体大小，可选，0表示默认，单位: 缇，等于 1/20 磅。
-
-4. `:fill => <FillColor>`
-: 字体颜色，可选。
-
-5. `:text => <WatermarkText>`
-: 水印文字，必须，图片用 \0 - \9 占位。
-
-6. `:bucket => <ImageFromBucket>`
-: 如果水印中有图片，需要指定图片所在的 `RS Bucket` 名称，可选。
-
-7. `:dissolve => <Dissolve>`
-: 透明度，可选，字符串，如50%。
-
-8. `:gravity => <Gravity>`
-: 位置，可选，字符串，默认为右下角（SouthEast）。可选的值包括：NorthWest、North、NorthEast、West、Center、East、SouthWest、South和SouthEast。
-
-9. `:dx => <DistanceX>`
-: 横向边距，可选，默认值为10，单位px。
-
-10. `:dy => <DistanceY>`
-: 纵向边距，可选，默认值为10，单位px。
-
-**返回值**
-
-操作成功返回 `true`，否则返回 `false` 。
-
-
-<a name="watermarking-get-template"></a>
-
-### 获取水印模板
-
-SDK 提供了 `Qiniu::RS.get_watermark` 函数获取指定终端用户或者缺省的水印模板。该函数原型如下：
-
-    Qiniu::RS.get_watermark(customer_id = nil)
-
-**参数**
-
-customer_id
-: 客户方终端用户标识，可选，字符串类型，含义同 [Qiniu::RS.set_watermark](#watermarking-set-template) 函数中的 `customer_id` 参数。该值缺省为 `nil`，如果该值为 `nil`，则表示取默认的通用水印模板。
-
-**返回值**
-
-如果请求成功，返回如下一段 Hash 结构的数据；否则返回 `false`。
-
-    {
-    	font: <FontName>
-    	fontsize: <FontSize>
-    	fill: <FillColor>
-    	text: <WatermarkText>
-    	bucket: <LogoBucket>
-    	dissolve: <Dissolve>
-    	gravity: <Gravity>
-    	dx: <DistanceX>
-    	dy: <DistanceY>
-    }
-
-请求成功后返回数据的含义同 [设置水印模板](#watermarking-set-template) 时传入的参数一致。
-
-
 <a name="Contributing"></a>

 ## 贡献代码

-七牛云存储 Ruby SDK 源码地址：[https://github.com/qiniu/ruby-sdk](https://github.com/qiniu/ruby-sdk)
+七牛云存储 Ruby SDK 源码地址：<https://github.com/qiniu/ruby-sdk>

-1. 登录 [github.com](https://github.com)
-2. Fork [https://github.com/qiniu/ruby-sdk](https://github.com/qiniu/ruby-sdk)
+1. 登录 <https://github.com>
+2. Fork <https://github.com/qiniu/ruby-sdk>
 3. 创建您的特性分支 (`git checkout -b my-new-feature`)
 4. 提交您的改动 (`git commit -am 'Added some feature'`)
 5. 将您的改动记录提交到远程 `git` 仓库 (`git push origin my-new-feature`)
@@ -17,6 +17,7 @@ module Qiniu
    autoload :AccessToken, 'qiniu/tokens/access_token'
    autoload :QboxToken, 'qiniu/tokens/qbox_token'
    autoload :UploadToken, 'qiniu/tokens/upload_token'
+    autoload :DownloadToken, 'qiniu/tokens/download_token'
    autoload :Abstract, 'qiniu/rs/abstract'

    class << self
@@ -62,6 +63,7 @@ module Qiniu
        code == StatusOK
      end

+=begin
      def set_watermark(customer_id, options = {})
        code, data = EU.set_watermark(customer_id, options)
        code == StatusOK
@@ -71,6 +73,7 @@ module Qiniu
        code, data = EU.get_watermark(customer_id)
        code == StatusOK ? data : false
      end
+=end

      def put_auth(expires_in = nil, callback_url = nil)
        code, data = IO.put_auth(expires_in, callback_url)
@@ -100,12 +103,14 @@ module Qiniu
      end

      def upload_file opts = {}
-        [:uptoken, :file, :bucket, :key].each do |opt|
-          raise MissingArgsError, [opt] unless opts.has_key?(opt)
-        end
+        uncontained_opts = [:uptoken, :file, :bucket, :key] - opts.keys
+        raise MissingArgsError, uncontained_opts unless uncontained_opts.empty?
+
        source_file = opts[:file]
        raise NoSuchFileError, source_file unless File.exist?(source_file)
+
        opts[:enable_resumable_upload] = true unless opts.has_key?(:enable_resumable_upload)
+
        if opts[:enable_resumable_upload] && File::size(source_file) > Config.settings[:block_size]
          code, data = UP.upload_with_token(opts[:uptoken],
                                            opts[:file],
@@ -146,6 +151,16 @@ module Qiniu
        code == StatusOK ? data["url"] : false
      end

+      def copy(source_bucket, source_key, target_bucket, target_key)
+        code, data = RS.copy(source_bucket, source_key, target_bucket, target_key)
+        code == StatusOK
+      end
+
+      def move(source_bucket, source_key, target_bucket, target_key)
+        code, data = RS.move(source_bucket, source_key, target_bucket, target_key)
+        code == StatusOK
+      end
+
      def delete(bucket, key)
        code, data = RS.delete(bucket, key)
        code == StatusOK
@@ -166,6 +181,16 @@ module Qiniu
        code == StatusOK ? data : false
      end

+      def batch_copy(*args)
+        code, data = RS.batch_copy(args)
+        code == StatusOK
+      end
+
+      def batch_move(*args)
+        code, data = RS.batch_move(args)
+        code == StatusOK
+      end
+
      def batch_download(bucket, keys)
        code, data = RS.batch_get(bucket, keys)
        return false unless code == StatusOK
@@ -227,6 +252,17 @@ module Qiniu
        #token_obj.callback_body_type = opts[:callback_body_type]
        #token_obj.customer = opts[:customer]
        #token_obj.escape = opts[:escape]
+        #token_obj.async_options = opts[:async_options]
+        #token_obj.return_body = opts[:return_body]
+        token_obj.generate_token
+      end
+
+      def generate_download_token(opts = {})
+        token_obj = DownloadToken.new(opts)
+        token_obj.access_key = Config.settings[:access_key]
+        token_obj.secret_key = Config.settings[:secret_key]
+        #token_obj.expires_in = opts[:expires_in]
+        #token_obj.pattern = opts[:pattern]
        token_obj.generate_token
      end

@@ -4,9 +4,6 @@ module Qiniu
  module RS

    class Exception < RuntimeError
-      def to_s
-        inspect
-      end
    end

    class ResponseError < Exception
@@ -26,6 +26,16 @@ module Qiniu
          Auth.request url
        end

+        def copy(source_bucket, source_key, target_bucket, target_key)
+          uri = _generate_cp_or_mv_opstr('copy', source_bucket, source_key, target_bucket, target_key)
+          Auth.request Config.settings[:rs_host] + uri
+        end
+
+        def move(source_bucket, source_key, target_bucket, target_key)
+          uri = _generate_cp_or_mv_opstr('move', source_bucket, source_key, target_bucket, target_key)
+          Auth.request Config.settings[:rs_host] + uri
+        end
+
        def delete(bucket, key)
          Auth.request Config.settings[:rs_host] + '/delete/' + encode_entry_uri(bucket, key)
        end
@@ -61,6 +71,14 @@ module Qiniu
          batch("stat", bucket, keys)
        end

+        def batch_copy(*args)
+          _batch_cp_or_mv('copy', args)
+        end
+
+        def batch_move(*args)
+          _batch_cp_or_mv('move', args)
+        end
+
        def batch_delete(bucket, keys)
          batch("delete", bucket, keys)
        end
@@ -77,6 +95,22 @@ module Qiniu
          save_as(bucket, key, source_image_url, mogrify_params_string)
        end

+        private
+
+        def _generate_cp_or_mv_opstr(command, source_bucket, source_key, target_bucket, target_key)
+          source_encoded_entry_uri = encode_entry_uri(source_bucket, source_key)
+          target_encoded_entry_uri = encode_entry_uri(target_bucket, target_key)
+          %Q(/#{command}/#{source_encoded_entry_uri}/#{target_encoded_entry_uri})
+        end
+
+        def _batch_cp_or_mv(command, *op_args)
+          execs = []
+          op_args.each do |e|
+            execs << 'op=' + _generate_cp_or_mv_opstr(command, e[0], e[1], e[2], e[3]) if e.size == 4
+          end
+          Auth.request Config.settings[:rs_host] + "/batch?" + execs.join("&")
+        end
+
      end
    end
  end
@@ -14,6 +14,9 @@ module Qiniu
  module RS
    module UP

+      PROGRESS_TMP_FILE = 'progresses'
+      CHECKSUM_TMP_FILE = 'ctxes'
+
      module AbstractClass
        class ChunkProgressNotifier
          include Qiniu::RS::Abstract
@@ -29,78 +32,58 @@ module Qiniu
      end

      class ChunkProgressNotifier < AbstractClass::ChunkProgressNotifier
+          attr_reader :tmpdata
          def initialize(id)
-              @data = UP::ProgressData.new(id)
+              @tmpdata = UP::TmpData.new(id, PROGRESS_TMP_FILE)
          end
          def notify(index, progress)
-              @data.set_progresses(index, progress)
-              logmsg = "chunk #{progress[:offset]/Config.settings[:chunk_size]} in block #{index} successfully uploaded.\n" +
-                       "{ctx:#{progress[:ctx]}, offset:#{progress[:offset]}, restsize:#{progress[:restsize]}, status_code:#{progress[:status_code]}}"
+              @tmpdata.set(index, progress)
+              logmsg = "chunk #{progress[:offset]/Config.settings[:chunk_size]} in block #{index} successfully uploaded.\n" + progress.to_s
              Utils.debug(logmsg)
          end
      end

      class BlockProgressNotifier < AbstractClass::BlockProgressNotifier
+          attr_reader :tmpdata
          def initialize(id)
-              @data = UP::ProgressData.new(id)
+              @tmpdata = UP::TmpData.new(id, CHECKSUM_TMP_FILE)
          end
          def notify(index, checksum)
-              @data.set_checksums(index, checksum)
+              @tmpdata.set(index, checksum)
+              Utils.debug "block #{index}: {ctx: #{checksum}} successfully uploaded."
              Utils.debug "block #{index}: {checksum: #{checksum}} successfully uploaded."
          end
      end

-      class ProgressData
-          def initialize(id)
-              @id = id
-              @tmpdir = Config.settings[:tmpdir] + File::SEPARATOR + @id
-              FileUtils.mkdir_p(@tmpdir) unless Dir.exists?(@tmpdir)
-              @checksum_file = @tmpdir + File::SEPARATOR + 'checksums'
-              @progress_file = @tmpdir + File::SEPARATOR + 'progresses'
+      class TmpData
+          def initialize(dir, filename)
+              @tmpdir = Config.settings[:tmpdir] + File::SEPARATOR + dir
+              FileUtils.mkdir_p(@tmpdir) unless File.directory?(@tmpdir)
+              @tmpfile = @tmpdir + File::SEPARATOR + filename
          end

-          def get_checksums
-              File.exist?(@checksum_file) ? YAML.load_file(@checksum_file) : []
-          end
-
-          def get_progresses
-              File.exist?(@progress_file) ? YAML.load_file(@progress_file) : []
-          end
-
-          def set_checksums(index, checksum)
-              checksums = get_checksums
-              checksums[index] = checksum
-              File.open(@checksum_file, "w") do |f|
-                  YAML::dump(checksums, f)
-                  Utils.debug %Q(Updating tmpfile: #{@checksum_file})
+          def init(values)
+              File.open(@tmpfile, "w") do |f|
+                  YAML::dump(values, f)
+                  Utils.debug %Q(Initializing tmpfile: #{@tmpfile})
              end
          end

-          def set_progresses(index, progress)
-              progresses = get_progresses
-              progresses[index] = progress
-              File.open(@progress_file, "w") do |f|
-                  YAML::dump(progresses, f)
-                  Utils.debug %Q(Updating tmpfile: #{@progress_file})
-              end
+          def all
+              File.exist?(@tmpfile) ? YAML.load_file(@tmpfile) : []
          end

-          def init_checksums(checksums)
-              File.open(@checksum_file, "w") do |f|
-                  YAML::dump(checksums, f)
-                  Utils.debug %Q(Initializing tmpfile: #{@checksum_file})
-              end
-          end
-
-          def init_progresses(progresses)
-              File.open(@progress_file, "w") do |f|
-                  YAML::dump(progresses, f)
-                  Utils.debug %Q(Initializing tmpfile: #{@progress_file})
+          def set(index, value)
+              values = all
+              values[index] = value
+              File.open(@tmpfile, "w") do |f|
+                  YAML::dump(values, f)
+                  Utils.debug %Q(Updating tmpfile: #{@tmpfile})
              end
          end

          def sweep!
-              FileUtils.rm_r(@tmpdir)
+              FileUtils.rm_r(@tmpdir) if File.directory?(@tmpdir)
          end
      end

@@ -117,7 +100,6 @@ module Qiniu
                              customer = nil,
                              callback_params = nil,
                              rotate = nil)
-          raise NoSuchFileError, local_file unless File.exist?(local_file)
          begin
            ifile = File.open(local_file, 'rb')
            fh = FileData.new(ifile)
@@ -127,11 +109,7 @@ module Qiniu
              mime = MIME::Types.type_for local_file
              mime_type = mime.empty? ? 'application/octet-stream' : mime[0].content_type
            end
-            if fsize > Config.settings[:block_size]
-              code, data = _resumable_upload(uptoken, fh, fsize, bucket, key, mime_type, custom_meta, customer, callback_params, rotate)
-            else
-              code, data = IO.upload_with_token(uptoken, local_file, bucket, key, mime_type, custom_meta, callback_params, true, rotate)
-            end
+            code, data = _resumable_upload(uptoken, fh, fsize, bucket, key, mime_type, custom_meta, customer, callback_params, rotate)
            [code, data]
          ensure
            ifile.close unless ifile.nil?
@@ -162,20 +140,21 @@ module Qiniu
        end

        def _new_block_put_progress_data
-          {:ctx => nil, :offset => 0, :restsize => nil, :status_code => nil}
+          {:ctx => nil, :offset => 0, :restsize => nil, :status_code => nil, :host => nil}
        end

-        def _call_binary_with_token(uptoken, url, data, retry_times = 0)
+        def _call_binary_with_token(uptoken, url, data, content_type = nil, retry_times = 0)
          options = {
              :method => :post,
              :content_type => 'application/octet-stream',
              :upload_signature_token => uptoken
          }
+          options[:content_type] = content_type if !content_type.nil? && !content_type.empty?
          code, data = http_request url, data, options
          unless Utils.is_response_ok?(code)
              retry_times += 1
              if Config.settings[:auto_reconnect] && retry_times < Config.settings[:max_retry_times]
-                  return _call_binary_with_token(uptoken, url, data, retry_times)
+                  return _call_binary_with_token(uptoken, url, data, options[:content_type], retry_times)
              end
          end
          [code, data]
@@ -186,12 +165,12 @@ module Qiniu
            _call_binary_with_token(uptoken, url, body)
        end

-        def _putblock(uptoken, ctx, offset, body)
-            url = Config.settings[:up_host] + "/bput/#{ctx}/#{offset}"
+        def _putblock(uphost, uptoken, ctx, offset, body)
+            url = uphost + "/bput/#{ctx}/#{offset}"
            _call_binary_with_token(uptoken, url, body)
        end

-        def _resumable_put_block(uptoken, fh, block_index, block_size, chunk_size, progress, retry_times = 1, notifier)
+        def _resumable_put_block(uptoken, fh, block_index, block_size, chunk_size, progress, retry_times, notifier)
            code, data = 0, {}
            fpath = fh.path
            # this block has never been uploaded.
@@ -214,6 +193,7 @@ module Qiniu
                        progress[:offset] = body_length
                        progress[:restsize] = block_size - body_length
                        progress[:status_code] = code
+                        progress[:host] = data["host"]
                        if !notifier.nil? && notifier.respond_to?("notify")
                            notifier.notify(block_index, progress)
                        end
@@ -236,13 +216,14 @@ module Qiniu
                    if result_length != body_length
                        raise FileSeekReadError.new(fpath, block_index, seek_pos, body_length, result_length)
                    end
-                    code, data = _putblock(uptoken, progress[:ctx], progress[:offset], body)
+                    code, data = _putblock(progress[:host], uptoken, progress[:ctx], progress[:offset], body)
                    body_crc32 = Zlib.crc32(body)
                    if Utils.is_response_ok?(code) && data["crc32"] == body_crc32
                        progress[:ctx] = data["ctx"]
                        progress[:offset] += body_length
                        progress[:restsize] -= body_length
                        progress[:status_code] = code
+                        progress[:host] = data["host"]
                        if !notifier.nil? && notifier.respond_to?("notify")
                            notifier.notify(block_index, progress)
                        end
@@ -280,7 +261,8 @@ module Qiniu
                    end
                    code, data = _resumable_put_block(uptoken, fh, block_index, block_size, Config.settings[:chunk_size], progresses[block_index], Config.settings[:max_retry_times], chunk_notifier)
                    if Utils.is_response_ok?(code)
-                        checksums[block_index] = data["checksum"]
+                        #checksums[block_index] = data["checksum"]
+                        checksums[block_index] = data["ctx"]
                        if !block_notifier.nil? && block_notifier.respond_to?("notify")
                            block_notifier.notify(block_index, checksums[block_index])
                        end
@@ -290,7 +272,7 @@ module Qiniu
            return [code, data]
        end

-        def _mkfile(uptoken, entry_uri, fsize, checksums, mime_type = nil, custom_meta = nil, customer = nil, callback_params = nil, rotate = nil)
+        def _mkfile(uphost, uptoken, entry_uri, fsize, checksums, mime_type = nil, custom_meta = nil, customer = nil, callback_params = nil, rotate = nil)
          path = '/rs-mkfile/' + Utils.urlsafe_base64_encode(entry_uri) + "/fsize/#{fsize}"
          path += '/mimeType/' + Utils.urlsafe_base64_encode(mime_type) if !mime_type.nil? && !mime_type.empty?
          path += '/meta/' + Utils.urlsafe_base64_encode(custom_meta) if !custom_meta.nil? && !custom_meta.empty?
@@ -298,42 +280,45 @@ module Qiniu
          callback_query_string = Utils.generate_query_string(callback_params) if !callback_params.nil? && !callback_params.empty?
          path += '/params/' + Utils.urlsafe_base64_encode(callback_query_string) if !callback_query_string.nil? && !callback_query_string.empty?
          path += '/rotate/' + rotate if !rotate.nil? && rotate.to_i >= 0
-          url = Config.settings[:up_host] + path
-          body = ''
-          checksums.each do |checksum|
-              body += Utils.urlsafe_base64_decode(checksum)
-          end
-          _call_binary_with_token(uptoken, url, body)
+          url = uphost + path
+          #body = ''
+          #checksums.each do |checksum|
+          #    body += Utils.urlsafe_base64_decode(checksum)
+          #end
+          body = checksums.join(',')
+          _call_binary_with_token(uptoken, url, body, 'text/plain')
        end

        def _resumable_upload(uptoken, fh, fsize, bucket, key, mime_type = nil, custom_meta = nil, customer = nil, callback_params = nil, rotate = nil)
          block_count = _block_count(fsize)
-          progress_data = ProgressData.new(key)
-          checksums = progress_data.get_checksums
-          progresses = progress_data.get_progresses
-          if checksums.empty?
-              block_count.times{checksums << ''}
-              progress_data.init_checksums(checksums)
-          end
-          if progresses.empty?
-              block_count.times{progresses << _new_block_put_progress_data}
-              progress_data.init_progresses(progresses)
-          end
          chunk_notifier = ChunkProgressNotifier.new(key)
          block_notifier = BlockProgressNotifier.new(key)
+          progresses = chunk_notifier.tmpdata.all
+          if progresses.empty?
+              block_count.times{progresses << _new_block_put_progress_data}
+              chunk_notifier.tmpdata.init(progresses)
+          end
+          checksums = block_notifier.tmpdata.all
+          if checksums.empty?
+              block_count.times{checksums << ''}
+              block_notifier.tmpdata.init(checksums)
+          end
          code, data = _resumable_put(uptoken, fh, checksums, progresses, block_notifier, chunk_notifier)
          if Utils.is_response_ok?(code)
+            uphost = data["host"]
            entry_uri = bucket + ':' + key
-            code, data = _mkfile(uptoken, entry_uri, fsize, checksums, mime_type, custom_meta, customer, callback_params, rotate)
+            code, data = _mkfile(uphost, uptoken, entry_uri, fsize, checksums, mime_type, custom_meta, customer, callback_params, rotate)
          end
          if Utils.is_response_ok?(code)
            Utils.debug "File #{fh.path} {size: #{fsize}} successfully uploaded."
-            progress_data.sweep!
+            chunk_notifier.tmpdata.sweep!
+            block_notifier.tmpdata.sweep!
          end
          [code, data]
        end

      end
+
    end
  end
 end
@@ -4,8 +4,8 @@ module Qiniu
  module RS
    module Version
      MAJOR = 3
-      MINOR = 2
-      PATCH = 1
+      MINOR = 4
+      PATCH = 2
      # Returns a version string by joining <tt>MAJOR</tt>, <tt>MINOR</tt>, and <tt>PATCH</tt> with <tt>'.'</tt>
      #
      # Example
@@ -0,0 +1,33 @@
+# -*- encoding: utf-8 -*-
+
+require 'json'
+require 'qiniu/tokens/access_token'
+require 'qiniu/rs/utils'
+
+module Qiniu
+  module RS
+      class DownloadToken < AccessToken
+
+        include Utils
+
+        attr_accessor :pattern, :expires_in
+
+        def initialize(opts = {})
+          @pattern = opts[:pattern] || "*"
+          @expires_in = opts[:expires_in] || 3600
+        end
+
+        def generate_signature
+          params = {"S" => @pattern, "E" => Time.now.to_i + @expires_in}
+          Utils.urlsafe_base64_encode(params.to_json)
+        end
+
+        def generate_token
+          signature = generate_signature
+          encoded_digest = generate_encoded_digest(signature)
+          %Q(#{@access_key}:#{encoded_digest}:#{signature})
+        end
+
+      end
+  end
+end
@@ -8,6 +8,8 @@ module Qiniu
  module RS
      class QboxToken < AccessToken

+        include Utils
+
        attr_accessor :url, :params

        def initialize(opts = {})
@@ -20,16 +22,16 @@ module Qiniu
          signature = uri.path
          query_string = uri.query
          signature += '?' + query_string if !query_string.nil? && !query_string.empty?
-          signature += "\n";
+          signature += "\n"
          if @params.is_a?(Hash)
-            total_param = @params.map { |key, value| %Q(#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s).gsub('+', '%20')}) }
-            signature += total_param.join("&")
+              params_string = Utils.generate_query_string(@params)
+              signature += params_string
          end
          signature
        end

        def generate_token
-          encoded_digest = generate_encoded_digest(signature)
+          encoded_digest = generate_encoded_digest(generate_signature)
          %Q(#{@access_key}:#{encoded_digest})
        end

@@ -10,7 +10,7 @@ module Qiniu

        include Utils

-        attr_accessor :scope, :expires_in, :callback_url, :callback_body_type, :customer, :escape
+        attr_accessor :scope, :expires_in, :callback_url, :callback_body_type, :customer, :escape, :async_options, :return_body

        def initialize(opts = {})
          @scope = opts[:scope]
@@ -19,6 +19,8 @@ module Qiniu
          @callback_body_type = opts[:callback_body_type]
          @customer = opts[:customer]
          @escape = opts[:escape]
+          @async_options = opts[:async_options]
+          @return_body = opts[:return_body]
        end

        def generate_signature
@@ -27,7 +29,9 @@ module Qiniu
          params[:callbackBodyType] = @callback_body_type if !@callback_body_type.nil? && !@callback_body_type.empty?
          params[:customer] = @customer if !@customer.nil? && !@customer.empty?
          params[:escape] = 1 if @escape == 1 || @escape == true
-          urlsafe_base64_encode(params.to_json)
+          params[:asyncOps] = @async_options if !@async_options.nil? && !@async_options.empty?
+          params[:returnBody] = @return_body if !@return_body.nil? && !@return_body.empty?
+          Utils.urlsafe_base64_encode(params.to_json)
        end

        def generate_token
@@ -17,8 +17,8 @@ Gem::Specification.new do |gem|
  gem.version       = Qiniu::RS::Version.to_s

  # specify any dependencies here; for example:
-  gem.add_development_dependency "rake", "~> 0.9"
-  gem.add_development_dependency "rspec", "~> 2.11"
+  gem.add_development_dependency "rake", ">= 0.9"
+  gem.add_development_dependency "rspec", ">= 2.11"
  gem.add_development_dependency "fakeweb", "~> 1.3"
  gem.add_runtime_dependency "json", "~> 1.7"
  gem.add_runtime_dependency "rest-client", "~> 1.6"
@@ -10,8 +10,8 @@ module Qiniu
    describe EU do

      before :all do
-        @customer_id = "awhy.xu@gmail.com"
-        @bucket = "wm_test_bucket"
+        @customer_id = "why404@gmail.com"
+        @bucket = 'RubySdkTest' + (Time.now.to_i+rand(1000)).to_s
        @key = "image_logo_for_test.png"

        result = Qiniu::RS.mkbucket(@bucket)
@@ -35,12 +35,12 @@ module Qiniu
      end

      after :all do
-        @bucket = "wm_test_bucket"
        result = Qiniu::RS.drop(@bucket)
        puts result.inspect
        result.should_not be_false
      end

+=begin
      context ".set_watermark" do
        it "should works" do
          options = {
@@ -59,6 +59,7 @@ module Qiniu
          puts data.inspect
        end
      end
+=end

    end
  end
@@ -11,7 +11,7 @@ module Qiniu

      before :all do

-        @bucket = "test_images_12345"
+        @bucket = 'RubySdkTest' + (Time.now.to_i+rand(1000)).to_s
        @key = "image_logo_for_test.png"

        result = Qiniu::RS.mkbucket(@bucket)
@@ -20,11 +20,22 @@ module Qiniu

        local_file = File.expand_path('../' + @key, __FILE__)

-        upopts = {:scope => @bucket, :expires_in => 3600, :customer => "awhy.xu@gmail.com"}
+        upopts = {
+            :scope => @bucket,
+            :expires_in => 3600,
+            :customer => "why404@gmail.com",
+            :async_options => "imageView/1/w/120/h/120",
+            :return_body => '{"size":$(fsize), "hash":$(etag), "width":$(imageInfo.width), "height":$(imageInfo.height)}'
+        }
        uptoken = Qiniu::RS.generate_upload_token(upopts)
        data = Qiniu::RS.upload_file :uptoken => uptoken, :file => local_file, :bucket => @bucket, :key => @key
        puts data.inspect

+        data["size"].should_not be_zero
+        data["hash"].should_not be_empty
+        data["width"].should_not be_zero
+        data["height"].should_not be_zero
+
        result = Qiniu::RS.get(@bucket, @key)
        result["url"].should_not be_empty
        puts result.inspect
@@ -42,7 +53,6 @@ module Qiniu
      end

      after :all do
-        @bucket = "test_images_12345"
        result = Qiniu::RS.drop(@bucket)
        puts result.inspect
        result.should_not be_false
@@ -1,4 +1,4 @@
-# Utils.-*- encoding: utf-8 -*-
+# -*- encoding: utf-8 -*-

 require 'spec_helper'
 require 'qiniu/rs/auth'
@@ -10,8 +10,8 @@ module Qiniu
    describe IO do

      before :all do
-        @bucket = "io_test_bucket"
-        @key = Digest::SHA1.hexdigest (Time.now.to_i+rand(100)).to_s
+        @bucket = 'RubySdkTest' + (Time.now.to_i+rand(1000)).to_s
+        @key = Digest::SHA1.hexdigest((Time.now.to_i+rand(100)).to_s)

        result = Qiniu::RS.mkbucket(@bucket)
        puts result.inspect
@@ -19,7 +19,6 @@ module Qiniu
      end

      after :all do
-        @bucket = "io_test_bucket"
        result = Qiniu::RS.drop(@bucket)
        puts result.inspect
        result.should_not be_false
@@ -48,7 +47,7 @@ module Qiniu

      context ".upload_with_token" do
        it "should works" do
-          upopts = {:scope => @bucket, :expires_in => 3600, :customer => "awhy.xu@gmail.com"}
+          upopts = {:scope => @bucket, :expires_in => 3600, :customer => "why404@gmail.com"}
          uptoken = Qiniu::RS.generate_upload_token(upopts)
          code, data = Qiniu::RS::IO.upload_with_token(uptoken, __FILE__, @bucket, @key, nil, nil, nil, true)
          code.should == 200
@@ -10,14 +10,13 @@ module Qiniu
    describe Pub do

      before :all do
-        @bucket = "pub_test_bucket"
+        @bucket = 'RubySdkTest' + (Time.now.to_i+rand(1000)).to_s
        result = Qiniu::RS.mkbucket(@bucket)
        puts result.inspect
        result.should_not be_false
      end

      after :all do
-        @bucket = "pub_test_bucket"
        result = Qiniu::RS.drop(@bucket)
        puts result.inspect
        result.should_not be_false
@@ -11,9 +11,10 @@ module Qiniu
    describe RS do

      before :all do
-        @bucket = "rs_test_bucket"
-        @key = Digest::SHA1.hexdigest (Time.now.to_i+rand(100)).to_s
-        @domain = 'rs-test-bucket.dn.qbox.me'
+        @bucket = 'RubySdkTest' + (Time.now.to_i+rand(1000)).to_s
+        @key = Digest::SHA1.hexdigest((Time.now.to_i+rand(100)).to_s)
+        @key2 = @key + rand(100).to_s
+        #@domain = @bucket + '.dn.qbox.me'

        code, data = Qiniu::RS::RS.mkbucket(@bucket)
        puts [code, data].inspect
@@ -21,7 +22,6 @@ module Qiniu
      end

      after :all do
-        @bucket = "rs_test_bucket"
        code, data = Qiniu::RS::RS.drop(@bucket)
        puts [code, data].inspect
        code.should == 200
@@ -90,6 +90,35 @@ module Qiniu
        end
      end

+      context ".batch_copy" do
+        it "should works" do
+          code, data = Qiniu::RS::RS.batch_copy [@bucket, @key, @bucket, @key2]
+          code.should == 200
+          puts data.inspect
+
+          #code2, data2 = Qiniu::RS::RS.stat(@bucket, @key2)
+          #code2.should == 200
+          #puts data2.inspect
+        end
+      end
+
+      context ".batch_move" do
+        it "should works" do
+          code, data = Qiniu::RS::RS.batch_move [@bucket, @key, @bucket, @key2]
+          code.should == 200
+          puts data.inspect
+
+          #code2, data2 = Qiniu::RS::RS.stat(@bucket, @key2)
+          #code2.should == 200
+          #puts data2.inspect
+
+          code3, data3 = Qiniu::RS::RS.batch_move [@bucket, @key2, @bucket, @key]
+          code3.should == 200
+          puts data3.inspect
+        end
+      end
+
+=begin
      context ".publish" do
        it "should works" do
          code, data = Qiniu::RS::RS.publish(@domain, @bucket)
@@ -105,6 +134,35 @@ module Qiniu
          puts data.inspect
        end
      end
+=end
+
+      context ".copy" do
+        it "should works" do
+          code, data = Qiniu::RS::RS.copy(@bucket, @key, @bucket, @key2)
+          code.should == 200
+          puts data.inspect
+
+          #code2, data2 = Qiniu::RS::RS.stat(@bucket, @key2)
+          #code2.should == 200
+          #puts data2.inspect
+        end
+      end
+
+      context ".move" do
+        it "should works" do
+          code, data = Qiniu::RS::RS.move(@bucket, @key, @bucket, @key2)
+          code.should == 200
+          puts data.inspect
+
+          code2, data2 = Qiniu::RS::RS.stat(@bucket, @key2)
+          code2.should == 200
+          puts data2.inspect
+
+          code3, data3 = Qiniu::RS::RS.move(@bucket, @key2, @bucket, @key)
+          code3.should == 200
+          puts data3.inspect
+        end
+      end

      context ".delete" do
        it "should works" do
@@ -1,4 +1,4 @@
-# Utils.-*- encoding: utf-8 -*-
+# -*- encoding: utf-8 -*-

 require 'digest/sha1'
 require 'spec_helper'
@@ -11,8 +11,8 @@ module Qiniu

      before :all do
        @localfile = "bigfile.txt"
-        File.open(@localfile, "w"){|f| 9437184.times{f.write(Random.rand(9).to_s)}}
-        @bucket = "up_test_bucket"
+        File.open(@localfile, "w"){|f| 5242888.times{f.write(rand(9).to_s)}}
+        @bucket = 'RubySdkTest' + (Time.now.to_i+rand(1000)).to_s
        @key = Digest::SHA1.hexdigest(@localfile+Time.now.to_s)

        code, data = Qiniu::RS::RS.mkbucket(@bucket)
@@ -21,10 +21,8 @@ module Qiniu
      end

      after :all do
-        @localfile = "bigfile.txt"
        File.unlink(@localfile) if File.exists?(@localfile)

-        @bucket = "up_test_bucket"
        code, data = Qiniu::RS::RS.drop(@bucket)
        puts [code, data].inspect
        code.should == 200
@@ -32,7 +30,7 @@ module Qiniu

      context ".upload_with_token" do
        it "should works" do
-          upopts = {:scope => @bucket, :expires_in => 3600, :customer => "awhy.xu@gmail.com"}
+          upopts = {:scope => @bucket, :expires_in => 3600, :customer => "why404@gmail.com"}
          uptoken = Qiniu::RS.generate_upload_token(upopts)
          code, data = Qiniu::RS::UP.upload_with_token(uptoken, @localfile, @bucket, @key)
          puts data.inspect
@@ -3,19 +3,21 @@
 require 'digest/sha1'
 require 'spec_helper'
 require 'qiniu/rs'
+require 'qiniu/rs/exceptions'

 module Qiniu
  describe RS do

    before :all do
-      @bucket = 'qiniu_rs_test'
+      @bucket = 'RubySdkTest' + (Time.now.to_i+rand(1000)).to_s
      @key = Digest::SHA1.hexdigest Time.now.to_s
-      @domain = 'qiniu-rs-test.dn.qbox.me'
+      @key2 = @key + rand(100).to_s
+      #@domain = @bucket + '.dn.qbox.me'

      result = Qiniu::RS.mkbucket(@bucket)
      result.should_not be_false

-      @test_image_bucket = 'test_images_12345'
+      @test_image_bucket = 'RubySdkTest' + (Time.now.to_i+rand(1000)).to_s
      result2 = Qiniu::RS.mkbucket(@test_image_bucket)
      puts result2.inspect
      result2.should be_true
@@ -23,16 +25,19 @@ module Qiniu
      @test_image_key = 'image_logo_for_test.png'
      local_file = File.expand_path('./rs/' + @test_image_key, File.dirname(__FILE__))
      puts local_file.inspect
-      upopts = {:scope => @test_image_bucket, :expires_in => 3600, :customer => "awhy.xu@gmail.com"}
+      upopts = {:scope => @test_image_bucket, :expires_in => 3600, :customer => "why404@gmail.com"}
      uptoken = Qiniu::RS.generate_upload_token(upopts)
      data = Qiniu::RS.upload_file :uptoken => uptoken, :file => local_file, :bucket => @test_image_bucket, :key => @test_image_key
      puts data.inspect
    end

    after :all do
-      result = Qiniu::RS.drop(@bucket)
-      puts result.inspect
-      result.should_not be_false
+      #result = Qiniu::RS.unpublish(@domain)
+      #result.should_not be_false
+
+      result1 = Qiniu::RS.drop(@bucket)
+      puts result1.inspect
+      result1.should_not be_false

      result2 = Qiniu::RS.drop(@test_image_bucket)
      puts result2.inspect
@@ -79,6 +84,7 @@ module Qiniu
      end
    end

+=begin
    context ".set_watermark" do
      it "should works" do
        options = {
@@ -97,6 +103,7 @@ module Qiniu
        puts result.inspect
      end
    end
+=end

    context ".put_auth" do
      it "should works" do
@@ -148,16 +155,39 @@ module Qiniu
        result.should_not be_false
        puts result.inspect
      end
+
+      it "should raise MissingArgsError" do
+        uptoken_opts = {:scope => @bucket, :escape => 0}
+        upload_opts = {
+          :uptoken => Qiniu::RS.generate_upload_token(uptoken_opts),
+          :file => __FILE__,
+          :key => @key,
+          :enable_crc32_check => true
+        }
+        lambda { Qiniu::RS.upload_file(upload_opts) }.should raise_error(RS::MissingArgsError)
+      end
+
+      it "should raise NoSuchFileError" do
+        uptoken_opts = {:scope => @bucket, :escape => 0}
+        upload_opts = {
+          :uptoken => Qiniu::RS.generate_upload_token(uptoken_opts),
+          :file => 'no_this_file',
+          :bucket => @bucket,
+          :key => @key,
+          :enable_crc32_check => true
+        }
+        lambda { Qiniu::RS.upload_file(upload_opts) }.should raise_error(RS::NoSuchFileError)
+      end
    end

    context ".resumable_upload_file" do
      it "should works" do
        # generate bigfile for testing
        localfile = "test_bigfile"
-        File.open(localfile, "w"){|f| 5242888.times{f.write(Random.rand(9).to_s)}}
+        File.open(localfile, "w"){|f| 5242888.times{f.write(rand(9).to_s)}}
        key = Digest::SHA1.hexdigest(localfile+Time.now.to_s)
        # generate the upload token
-        uptoken_opts = {:scope => @bucket, :expires_in => 3600, :customer => "awhy.xu@gmail.com", :escape => 0}
+        uptoken_opts = {:scope => @bucket, :expires_in => 3600, :customer => "why404@gmail.com", :escape => 0}
        uptoken = Qiniu::RS.generate_upload_token(uptoken_opts)
        # uploading
        upload_opts = {
@@ -248,19 +278,69 @@ module Qiniu
      end
    end

+=begin
    context ".publish" do
      it "should works" do
        result = Qiniu::RS.publish(@domain, @bucket)
        result.should_not be_false
      end
    end
+=end

+=begin
    context ".unpublish" do
      it "should works" do
        result = Qiniu::RS.unpublish(@domain)
        result.should_not be_false
      end
    end
+=end
+
+    context ".batch_copy" do
+      it "should works" do
+        result = Qiniu::RS.batch_copy [@bucket, @key, @bucket, @key2]
+        result.should_not be_false
+
+        #result2 = Qiniu::RS.stat(@bucket, @key2)
+        #result2.should_not be_false
+      end
+    end
+
+    context ".batch_move" do
+      it "should works" do
+        result = Qiniu::RS::RS.batch_move [@bucket, @key, @bucket, @key2]
+        result.should_not be_false
+
+        #result2 = Qiniu::RS.stat(@bucket, @key2)
+        #result2.should_not be_false
+
+        result3 = Qiniu::RS.batch_move [@bucket, @key2, @bucket, @key]
+        result3.should_not be_false
+      end
+    end
+
+    context ".copy" do
+      it "should works" do
+        result = Qiniu::RS.copy(@bucket, @key, @bucket, @key2)
+        result.should_not be_false
+
+        #result2 = Qiniu::RS.stat(@bucket, @key2)
+        #result2.should_not be_false
+      end
+    end
+
+    context ".move" do
+      it "should works" do
+        result = Qiniu::RS.move(@bucket, @key, @bucket, @key2)
+        result.should_not be_false
+
+        result2 = Qiniu::RS.stat(@bucket, @key2)
+        result2.should_not be_false
+
+        result3 = Qiniu::RS.move(@bucket, @key2, @bucket, @key)
+        result3.should_not be_false
+      end
+    end

    context ".delete" do
      it "should works" do
@@ -307,10 +387,6 @@ module Qiniu
        data.should_not be_empty
        puts data.inspect

-        dest_bucket = "test_thumbnails_bucket"
-        result = Qiniu::RS.mkbucket(dest_bucket)
-        result.should_not be_false
-
        dest_key = "cropped-" + @test_image_key
        src_img_url = data["url"]
        mogrify_options = {
@@ -322,7 +398,7 @@ module Qiniu
          :format => "jpg",
          :auto_orient => true
        }
-        result2 = Qiniu::RS.image_mogrify_save_as(dest_bucket, dest_key, src_img_url, mogrify_options)
+        result2 = Qiniu::RS.image_mogrify_save_as(@test_image_bucket, dest_key, src_img_url, mogrify_options)
        result2.should_not be_false
        result2.should_not be_empty
        puts result2.inspect
@@ -331,9 +407,19 @@ module Qiniu

    context ".generate_upload_token" do
      it "should works" do
-        data = Qiniu::RS.generate_upload_token({:scope => 'test_bucket', :expires_in => 3600, :escape => 0})
+        data = Qiniu::RS.generate_upload_token({:scope => @bucket, :expires_in => 3600, :escape => 0})
        data.should_not be_empty
        puts data.inspect
+        data.split(":").length.should == 3
+      end
+    end
+
+    context ".generate_download_token" do
+      it "should works" do
+        data = Qiniu::RS.generate_download_token({:expires_in => 1, :pattern => 'http://*.dn.qbox.me/*'})
+        data.should_not be_empty
+        puts data.inspect
+        data.split(":").length.should == 3
      end
    end

@@ -0,0 +1,29 @@
+# -*- encoding: utf-8 -*-
+
+require 'spec_helper'
+require 'qiniu/tokens/qbox_token'
+
+module Qiniu
+  module RS
+    describe QboxToken do
+      before :all do
+        @qbox_token = QboxToken.new(:url => 'www.qiniutek.com?key1=value1',
+                                    :params => { :key2 => 'value2' })
+        @qbox_token.access_key = 'access_key'
+        @qbox_token.secret_key = 'secret_key'
+      end
+
+      context "#generate_token" do
+        it "should generate token" do
+          @qbox_token.generate_token.should_not be_empty
+        end
+      end
+
+      context "#generate_signature" do
+        it "should generate signature" do
+          @qbox_token.generate_signature.should == "www.qiniutek.com?key1=value1\nkey2=value2"
+        end
+      end
+    end
+  end
+end
@@ -6,13 +6,6 @@ require 'rspec'

 RSpec.configure do |config|
  config.before :all do
-    Qiniu::RS.establish_connection! :access_key => "dFX_wMGVrRzwdWaraW-Qe5ZCDT-kcSmIAGKQOkXh",
-                                    :secret_key => "VllxxDfkn_h2ZIqeKYTnHJiN4LVODfDBlJHy_KsW",
-                                    :auth_url   => "http://m1.qbox.me:13001/oauth2/token",
-                                    :rs_host    => "http://m1.qbox.me:13003",
-                                    :io_host    => "http://m1.qbox.me:13004",
-                                    :up_host    => "http://m1.qbox.me:13019",
-                                    :pub_host   => "http://m1.qbox.me:13012",
-                                    :eu_host    => "http://m1.qbox.me:13050"
+    Qiniu::RS.establish_connection! :access_key => ENV["QINIU_ACCESS_KEY"], :secret_key => ENV["QINIU_SECRET_KEY"]
  end
 end
Author	SHA1	Message	Date
xushiwei	7b507f15c6	Merge pull request #41 from why404/release/v3.4.2 Release/v3.4.2 - uploadToken[:return_body]	2013-02-05 03:45:03 -08:00
404	aab7277b50	update README.md	2013-02-05 14:59:26 +08:00
404	eaed72eeaa	release v3.4.2 for uploadToken[:return_body] #40 .	2013-02-04 15:38:11 +08:00
404	60cc7274b1	Merge pull request #38 from why404/feature/fix_env_appkey rm encrypted appkey	2013-01-24 18:38:37 -08:00
xushiwei	466a4ba07e	Merge pull request #39 from why404/feature/return_body add :return_body option for Qiniu::RS.generate_upload_token()	2013-01-23 06:23:49 -08:00
404	444956f161	add :return_body option for Qiniu::RS.generate_upload_token()	2013-01-23 21:30:15 +08:00
404	0e4b5d00bc	used before_script instead of env vars in .travis.yml	2013-01-23 16:55:41 +08:00
404	5d2745d148	fix travis env syntax	2013-01-23 16:49:15 +08:00
404	3026a40d99	rm encrypted appkey	2013-01-23 16:38:42 +08:00
xushiwei	84f7cc6205	Merge pull request #36 from why404/feature/encrypt_appkey mv appkey outside and encrypted	2013-01-22 23:58:50 -08:00
404	5562df4b28	mv appkey outside and encrypted	2013-01-23 15:37:13 +08:00
qiniu	70c4664e0d	Merge pull request #35 from qiniu/master v3.4.1 - add :async_options for uploadToken	2013-01-14 17:58:45 -08:00
404	2096bff7a7	Merge pull request #34 from why404/feature/upload_async_options v3.4.1 - add :async_options for uploadToken	2013-01-14 09:20:44 -08:00
404	b0af3c1814	v3.4.1 - add :async_options for uploadToken	2013-01-15 00:10:19 +08:00
404	9bda6845a0	Merge pull request #33 from why404/feature/add_cp_and_mv_support v3.4.0 - added copy and move methods	2013-01-08 09:59:13 -08:00
404	d9422cbcf4	added copy and move methods	2013-01-09 01:56:05 +08:00
404	38c054f24c	Merge pull request #32 from why404/feature/uniq_bucket_for_multi_test_concurrency using unique bucket for multi concurrency testing	2013-01-06 07:48:34 -08:00
404	f85c4fab41	updated CHANGELOG.md for v3.3.1	2013-01-06 23:39:28 +08:00
404	f9bbcfeec6	using unique bucket for multi concurrency testing	2013-01-06 23:29:23 +08:00
xushiwei	e3d4a80b54	Merge pull request #31 from why404/feature/download_token Feature/download token	2013-01-05 23:53:54 -08:00
404	61aae133cf	updated Gemfile.lock	2013-01-06 15:20:50 +08:00
404	c3e2a3d44b	rewrite docs	2013-01-06 14:48:35 +08:00
404	06b019008a	fix encoding comments	2013-01-06 11:07:12 +08:00
404	957b5d1499	docs updated	2012-12-20 17:16:17 +08:00
404	5b0a561cc1	add Qiniu::RS.generate_download_token()	2012-12-19 17:53:26 +08:00
404	d1e60697c3	disabled wm	2012-12-18 10:57:16 +08:00
404	089b6bc7c6	Merge pull request #29 from zhouguangming/bug_fixed refactor UP.upload_with_token	2012-12-09 17:53:22 -08:00
zhouguangming	f1edde2e54	refactor UP.upload_with_token	2012-12-08 22:15:01 +08:00
404	8aca8bf33e	Merge pull request #28 from zhouguangming/bug_fixed MissingArgsError should get a key_list // very nice!	2012-12-07 00:07:43 -08:00
zhouguangming	69bb9cb913	MissingArgsError should get a key_list	2012-12-07 15:25:54 +08:00
404	cacdb4f926	Merge pull request #27 from zhouguangming/bug_fixed 感谢修正！不过由于历史遗留原因 lib/qiniu/tokens/qbox_token.rb 尚保留在sdk代码里边但并未实际使用。请求签名认证程序使用的是 Qiniu::RS::Utils.generate_qbox_signature(url,params) , 所以不影响sdk正常使用。	2012-12-06 05:41:46 -08:00
zhouguangming	557b75f33f	[bug_fixed] lib/qiniu/tokens/qbox_token.rb => method generate_token => undefined method signature	2012-12-06 17:19:14 +08:00
xushiwei	2cbb175423	Merge pull request #26 from why404/release/v3.2.2 fix up 701	2012-12-04 22:32:53 -08:00
404	a8a8f63887	fix up 701	2012-12-05 14:00:12 +08:00
404	64cf9b5d3f	Merge pull request #24 from hayeah/master Fixes Qiniu::RS::Exception Issue	2012-11-29 01:53:46 -08:00
Howard Yeh	1a73c39ffb	Don't override to_s of Exception with inspect. This causes infinite recursion.	2012-11-27 18:52:41 +08:00