From c3e2a3d44bd083d5093f165c23e8b03fdcfb2540 Mon Sep 17 00:00:00 2001 From: 404 Date: Sun, 6 Jan 2013 14:48:35 +0800 Subject: [PATCH] rewrite docs --- docs/README.md | 531 ++++++++++++------------------------------------- 1 file changed, 131 insertions(+), 400 deletions(-) diff --git a/docs/README.md b/docs/README.md index ff3b042..8862c2b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,54 +8,51 @@ title: Ruby SDK 使用指南 | 七牛云存储 七牛云存储 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) + ## 安装 - - 在您 Ruby 应用程序的 `Gemfile` 文件中，添加如下一行代码： gem 'qiniu-rs' @@ -69,11 +66,13 @@ title: Ruby SDK 使用指南 | 七牛云存储 $ gem install qiniu-rs -## 使用 + + +## 接入 -### 应用接入 +### 配置密钥（AccessKey / SecretKey） 要接入七牛云存储，您需要拥有一对有效的 Access Key 和 Secret Key 用来进行签名认证。可以通过如下步骤获得： @@ -87,7 +86,7 @@ title: Ruby SDK 使用指南 | 七牛云存储 -### Ruby On Rails 应用初始化设置 +### 针对 Ruby On Rails 网站应用初始化设置 如果您使用的是 [Ruby on Rails](http://rubyonrails.org/) 框架，我们建议您在应用初始化启动的过程中，依次调用上述两个函数即可，操作如下： @@ -102,13 +101,20 @@ title: Ruby SDK 使用指南 | 七牛云存储 接下来，我们会逐一介绍此 SDK 提供的其他方法。 + + + +## 使用 + -### 上传文件 +### 文件上传 + +**注意**：如果您只是想要上传已存在您电脑本地或者是服务器上的文件到七牛云存储，可以直接使用七牛提供的 [qrsync](/v3/tools/qrsync/) 上传工具。如果是需要通过您的网站或是移动应用(App)上传文件，则可以接入使用此 SDK，详情参考如下文档说明。 -#### 获取用于上传文件的临时授权凭证 +#### 生成上传授权凭证（uploadToken） 要上传一个文件，首先需要调用 SDK 提供的 `Qiniu::RS.generate_upload_token` 函数来获取一个经过授权用于临时匿名上传的 `upload_token`——经过数字签名的一组数据信息，该 `upload_token` 作为文件上传流中 `multipart/form-data` 的一部分进行传输。 @@ -157,7 +163,7 @@ title: Ruby SDK 使用指南 | 七牛云存储 -#### 服务端上传文件 +#### Ruby 服务端上传文件 通过 `Qiniu::RS.upload_file()` 方法可在客户方的业务服务器上直接往七牛云存储上传文件。该函数规格如下： @@ -210,7 +216,7 @@ title: Ruby SDK 使用指南 | 七牛云存储 -##### 断点续上传 +##### 开启断点续上传 无需任何额外改动，SDK 提供的 `Qiniu::RS.upload_file()` 方法缺省支持断点续上传。默认情况下，SDK 会自动启用断点续上传的方式来上传超过 4MB 大小的文件。您也可以在 [应用接入](/v3/sdk/ruby/#establish_connection!) 时通过修改缺省配置来设置该阀值： @@ -246,55 +252,63 @@ title: Ruby SDK 使用指南 | 七牛云存储 : 整型，指定每次 http 若请求失败最多可以重试的次数，缺省为3次。该参数 SDK 全局有效。 - - -##### 自定义 404 NotFound 资源 - -您可以上传一个应对 HTTP 404 出错处理的文件，当您 [创建公开外链](#publish) 后，若公开的外链找不到该文件，即可使用您上传的“自定义404文件”代替之。要这么做，您只须使用 `Qiniu::RS.upload_file` 函数上传一个 `key` 为固定字符串类型的值 `errno-404` 即可。 - -除了使用 SDK 提供的方法，同样也可以借助七牛云存储提供的命令行辅助工具 [qboxrsctl](https://github.com/qiniu/devtools/tags) 达到同样的目的： - - qboxrsctl put - -将其中的 `` 换作 `errno-404` 即可。 - -注意，每个 `` 里边有且只有一个 `errno-404` 文件，上传多个，最后的那一个会覆盖前面所有的。 - -#### 移动端/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` 格式的数据，七牛云存储服务端会将该回调请求所得的响应信息原封不动地返回给终端应用程序。 -### 下载文件 -私有(private)是 bucket(空间) 的一个属性，一个私有 bucket 中的资源为私有资源，私有资源不可匿名下载。 +### 文件下载 -新创建的bucket缺省为私有，也可以将某个bucket设为公有，公有bucket中的资源为公有资源，公有资源可以匿名下载。 +七牛云存储上的资源下载分为 [公有资源下载](#download-public-files) 和 [私有资源下载](#download-private-files) 。 + +私有（private）是 Bucket（空间）的一个属性，一个私有 Bucket 中的资源为私有资源，私有资源不可匿名下载。 + +新创建的空间（Bucket）缺省为私有，也可以将某个 Bucket 设为公有，公有 Bucket 中的资源为公有资源，公有资源可以匿名下载。 + #### 公有资源下载 - http://.qiniudn.com/ + [GET] http://.qiniudn.com/ + +或者， + + [GET] http://<绑定域名>/ + +绑定域名可以是自定义域名，可以在 [七牛云存储开发者自助网站](https://dev.qiniutek.com/buckets) 进行域名绑定操作。 注意，尖括号不是必需，代表替换项。 + #### 私有资源下载 私有资源只能通过临时下载授权凭证(downloadToken)下载，下载链接格式如下： - http://.qiniudn.com/?token= + [GET] http://.qiniudn.com/?token= -downloadToken 可以使用 SDK 提供的如下方法生成： +或者， + + [GET] http://<绑定域名>/?token= + + + +##### 生成下载授权凭证（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) + + + +#### 高级特性 + + + +##### 断点续下载 + +七牛云存储支持标准的断点续下载，参考：[云存储API之断点续下载](/v3/api/io/#download-by-range-bytes) + + + +##### 自定义 404 NotFound + +您可以上传一个应对 HTTP 404 出错处理的文件，当用户访问一个不存在的文件时，即可使用您上传的“自定义404文件”代替之。要这么做，您只须使用 `Qiniu::RS.upload_file` 函数上传一个 `key` 为固定字符串类型的值 `errno-404` 即可。 + +除了使用 SDK 提供的方法，同样也可以借助七牛云存储提供的命令行辅助工具 [qboxrsctl](/v3/tools/qboxrsctl/) 达到同样的目的： + + qboxrsctl put + +将其中的 `` 换作 `errno-404` 即可。 + +注意，每个 `` 里边有且只有一个 `errno-404` 文件，上传多个，最后的那一个会覆盖前面所有的。 + + + + +### 文件管理 + +文件管理包括对存储在七牛云存储上的文件进行查看、复制、移动和删除处理。 + -### 查看文件属性信息 +#### 查看单个文件属性信息 Qiniu::RS.stat(bucket, key) @@ -348,7 +394,7 @@ putTime -### 删除指定文件 +### 删除单个文件 Qiniu::RS.delete(bucket, key) @@ -366,22 +412,6 @@ key 如果删除成功，返回 `true`，否则返回 `false` 。 - - -### 删除所有文件（单个 bucket） - - Qiniu::RS.drop(bucket) - -`Qiniu::RS.drop` 提供了删除整个 `bucket` 及其里边的所有 `key`，以及这些 `key` 关联的所有文件都将被删除。 - -**参数** - -bucket -: 必须，字符串类型（String），类似传统数据库里边的表名称，我们暂且将其叫做“资源表”，每份数据是属性信息都存储到具体的 bucket（资源表）中 。 - -**返回值** - -如果删除成功，返回 `true`，否则返回 `false` 。 @@ -420,7 +450,7 @@ keys ... ] - + #### 批量获取文件属性信息 @@ -454,7 +484,7 @@ keys ... ] - + #### 批量删除文件 @@ -468,71 +498,18 @@ keys 如果批量删除成功，返回 `true` ，否则为 `false` 。 - -### Bucket（空间）管理 + - +### 云处理 -#### 创建 Bucket + - Qiniu::RS.mkbucket(bucket_name) +#### 图像 -可以通过 SDK 提供的 `Qiniu::RS.mkbucket` 函数创建一个 bucket（资源表）。 + -**参数** - -bucket_name -: 必须，字符串类型（String），资源表 bucket 的名称。 - -**返回值** - -如果指定 bucket 创建成功，返回 `true`，否则返回 `false` 。 - - - -#### 列出所有 Bucket - - Qiniu::RS.buckets - -可以通过 SDK 提供的 `Qiniu::RS.buckets` 函数列出当前登录客户的所有 buckets（资源表）。 - -**返回值** - -如果请求成功，返回一个 buckets 的列表（Array），否则返回 `false` 。 - - ["Bucket1", "Bucket2", …, "BucketN"] - - - -#### 访问控制 - - 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` 。 - - - - -### 图像处理 - - - -#### 查看图片属性信息 +##### 查看图片属性信息 Qiniu::RS.image_info(url) @@ -566,9 +543,9 @@ height colorModel : 原始图片着色模式 - + -#### 查看图片EXIF信息 +##### 查看图片EXIF信息 Qiniu::RS.image_exif(url) @@ -583,31 +560,9 @@ url 如果参数 `url` 所代表的图片没有 EXIF 信息，返回 `false`。否则，返回一个包含 EXIF 信息的 Hash 结构。 + - - -#### 获取指定规格的缩略图预览地址 - - 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 - - - - -#### 高级图像处理（缩略、裁剪、旋转、转化） +##### 图像在线处理（缩略、裁剪、旋转、转化） `Qiniu::RS.image_mogrify_preview_url()` 方法支持将一个存储在七牛云存储的图片进行缩略、裁剪、旋转和格式转化处理，该方法返回一个可以直接预览缩略图的URL。 @@ -639,10 +594,9 @@ mogrify_options 返回一个可以预览最终缩略图的URL，String 类型。 + - - -#### 高级图像处理（缩略、裁剪、旋转、转化）并持久化存储处理结果 +#### 图像在线处理（缩略、裁剪、旋转、转化）后并持久化存储 `Qiniu::RS.image_mogrify_save_as()` 方法支持将一个存储在七牛云存储的图片进行缩略、裁剪、旋转和格式转化处理，并且将处理后的缩略图作为一个新文件持久化存储到七牛云存储服务器上，这样就可以供后续直接使用而不用每次都传入参数进行图像处理。 @@ -713,229 +667,6 @@ mogrify_options end - - -## 高级图像处理（水印） - - - -### 水印准备工作 - -为了保护用户原图和方便用户访问打过水印之后的图片，在经水印作用之前，需进行以下一些设置： - -1. [设置原图保护](#watermarking-set-protected) -2. [设置水印预览图URL分隔符](#watermarking-set-sep) -3. [设置水印预览图规格别名](#watermarking-set-style) - - - -#### 1. 设置原图保护 - -用户的图片打上水印后，其原图不可见。通过给原图所在的 Bucket（资源表）设置访问控制，可以达到保护原图的目的，详情请参考 [Bucket（资源表）管理之访问控制](set-protected)。 - -设置原图保护也可以借助七牛云存储提供的命令行辅助工具 [qboxrsctl](https://github.com/qiniu/devtools/tags) 来实现： - - // 为下面的所有图片设置原图保护 - qboxrsctl protected - - - -#### 2. 设置水印预览图URL分隔符 - -没有设置水印前，用户可以通过如下公开链接的形式访问原图（[创建公开外链后的情况下](/v3/api/io/#rs-Publish)）： - - http:/// - -设置水印后，其原图属性为私有，不能再通过这种形式访问。但是用户可以在原图的 `` 后面加上“分隔符”，以及相应的水印风格样式来访问打水印后的图片。例如，假设您为用户设定的访问水印图的分隔符为中划线 “-”，那么用户可以通过这种形式来访问打水印后的图片： - - http:///-/imageView//w//h//q//format//sharpen//watermark/ - -其中，`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 - - - -#### 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) 达到同样的目的： - - // 为 下面的所有图片设置名为 的