home/ruby-sdk
2
0
Fork 0
mirror of https://github.com/wahyd4/ruby-sdk.git synced 2026-08-09 04:46:10 +10:00
Code Issues Packages Projects Releases Wiki Activity

rewrite docs

Browse Source
This commit is contained in:
404
2013-01-06 14:48:35 +08:00
parent 06b019008a
commit c3e2a3d44b
1 changed files with 131 additions and 400 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README.md
+131 -400
View File
@@ -8,54 +8,51 @@ title: Ruby SDK 使用指南 | 七牛云存储
七牛云存储 Ruby SDK 源码地址：<https://github.com/qiniu/ruby-sdk>
**文档大纲**
**目录**
- [安装](#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)
- [自定义 404 NotFound 资源](#upload-file-for-not-found)
- [移动端/web端直传文件](#upload-client-side)
- [下载文件](#download)
- [文件上传](#upload)
- [生成上传授权凭证（uploadToken）](#generate-upload-token)
- [Ruby 服务端上传文件](#upload-server-side)
- [开启断点续上传](#resumable-upload)
- [iOS / Android / Web 端直传文件说明](#upload-client-side)
- [文件下载](#download)
- [公有资源下载](#download-public-files)
- [私有资源下载](#download-private-files)
- [查看文件属性信息](#stat)
- [删除指定文件](#delete)
- [删除所有文件（单个 bucket）](#drop)
- [批量操作](#batch)
- [批量获取文件属性信息](#batch_get)
- [批量删除文件](#batch_delete)
- [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)
- [生成下载授权凭证（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'
@@ -69,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 用来进行签名认证。可以通过如下步骤获得：
@@ -87,7 +86,7 @@ title: Ruby SDK 使用指南 | 七牛云存储
<a name="ror-init"></a>
### Ruby On Rails 应用初始化设置
### 针对 Ruby On Rails 网站应用初始化设置
如果您使用的是 [Ruby on Rails](http://rubyonrails.org/) 框架，我们建议您在应用初始化启动的过程中，依次调用上述两个函数即可，操作如下：
@@ -102,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` 的一部分进行传输。
@@ -157,7 +163,7 @@ title: Ruby SDK 使用指南 | 七牛云存储
<a name="upload-server-side"></a>
#### 服务端上传文件
#### Ruby 服务端上传文件
通过 `Qiniu::RS.upload_file()` 方法可在客户方的业务服务器上直接往七牛云存储上传文件。该函数规格如下：
@@ -210,7 +216,7 @@ title: Ruby SDK 使用指南 | 七牛云存储
<a name="resumable-upload"></a>
##### 断点续上传
##### 开启断点续上传
无需任何额外改动，SDK 提供的 `Qiniu::RS.upload_file()` 方法缺省支持断点续上传。默认情况下，SDK 会自动启用断点续上传的方式来上传超过 4MB 大小的文件。您也可以在 [应用接入](/v3/sdk/ruby/#establish_connection!) 时通过修改缺省配置来设置该阀值：
@@ -246,55 +252,63 @@ title: Ruby SDK 使用指南 | 七牛云存储
: 整型，指定每次 http 若请求失败最多可以重试的次数，缺省为3次。该参数 SDK 全局有效。
<a name="upload-file-for-not-found"></a>
##### 自定义 404 NotFound 资源
您可以上传一个应对 HTTP 404 出错处理的文件，当您 [创建公开外链](#publish) 后，若公开的外链找不到该文件，即可使用您上传的“自定义404文件”代替之。要这么做，您只须使用 `Qiniu::RS.upload_file` 函数上传一个 `key` 为固定字符串类型的值 `errno-404` 即可。
除了使用 SDK 提供的方法，同样也可以借助七牛云存储提供的命令行辅助工具 [qboxrsctl](https://github.com/qiniu/devtools/tags) 达到同样的目的：
qboxrsctl put <Bucket> <Key> <LocalFile>
将其中的 `<Key>` 换作 `errno-404` 即可。
注意，每个 `<Bucket>` 里边有且只有一个 `errno-404` 文件，上传多个，最后的那一个会覆盖前面所有的。
<a name="upload-client-side"></a>
#### 移动端/web端直传文件
#### iOS / Android / Web 端直传文件说明
客户端上传流程和服务端上传类似，差别在于：客户端直传文件所需的 `upload_token` 可以选择在客户方的业务服务器端生成，也可以选择在客户方的客户端程序里边生成。选择前者，可以和客户方的业务揉合得更紧密和安全些，比如防伪造请求。
客户端 iOS / Android / Web 上传流程和服务端上传类似，差别在于：客户端直传文件所需的 `uploadToken` 选择在客户方的业务服务器端生成，然后将其生成的 `uploadToken` 颁发给客户端。
简单来讲，客户端上传流程也分为两步：
简单来讲，客户端上传流程分为两步：
1. 获取 `upload_token`（[用于上传文件的临时授权凭证](#generate-upload-token)）
2. 将该 `upload_token` 作为文件上传流 `multipart/form-data` 中的一部分实现上传操作
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 响应信息原封不动地返回给客户端应用程序。
如果您的网络程序是从云端（服务端程序）到终端（手持设备应用）的架构模型，且终端用户有使用您移动端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="download"></a>
### 下载文件
私有(private)是 bucket(空间) 的一个属性，一个私有 bucket 中的资源为私有资源，私有资源不可匿名下载。
### 文件下载
新创建的bucket缺省为私有，也可以将某个bucket设为公有，公有bucket中的资源为公有资源，公有资源可以匿名下载。
七牛云存储上的资源下载分为 [公有资源下载](#download-public-files) 和 [私有资源下载](#download-private-files) 。
私有（private）是 Bucket（空间）的一个属性，一个私有 Bucket 中的资源为私有资源，私有资源不可匿名下载。
新创建的空间（Bucket）缺省为私有，也可以将某个 Bucket 设为公有，公有 Bucket 中的资源为公有资源，公有资源可以匿名下载。
<a name="download-public-files"></a>
#### 公有资源下载
http://<bucket>.qiniudn.com/<key>
[GET] http://<bucket>.qiniudn.com/<key>
或者，
[GET] http://<绑定域名>/<key>
绑定域名可以是自定义域名，可以在 [七牛云存储开发者自助网站](https://dev.qiniutek.com/buckets) 进行域名绑定操作。
注意，尖括号不是必需，代表替换项。
<a name="download-private-files"></a>
#### 私有资源下载
私有资源只能通过临时下载授权凭证(downloadToken)下载，下载链接格式如下：
http://<bucket>.qiniudn.com/<key>?token=<downloadToken>
[GET] http://<bucket>.qiniudn.com/<key>?token=<downloadToken>
downloadToken 可以使用 SDK 提供的如下方法生成：
或者，
[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
@@ -307,9 +321,41 @@ expires_in
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>
##### 自定义 404 NotFound
您可以上传一个应对 HTTP 404 出错处理的文件，当用户访问一个不存在的文件时，即可使用您上传的“自定义404文件”代替之。要这么做，您只须使用 `Qiniu::RS.upload_file` 函数上传一个 `key` 为固定字符串类型的值 `errno-404` 即可。
除了使用 SDK 提供的方法，同样也可以借助七牛云存储提供的命令行辅助工具 [qboxrsctl](/v3/tools/qboxrsctl/) 达到同样的目的：
qboxrsctl put <Bucket> <Key> <LocalFile>
将其中的 `<Key>` 换作 `errno-404` 即可。
注意，每个 `<Bucket>` 里边有且只有一个 `errno-404` 文件，上传多个，最后的那一个会覆盖前面所有的。
<a name="file-management"></a>
### 文件管理
文件管理包括对存储在七牛云存储上的文件进行查看、复制、移动和删除处理。
<a name="stat"></a>
### 查看文件属性信息
#### 查看单个文件属性信息
Qiniu::RS.stat(bucket, key)
@@ -348,7 +394,7 @@ putTime
<a name="delete"></a>
### 删除指定文件
### 删除单个文件
Qiniu::RS.delete(bucket, key)
@@ -366,22 +412,6 @@ key
如果删除成功，返回 `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>
@@ -420,7 +450,7 @@ keys
...
]
<a name="batch_get"></a>
<a name="batch-get"></a>
#### 批量获取文件属性信息
@@ -454,7 +484,7 @@ keys
...
]
<a name="batch_delete"></a>
<a name="batch-delete"></a>
#### 批量删除文件
@@ -468,71 +498,18 @@ keys
如果批量删除成功，返回 `true` ，否则为 `false` 。
<a name="buckets"></a>
### Bucket（空间）管理
<a name="cloud-processing"></a>
<a name="mkbucket"></a>
### 云处理
#### 创建 Bucket
<a name="image-processing"></a>
Qiniu::RS.mkbucket(bucket_name)
#### 图像
可以通过 SDK 提供的 `Qiniu::RS.mkbucket` 函数创建一个 bucket（资源表）。
<a name="image-info"></a>
**参数**
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)
@@ -566,9 +543,9 @@ height
colorModel
: 原始图片着色模式
<a name="image_exif"></a>
<a name="image-exif"></a>
#### 查看图片EXIF信息
##### 查看图片EXIF信息
Qiniu::RS.image_exif(url)
@@ -583,31 +560,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。
@@ -639,10 +594,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()` 方法支持将一个存储在七牛云存储的图片进行缩略、裁剪、旋转和格式转化处理，并且将处理后的缩略图作为一个新文件持久化存储到七牛云存储服务器上，这样就可以供后续直接使用而不用每次都传入参数进行图像处理。
@@ -713,229 +667,6 @@ mogrify_options
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>
## 贡献代码