功能概述
对象存储通过数据万象 watermark 接口提供图片水印处理功能。目前水印图片必须指定为已存储于数据万象绑定(或新建)的存储桶中的图片。关于图片水印等图片基础处理的限制说明,请参见 规则与限制。
该功能支持以下处理方式:
- 下载时处理
- 上传时处理
- 云上数据处理
说明:
- 图片处理功能为收费项,由数据万象收取,详细的计费说明请参见数据万象 图片处理费用。
- 一张图片上,最多添加10张不同的图片水印。
- 不支持添加动图作为水印。
接口示例
1. 下载时处理
download_url?watermark/1/image/<encodedURL>
/gravity/<gravity>
/dx/<dx>
/dy/<dy>
/blogo/<type>
说明:请忽略上面的空格与换行符。
2. 上传时处理
PUT /<ObjectKey> HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Authorization: Auth String
Pic-Operations:
{
"is_pic_info": 1,
"rules": [{
"fileid": "exampleobject",
"rule": "watermark/1/image/<encodedURL>
/gravity/<gravity>
/dx/<dx>
/dy/<dy>
/blogo/<type>"
}]
}
3. 云上数据处理
POST /<ObjectKey>?image_process HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Content-length: Size
Authorization: Auth String
Pic-Operations:
{
"is_pic_info": 1,
"rules": [{
"fileid": "exampleobject",
"rule": "watermark/1/image/<encodedURL>
/gravity/<gravity>
/dx/<dx>
/dy/<dy>
/blogo/<type>"
}]
}
说明:Authorization: Auth String (详情请参见 请求签名 文档)。
处理参数说明
操作名称:watermark,数字1,表示水印类型为图片水印。
参数 | 含义 |
---|---|
download_url | 文件的访问链接,具体构成为<BucketName-APPID>.cos.<Region>.myqcloud.com/<picture name>, 例如 examplebucket-1250000000.cos.ap-shanghai.myqcloud.com/picture.jpeg |
/image/ | 水印图片地址,需要经过 URL 安全的 Base64 编码。例如,水印图片为http://examplebucket-1250000000.cos.ap-shanghai.myqcloud.com/shuiyin_2.png ,则该处编码后的字符串为aHR0cDovL2V4YW1wbGVidWNrZXQtMTI1MDAwMDAwMC5jb3MuYXAtc2hhbmdoYWkubXlxY2xvdWQuY29tL3NodWl5aW5fMi5wbmc |
/gravity/ | 文字水印位置,九宫格位置(参考九宫格方位图 ),默认值为 SouthEast |
/dx/ | 水平(横轴)边距,单位为像素,缺省值为0 |
/dy/ | 垂直(纵轴)边距,单位为像素,默认值为0 |
/blogo/ | 水印图适配功能,适用于水印图尺寸过大的场景(如水印墙)。一共有两种类型: |
/scatype/ | 根据原图的大小,缩放调整水印图的大小: |
/spcent/ | 与 scatype 搭配使用:http://examples-1251000004.cos.ap-shanghai.myqcloud.com/sample.jpeg?watermark/1/image/xxxxxxx/scatype/3/spcent/250 |
/dissolve/ | 图片水印的透明度,取值为1 - 100,默认90(90%不透明度) |
/batch/ | 平铺水印功能,可将图片水印平铺至整张图片。值为1时,表示开启平铺水印功能 |
/degree/ | 当 batch 值为1时生效。图片水印的旋转角度设置,取值范围为0 - 360,默认0 |
注意:指定的水印图片必须同时满足如下3个条件:
- 水印图片与源图片必须位于同一个存储桶下。
- URL 需使用 COS 域名(不能使用 CDN 加速域名,例如
examplebucket-1250000000.file.myqcloud.com/shuiyin_2.png
不可用 ),且需保证水印图可访问(如果水印图读取权限为私有,则需要携带有效签名)。- URL 必须以
http://
开始,不能省略 HTTP 头,也不能填 HTTPS 头,例如examplebucket-1250000000.cos.ap-shanghai.myqcloud.com/shuiyin_2.png
,https://examplebucket-1250000000.cos.ap-shanghai.myqcloud.com/shuiyin_2.png
为非法的水印 URL。
九宫格方位图
九宫格方位图可为图片的多种操作提供位置参考。红点为各区域位置的原点(通过 gravity 参数选定各区域后位移操作会以相应远点为参照)。
说明:
- 当 gravity 参数设置为 center 时,dx、dy 参数无效。
- 当 gravity 参数设置为 north 或 south 时,dx 参数无效(水印会水平居中)。
- 当 gravity 参数设置为 west 或 east 时,dy 参数无效(水印会垂直居中)。
实际案例
说明:本篇文档中的实际案例仅包含下载时处理,该类处理不会保存处理后的图片至存储桶。如有保存需求,您可查阅 图片持久化处理 文档并配置上传时处理或云上数据处理。
案例一:添加图片水印
http://examples-1251000004.cos.ap-shanghai.myqcloud.com/sample.jpeg?watermark/1/image/aHR0cDovL2V4YW1wbGVzLTEyNTEwMDAwMDQucGljc2gubXlxY2xvdWQuY29tL3NodWl5aW4uanBn/gravity/southeast
添加图片水印后效果如下:
案例二:添加图片水印并设置平铺、透明度
https://examples-1251000004.cos.ap-shanghai.myqcloud.com/sample.jpeg?watermark/1/image/aHR0cDovL2V4YW1wbGVzLTEyNTEwMDAwMDQucGljc2gubXlxY2xvdWQuY29tL3NodWl5aW4uanBn/gravity/southeast/batch/1/degree/45/dissolve/40/
添加图片水印并设置旋转45度平铺、透明度为40%后,效果如下:
案例三:添加图片水印并携带私有文件签名
处理方式同上,仅增加签名部分,并与图片处理参数以“&”连接,示例如下:
http://examples-1251000004.cos.ap-shanghai.myqcloud.com/sample.jpeg?q-sign-algorithm=<signature>&watermark/1/image/aHR0cDovL2V4YW1wbGVzLTEyNTEwMDAwMDQucGljc2gubXlxY2xvdWQuY29tL3NodWl5aW4uanBn/gravity/southeast
说明:<signature>为签名部分,获取方式请参考 请求签名。
注意事项
为了避免未授权人员通过访问不携带处理参数的链接实现访问和下载原图的情况,您可同时将处理参数签入到请求签名中,处理参数整体是参数的 key,value 为空,如下是简单的示例(仅做样式参考,可能已经过期无法直接访问),详细计算方法请参见 请求签名。
http://examples-1251000004.cos.ap-shanghai.myqcloud.com/sample.jpeg?q-sign-algorithm=sha1&q-ak=AKID********************&q-sign-time=1593342360;1593342720&q-key-time=1593342360;1593342720&q-header-list=&q-url-param-list=watermark%252f1%252fimage%252fahr0cdovl2v4yw1wbgvzlteyntewmdawmdqucgljc2gubxlxy2xvdwquy29tl3nodwl5aw4uanbn%252fgravity%252fsoutheast&q-signature=26a429871963375c88081ef60247c5746e834a98&watermark/1/image/aHR0cDovL2V4YW1wbGVzLTEyNTEwMDAwMDQucGljc2gubXlxY2xvdWQuY29tL3NodWl5aW4uanBn/gravity/southeast