对象存储BOS

    图片处理V2.0

    更新时间：2020-07-31

    概述

    图片处理服务依托对象存储BOS系统对外提供灵活、多样、实时的图片处理服务。用户将原始图片上传到BOS上，通过调用简单的RESTful接口，实现对图片的实时处理，如缩略、裁剪、格式转换、旋转、加文字/图片水印等，处理结果图会通过CDN实时的返回给用户。

    在访问速度上，图片处理服务集成了CDN功能，利用遍布在全国的高质量CDN节点，实现图片内容的加速分发，有效降低源站压力。

    图片处理服务的架构如下图所示：

    • 用户首次发送请求处理流程：

      1. 用户端首次发送图片处理请求;
      2. 首次请求，CDN未命中，请求会被直接发送到BOS源站进行处理；
      3. 根据用户发送的处理参数对图片进行实时处理；
      4. 处理后的结果图将被缓存到CDN节点上；
      5. 同时，将结果图返回给用户端。

    • 用户端非首次访问图片处理流程：

      1. 用户端发送图片处理请求;
      2. 若CDN命中，则直接跳到步骤5；若CDN未命中，则跳到步骤3；
      3. 请求会被回源到BOS，并根据用户发送的处理参数对图片进行实时处理；
      4. 处理后的结果图被缓存到CDN节点上；
      5. 将结果图返回给用户端。

    图片处理服务的灵活便捷体现在，您只要通过在原始图片的请求中直接添加处理参数，即可实时得到处理后的结果图。

    计费方式

    图片服务收费分为三个部分：

    • CDN流量 在CDN上会产生请求流量，这些流量将会记录到CDN计费中，请参考CDN产品定价。
    • BOS存储空间、请求次数、外网流出流量和CDN回源请求产生的流出流量 存储空间、请求次数、外网流出流量和CDN回源请求产生的流出流量按BOS标准计费。其中，CDN回源请求的图片流出流量，为处理后目标图的流出流量。请参考BOS产品定价。
    • 图片处理数据量 BOS 图像处理包括图像基础处理费用和图像高级处理费用。图像基础处理费用是指对存储在 BOS 中的图像进行缩放、旋转、水印、格式变换、裁剪等操作时产生的费用，图像高级处理费用是指对存储在 BOS 中的图像进行 HEIC 压缩，WebP-M6 压缩等高阶操作。图像基础处理、图像高级处理中 HEIC 图像压缩及 WebP-M6 图像压缩服务于 2020 年 6 月 1 日开始正式计费。您可以登录控制台-财务查看用量数据。

    使用方式

    说明： 本文档介绍的是BOS图片处理V2.0版本，您仍然可以通过BOS图片处理V1.0版本方式来访问BOS图片处理服务，但今后V1.0版本功能将不再更新。

    您需要先将原始图片上传到BOS，每个BOS Bucket默认开通图片处理的功能，无需开通，也无需使用特定域名访问。当访问图片URL时，在Querystring中通过x-bce-process参数指定图片处理命令，即可触发BOS图片处理功能。BOS支持通过命令和样式两种方式访问图片服务。

    • 命令方式访问格式：http://${domain}/${objectkey}?x-bce-process=image/${action},${key}_${value}. 样例：http://bucket-A.bj.bcebos.com/sample.jpg?x-bce-process=image/resize,m_fill,w_200,h_300。

    • 样式方式访问格式：http://${domain}/${objectkey}?x-bce-process=style/${stylename}. 样例：http://bucket-A.bj.bcebos.com/sample.jpg?x-bce-process=style/stylename。

      为了提升图片的安全性，尤其是在BOS中进行了处理并公开发布的图片，BOS也支持对指定Bucket内的图片开启原图保护。即开启原图保护后，如果图片获取者未验证被授权的签名，则只能通过样式方式访问处理后的图片，直接访问原图或通过处理参数访问的方式会被拒绝。目前支持在控制台对原图保护功能进行开启或关闭，也支持通过API进行相关操作，并可通过resource字段指定该功能生效范围。

    规则与限制

    • 支持的原图格式：jpg、png、bmp、webp、heic、gif。
    • 支持的目标格式：jpg、png、bmp、webp、heic、gif。
    • 支持图片大小不超过20MB，且图片宽高不超过10000px。
    • 处理结果输出图片宽高不超过4096px，包括管道和子命令间的中间输出图片。
    • 最多可以同时指定4组操作，即4个action。
    • 一个action下不可以重复指定同一个参数。

    图片处理命令

    整体的图片处理命令形式为：x-bce-process=image/${action},${key}_${value},${key}_${value}/${action},${key}_${value}，说明如下：

    • image：BOS支持多种数据处理形式，均使用x-bce-process参数触发，当使用图片处理时，需要指定此处名字为image。
    • action：BOS支持多种图片处理命令，每种图片处理命令称作一种action，比如缩放resize，裁剪crop等。
    • key：每种action支持多种具体的处理参数，比如缩放宽度w,高度h等。
    • value：处理参数取值。
    • 分隔符说明如下：
    分隔符名称 分隔符 两侧顺序 说明
    处理分隔符 / 有关 多个action之间的分隔符，前后action顺序执行
    参数分隔符 , 无关 多处理参数项之间的分隔符
    值分隔符 _ 固定顺序 参数名与参数值之间的分隔符

    下文详细介绍各个action的使用。

    缩放

    对图片大小进行缩放处理。

    action名称：resize

    参数 取值 说明
    m lift，mfit，fill，pad，fixed 设置缩略类型。非必选，默认lfit。
    w 1-4096 设置缩略图的宽度，单位px。lfit类型必须设置w或h，fill fixed类型必须同时设置w和h。
    h 1-4096 设置缩略图的高度，单位px。lfit类型必须设置w或h，fill fixed类型必须同时设置w和h。
    limit 0,1 设置是否限制图片缩放的尺寸大小不可超过原图大小，0不限制，1限制。非必选，默认0不限制。
    color 8位十六进制颜色码 指定pad类型下填充颜色，前6位分别表示RGB色，如ffffff；最后2位表示Alpha通道，可省略，省略时表示不透明。非必选，默认黑色。

    缩略类型详细说明：

    • lfit：等比缩放图片，缩放到能放到以w、h为宽高的矩形内的最大缩放图片。
    • mfit：等比缩放图片，缩放到能包含住以w、h为宽高的矩形的最小缩放图片。
    • fill：mfit基础上，对w、h矩形内的图片部分进行裁剪。
    • pad：lfit基础上，对w、h矩形内的非图片空白部分进行指定颜色填充。
    • fixed：强制缩放到指定w宽、h高。

    示例

    裁剪

    对图片进行矩形裁剪操作。

    action名称：crop

    参数 取值 说明
    x 0-图片宽度 裁剪左上角起点相对原点的x坐标，非必选，默认0。
    y 0-图片高度 裁剪左上角起点相对原点的y坐标，非必选，默认0。
    w 1-4096 裁剪后图片的宽度，如果指定的宽度超过了图片的宽度，则以图片宽度为准裁剪。单位为px。非必选，默认值原始图片宽度。
    h 1-4096 裁剪后图片的高度，如果指定的高度超过了图片的高度，则以图片高度为准裁剪。单位为px。非必选，默认值原始图片高度。

    示例

    内切圆裁剪

    以图片中心为圆心，进行内切圆裁剪。

    action名称：circle

    参数 取值 说明
    r 0-图片最小边大小的一半 以图片中心为圆心，从图片取出的半径为r的圆形区域，r如果超过最小边大小的一半，默认取原圆的最大内切圆。

    示例

    圆角矩形裁剪

    将图片裁剪为圆角矩形。

    action名称：rounded-corners

    参数 取值 说明
    r 1-4096 设置圆角的半径。如果指定半径r大于原图宽/高，则默认原图宽/高。

    示例

    旋转

    对图片进行一定角度的旋转。

    action名称：rotate

    参数 取值 说明
    a -360-360 图片旋转角度，正数表示顺时针旋转，负数表示逆时针旋转。

    示例

    自适应方向旋转

    根据exif信息进行自动旋转。

    action名称：auto-orient

    参数 取值 说明
    o 0,1 0：按原图默认方向，不自动旋转；1：自适应旋转。

    格式转换

    对图片格式进行转换。

    action名称：format

    参数 取值 说明
    f jpg、png、bmp、webp、heic、gif、auto 指定目标图片的图片格式，如果为值auto则根据请求Header的Accept字段自动选择最优格式。

    渐进显示

    指定图片显示方式。

    action名称：interlace

    参数 取值 说明
    i baseline，progressive baseline：标准式，指图片按照从上到下的扫描方式显示；progressive：渐进式 ，指图片由模糊到清晰渐进显示。progressive 只对jpg、png格式图片有效，若指定其他格式，则默认显示方式仍为baseline。

    质量变换

    对图片质量进行压缩，质量参数对PNG、BMP和GIF格式无效。

    action名称：quality

    参数 取值 说明
    q 1-100 指定图片的相对质量，假设原图质量为N，则压缩后质量为N * q%
    Q 1-100 指定图片的绝对质量，假设原图质量为N，如果Q < N，则按照Q进行重新编码，否则保持原图质量N不变

    示例

    水印

    对一张图片添加水印处理。

    action名称：watermark

    图片水印参数 取值 说明
    bucket - 指定水印图片存储在BOS的Bucket名称，非必选，默认当前bucket。非当前bucket则要求该水印图片有公共读权限。
    image - 指定水印图片存储在BOS的Object名称，需要取url安全的Base64编码后的值。图片水印必选参数。
    t 1-100 指定图片水印透明度，取值为100时，表示与原始透明度一致。非必选，默认值100。

    文字水印参数 取值 说明
    text - 水印文字内容，需要进行url安全的Base64编码，且编码后最多不能超过200个字符。文字水印必选。
    size 1-1024 指定水印字体大小，单位px。非必选，默认30。
    color 8位十六进制颜色码 指定字体颜色，前6位分别表示RGB色，如ffffff；最后2位表示Alpha通道，可省略，省略时表示不透明。非必选，默认000000黑色。
    type 支持的字体见下表 指定字体的字体类型，取值要求进行url安全的Base64编码。非必选。若指定的字体样式不在当前已支持的fontFamily列表中，则显示效果为默认字体宋体。
    style normal、italic、bold 指定字体样式。normal（常规）italic（斜体）bold（粗体）。非必选，默认normal。只有当字体支持style效果时，才会渲染文字效果。

    公共水印参数 取值 说明
    g 1-9 指定水印的锚点位置。非必选，默认9。具体含义见下方说明。
    x -4096-4096 指定水印基于锚点的水平方向距离。非必选，默认值10。
    y -4096-4096 指定水印基于锚点的垂直方向距离。非必选，默认值10。
    a -360-360 指定水印旋转角度。正数表示顺时针旋转，负数表示逆时针旋转。非必选，默认值0。

    说明：

    • 目前不支持在一组action中同时指定图片和文字水印，只能指定图片或文字水印一种类型。如果需要指定图片和文字水印，可通过多组action实现。
    • 锚点位置说明，将您的原始图片分成如下图所示9个区域，并按照图示位置进行编号，每个区域的锚点位置如图所示： gravity.png

    目前支持的字体类型如下：

    字体 名称 base64编码
    FZLanTingHei 方正兰亭黑 RlpMYW5UaW5nSGVp
    FZFangSong 方正仿宋 RlpGYW5nU29uZw==
    FZShuSong 方正书宋 RlpTaHVTb25n
    FZKai 方正楷体 RlpLYWk=
    FZHei 方正黑体 RlpIZWk=

    示例

    获取图片信息

    此命令用来获取图片信息，如果图片有exif信息则返回包含exif的完整信息，如果图片不包含exif信息，则返回图片的基本信息。

    action名称：info

    此命令没有参数，以 x-bce-process=image/info 形式访问即可。

    图片处理样式

    图片样式是指您可以将一些常用的图片处理操作保存为一个别名，即一个样式。这样，一组复杂的操作，利用样式，可以通过一个简洁的访问即可达到相同效果。

    样式访问

    整体的图片样式访问形式为：x-bce-process=style/${stylename}，说明如下：

    • style：当使用图片样式访问时，需要指定此处名字为style。

    • stylename：访问的style的名字。

      说明，因为BOS的图片处理命令分新旧两种版本，因此，一个图片处理样式所对应的实际图片处理命令可以是新版或旧版。
      这里x-bce-process=style/${stylename}的访问方式只能访问新版命令所对应的样式，旧版本命令所对应的样式仍需通过旧版本@!方式访问。

    添加/删除样式

    目前通过console添加的样式仍为旧版本命令的样式，新版本命令样式功能即将开通。

    原图保护

    BOS支持通过API实现原图保护功能，并可通过resource字段指定该功能生效范围，具体请参见原图保护。 对于开通原图保护的文件，不允许匿名下载访问该文件，或带自定义图片处理参数访问，只允许使用style样式访问或携带合法签名访问。