图片服务都是使用标准的 HTTP 的 GET 请求来访问的,所有的处理参数也在 URL 的 QueryString 中。

通过处理参数来请求缩略图

如果用户对原图进行一定的处理再返回,可有两种形式:

  • 通过URL的形式

    通过三级域名访问: http://bucket.<endpoint>/object?x-oss-process=image/action,parame_value

    • Bucket:用户的 IMG 频道。
    • endpoint:用户的 Bucket 所在数据中心的访问域名。
    • Object:在 IMG 中,用户操作图片的基本数据单元是 Object。即 OSS 对应的 Object,单个Object(即每张图片)允许的最大大小是 20MB。
    • action:用户对图片做的操作。
    • parame:用户对图片做的操作所对应的参数。
  • 多个 action 之间组合形式

    多个 action 之间效果顺序执行,格式为image/action1,param_value1/action2,param_value2,例如:image/resize,w_200/rotate,90表示图片先进行宽为 200 的缩放,再进行 90 度的旋转。

示例

假如请求 Bucket 是 image-demo,该 Bucket 区域在 华东1,对应的域名是 oss-cn-hangzhou.aliyuncs.com,请求图片是 example.jpg,对图片进行按目标宽度 200 进行缩略。

http://image-demo.oss-cn-hangzhou.aliyuncs.com/example.jpg?x-oss-process=image/resize,w_200

如果是https方式,访问形式如下:

https://image-demo.oss-cn-hangzhou.aliyuncs.com/example.jpg?x-oss-process=image/resize,w_200

通过用户自定义域名访问链接如下:

http://userdomain/object?x-oss-process=image/action,parame_value

通过样式来请求缩略图

  • Style(样式)

    图片处理可将用户的图片处理操作和参数保存成一个别名,即样式。利用样式功能后,原本一系列操作,现在只需要用一个很短的URL就能实现相同的效果。

    • 一个 Channel 下面有多个样式,目前一个 Channel 允许最多有 50 个样式。
    • 样式适应于 Channel 下面的 Object 图像变化操作。假如在 A Channel 下面有样式,名称为 abc,样式内容是 100w.jpg(按宽缩略成 100,保存成 jpg 格式)那么 A Channel 下面所有的 Object 都能使用样式 abc,实现缩略成 100w.jpg 的效果。
    • 样式的作用范围只在一个 Channel 下,即 A Channel 不能使用 B Channel 的样式。

    Style 命名规范:

    • 长度为 1-63 个字符。
    • 只能包含数字、大小写字母、下划线(_)、短横线(-)以及小数点(.)。
  • Channel (频道)

    Channel 是 IMG 上的命名空间,也是计费、权限控制、日志记录等高级功能的管理实体。IMG 名称在整个图片处理服务中具有全局唯一性,且不能修改。一个用户最多可创建10个 Channel,但每个 Channel 中存放的 Object 的数量没有限制。

    图片服务的数据中心和 OSS 的数据中心相对应。用户在 OSS 的某个数据中心上创建一个 Bucket,再选择开通图片服务,对应的 Channel 也属于该数据中心。目前 Channel 跟 OSS 的 Bucket 相对应,即用户只能创建与自己在 OSS 上 Bucket 同名的 Channel。

    Channel 命名规范:

    • 只能包括小写字母,数字,短横线(-)。
    • 必须以小写字母或者数字开头和结尾。
    • 长度必须在 3-63 字节之间。

    为简化使用,用户可以将特定的处理方法保存为样式,这样以后调用同样的处理方法只需指定某个样式即可。使用样式来进行图片处理的 URL 形式如下:

    http://userdomain/object?x-oss-process=style/name
  • 示例

    可以将上述处理参数保存成样式 style-example。假如请求 Bucket 为 image-demo,该 Bucket 区域在 华东1,对应的域名是 oss-cn-hangzhou.aliyuncs.com,请求图片是 example.jpg,访问图片的样式是 style-example,那么访问形式如下:

    ]
    http://image-demo.oss-cn-hangzhou.aliyuncs.com/example.jpg?x-oss-process=style/style-example

    如果是 https 方式,访问形式如下:

    https://image-demo.oss-cn-hangzhou.aliyuncs.com/example.jpg?x-oss-process=style/style-example

使用 SDK 方式

除了 public bucket 可以直接通过url方式进访问,对于 private 的文件,我们一般采用 SDK 的方式来访问。因为图片处理服务都是 GET 操作,所以在 Get Object 基础上面添加 process 参数即可。

以 Python SDK为例:

bucket = oss2.Bucket(oss2.Auth(access_key_id, access_key_secret), endpoint, bucket_name)
key = 'example.jpg'
new_pic = 'new-example.jpg'
process = "image/resize,m_fixed,w_100,h_100" //对于图片进行强制缩略
bucket.get_object_to_file(key, new_pic, process=process)

OSS SDK 使用图片服务,请参看 SDK 文档中的图片服务部分。部分 SDK 图片处理的链接见下表:

SDK 图片处理文档 使用示例
Java SDK 图片处理 ImageSample.java
Python SDK 图片处理 image.py
C# SDK 图片处理 ImageProcessSample.cs
PHP SDK 图片处理 Image.php
JS SDK 图片处理 object.test.js
C SDK 图片处理 oss_image_sample.c

图片处理限制

  • 图片处理支持的格式有:jpg、png、bmp、gif、webp、tiff。
  • 指定缩略图宽度或者高度时,在等比缩放的情况下,都会默认进行单边的缩放。在固定宽高的模式下,会默认在宽高一样的情况下进行缩放。
  • 对缩略后的图片大小有限制,目标缩略图的宽与高的乘积不能超过 4096x4096, 且单边的长度不能超过 4096x4。
  • 调用 resize,默认不允许放大。如果请求图片比原图大,那么返回的仍然是原图。如果想得到放大的图片,需要增加参数调用 limit_0
  • gif,webp 动图由于资源消耗原因目前只支持一级处理。如不能在缩略操作后直接进行图片裁剪。