oss图片服务api-20140714

《oss图片服务api-20140714》由会员分享，可在线阅读，更多相关《oss图片服务api-20140714（32页珍藏版）》请在金锄头文库上搜索。

1、ALIBABA 阿里云 OSS 图片处理服 务(IMG) API 使用手册 2014/07/14 目录 1 介绍介绍 2 基本概念 . 3 Object 3 Channel （频道） . 3 Style（样式） . 3 分隔符 4 1.1 规则 . 5 1.2 关键词说明 . 6 1.2.1 顺序无关 6 1.2.2覆盖处理 . 6 1.2.3冲突处理 . 6 1.2.4长边与短边 . 6 1.2.5 URL安全的Base64位编码. 7 1.3 用户签名验证（AUTHENTICATION） . 7 1.3.1 在Header里包含签名. 7 1.3.2 在URL里包含签名 8 1.3.3 如

2、何快速开发IMG签名 . 9 2 接口接口 12 2.1 生成指定规格的缩略图 . 12 访问规则 12 使用示例 18 2.2 水印请求 . 20 访问规则 20 使用示例 23 2.3 管道 . 25 访问规则 25 使用示例 25 阿里云 OSS 图片处理服务(IMG) 2 2.4 样式 . 27 访问规则 27 使用示例 27 3. 图片处理服务错误响应图片处理服务错误响应 28 3.1 图片处理服务错误的响应格式 . 29 3.2 图片处理服务的错误码 . 29 阿里云 OSS 图片处理服务(IMG) 2 1 介绍介绍 阿里云 OSS 图片处理服务(Image Service，简称

3、IMG) ，是阿里云 OSS 对外提供 的海量，安全，低成本高可靠的图片处理服务。用户将原始图片上传保存在 OSS 上，通过简单的 RESTful 接口，在任何时间、任何地点、任何互联网设备上对图 片进行处理。基于 IMG，用户可以搭建出跟图片相关的服务。 阿里云 OSS 图片处理服务(IMG) 3 基本概念基本概念 Object 在 IMG 中，用户操作图片的基本数据单元是 Object。即 OSS 对应的 Object， 单 个 Object (即每张图片)允许的最大小是 10MB。 Object 命名规范： (一) 使用 UTF-8 编码。 (二) 长度必须在 1-1023 字节之间。

4、(三) 不能以“/”或者“”字符开头。 Channel （频道） Channel 是 IMG 上的命名空间，也是计费、权限控制、日志记录等高级功能的管 理实体。IMG 名称在整个图片处理服务中具有全局唯一性，且不能修改。一个用 户最多可创建 10 个 Channel，但每个 Channel 中存放的 Object 的数量和大小 总和没有限制，用户不需要考虑数据的容量扩展。 目前 Channel 跟 OSS 的 Bucket 相对应，即用户只能创建与自己在 OSS 上 Bucket 同名的 Channel。 Channel 命名规范： (一) 只能包括小写字母，数字，短横线(-)。 (二) 必须

5、以小写字母或者数字开头和结尾。 (三) 长度必须在 3-63 字节之间。 Style（样式） 图片处理服务提供用户将图片的处理操作和参数保存成一个别名，即样式。 一系 列操作，利用样式功能后，只需要用一个很短的 URL 就能实现相同的效果。 阿里云 OSS 图片处理服务(IMG) 4 ? 一个一个 Channel 下面有多个样式下面有多个样式，目前一个 Channel 允许最多有 20 个样式。 ? 样式适应于样式适应于 Channel 下面的下面的 object 图像变化操作。假如在 ChannelA 下面有 样式，名称为 abc， 样式内容是 100w.jpg（按宽缩略成 100，保存成

6、jpg 格 式） 那么ChannelA下面所有的object都能使用样式abc， 实现缩略成 100w.jpg 的效果。 ? 样式的作用范围只在一个样式的作用范围只在一个 Channel 下下， 即 ChannelA 不能使用 Channel B 的样 式。 Style 命名规范： (一) 只能包括小写字母，数字，短横线(-)。 (二) 必须以小写字母或者数字开头和结尾。 (三) 长度必须在 3-63 字节之间。 注意: 样式的分隔符是: ! 分隔符 图片处理服务使用通过 URL 来访问处理的图片。 所以需要分隔符来区分一些关 键字段。不要在使用的图片文件名称中包含图片处理服务设定的分隔符。不

7、然会 导致解析出错的问题。 分隔符名称 分隔符 含义 处理分隔符 区分 object 名称跟处理字符 串，详见 2.1.1 样式分隔符 ！ 区分 object 跟样式内容，详 见 2.4.1 管道分隔符 | 区分多种操作，详见 2.3.1 阿里云 OSS 图片处理服务(IMG) 5 1.1 规则规则 图片处理服务使用通过 URL 来访问处理的图片， 本文定义访问方式的规范。 形式 为：http:/userdomain/object100w_100h_90Q.jpg。 其中 userdomain 为用户开通图片服务绑定的域名，这个域名会关联到一个 Bucket。object 为用户所关联 Buc

8、ket 上存储的原图片。100w_100h_90Q 为转换 字符串，用来转换处理图片的一段参数。通过指定转换字符串，生成并返回另一 张转换处理后的图片。 一个典型的转换字符串， 如“100w_100h_90Q.jpg”， 代表需要一张宽 （w） 100px、 高（h）100px、绝对质量（Q）90%、jpg 格式的图片，转换字符串的组成如图 1 转换字符串。 图 1 转换字符串 转换字符串分为 3 部分：初始符、转换参数、转换格式： ? 初始符是一个“”符号，从此符号开始，后面都为转换字符串。 ? 转换参数由一个或多个键值对 （以“_“连接） 组成， “值”在前“键”在后， “值” 为数字类型

9、，“键”为一位字母。 ? 转换格式是一种特殊的转换参数，通过指定转换格式，我们对原图处理并 返回用户期望的图片文件格式。 （支持格式是: jpg， jpeg， webp， png， bmp） 。 阿里云 OSS 图片处理服务(IMG) 6 1.2 关键词说明关键词说明 1.2.1 顺序无关 转换参数中键值对是循序无关的，即“120w_120h_90Q“和“90Q_120w_120h“都能 取到想要的图片，系统会对参数按照本规范以下定义的顺序重新排序后再处理。 （由于参数的顺序不同有时会表达不同的语义，如“100w_100h_2x”表达的是“先 缩放到 100*100，再放大 2 倍”，即得到

10、200*200 的图片；而“2x_100w_100h“按 照字面顺序理解是“先放大 2 倍再缩放到 100*100”，即得到 100*100 的图片，为 了避免这样的理解误差，同时简化处理方式，IMG 会对参数按照文档中出现的顺 序排序后处理。上例中的“2x_100w_100h“会被理解为“100w_100h_2x”，得到 200*200 的图片。 ） 1.2.2 覆盖处理 如果转换参数中出现多个相同“键”，后面定义的覆盖前面定义。如 “120w_120h_240w“等同于“120h_240w”。 1.2.3 冲突处理 见每个参数中关于冲突的说明。 1.2.4 长边与短边 关于“长边”和“短边

11、”的定义需要特别注意，它们表达的是在缩放中相对比例的长 或短。 “长边”是指原尺寸与目标尺寸的比值大的那条边； “短边”同理。 如原图 400 * 200，缩放为 800 * 100， （400/800=0.5，200/100=2，0.5 2） ，所以在这个缩放 中 200 那条是长边，400 是短边。 阿里云 OSS 图片处理服务(IMG) 7 1.2.5 URL 安全的 Base64 位编码 在图片处理服务里会有很多参数需要变成 Base64 位编码。编码的格式是： ? 先将内容编码成 Base64 结果； ? 将结果中的加号”+”替换成中划线“-“； ? 将结果中的斜杠”/”替换成下划线

12、”_”; ? 将结果中尾部的“=”号全部去除； 1.3 用户签名验证（用户签名验证（Authentication） 图片处理服务的签名验证与 OSS 签名验证方法使用相同的验证逻辑。其中 CanonicalizedResource 的构成由三部分构成： ? 使用绑定域名对应的图片处理服务频道，这个频道名称与 Bucket 名称相同 ? 原 OSS object 文件名称 ? 转换字符串。 如：用户绑定的域名 对应的频道名字为 image-demo，object 名字 为 example.jpg，转换字符串为：100w.jpg 在图片处理服务中，CanonicalizedResource 为 /

13、image-demo/example.jpg100.jpg 注意：上例中的转换字符串可以是简单缩略，文字水印，图片水印、管道和样式 （样式的分隔符是!） 具体 OSS 签名规则可以参考 OSS API 手册。 1.3.1 在 Header 里包含签名 Authorization 字段计算方法如下：字段计算方法如下： “Authorization: OSS “ + Access Key Id + “:“ + Signature Signature = base64(hmac-sha1(VERB + “n“ + CONTENT-MD5 + “n“ + CONTENT-TYPE + “n“ 阿里云

14、OSS 图片处理服务(IMG) 8 + DATE + “n“ + CanonicalizedOSSHeaders + CanonicalizedResource) ? CONTENT-MD5 表示请求内容数据的 MD5 值， 对于图片处理服务这里为 空字符串 ? CONTENT-TYPE 表示请求内容的类型，对于图片处理服务这里为空字 符串 ? DATE 表示此次操作的时间，且必须为 HTTP1.1 中支持的 GMT 格式 ? CanonicalizedOSSHeaders 表示 http 中的 object meta 组合，对于 图片处理服务这里为空字符串 ? CanonicalizedRe

15、source 表示用户想要访问的 OSS 资源，在图片处 理服务中这项的组成，格式为/channelname/object处理参数 其中， DATE 和 CanonicalizedResource 不能为空； 如果请求中的 DATE 时间和 OSS 服务器的时间差正负 15 分钟以上， OSS 图片处理服务将拒绝该服务， 并返回 HTTP 403 错误。 1.3.2 在 URL 里包含签名 Signature 字段计算方法如下：字段计算方法如下： Signature = base64(hmac-sha1(VERB + “n“ + CONTENT-MD5 + “n“ + CONTENT-TYPE

16、 + “n“ + Expires + “n“ + CanonicalizedOSSHeaders + CanonicalizedResource) ? CONTENT-MD5 表示请求内容数据的 MD5 值， 对于图片处理服务这里为 空字符串 ? CONTENT-TYPE 表示请求内容的类型，对于图片处理服务这里为空字 符串 ? Expires 授权给用户 URL 签名过期时间 ? CanonicalizedOSSHeaders 表示 http 中的 object meta 组合，对于 阿里云 OSS 图片处理服务(IMG) 9 图片处理服务这里为空字符串 ? CanonicalizedResource 表示用户想要访问的 OSS 资源，在图片处 理服务中这项的组成，格式为/channelname/object处理参数 其中，Expires 和 CanonicalizedResource 不能为空； 在 URL 里包含签名的示例链接如下： 在 URL 签名，必须在参数后包含，OSSAccessKeyId，