有奖捉虫:云通信与企业服务文档专题,速来> HOT

功能概述

腾讯云数据万象通过 watermark 接口提供图片水印处理功能。目前水印图片必须指定为已存储于数据万象中的图片。该功能支持以下处理方式:
下载时处理
上传时处理
云上数据处理

授权说明

通过子账号使用时,需要授予对应权限,具体请参见 COS action,CI 其他权限请参见 数据万象 action
下载时处理:授权策略中 action 设置为 cos:GetObject
上传时处理:授权策略中 action 设置为 cos:PutObject
云上数据处理:授权策略中 action 设置为 cos:GetObjectcos:PutObject(注意 GetObject 对应的 resource 为源文件,PutObject 对应的 resource 为转存的文件)。

服务开通

使用该功能需提前开通数据万象,并绑定存储桶。详情请参见 绑定存储桶

使用限制

使用该接口时,请先确认相关限制条件。详情请参见 使用限制
一张图片上,最多添加10张不同的图片水印。
不支持添加动图作为水印。

费用说明

图片水印为付费服务,费用同基础图片处理,具体费用请参见 图片处理费用,产生的费用将由数据万象收取。
如果采用下载时处理的方式,且通过外网进行下载,调用会产生 流量费用

接口示例

下载时处理

GET /<ObjectKey>?watermark/1/image/<encodedURL>
/gravity/<gravity>
/dx/<dx>
/dy/<dy>
/blogo/<type> HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: <GMT Date>
Authorization: <Auth String>
说明
请忽略上面的空格与换行符。

上传时处理

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>"
}]
}

云上数据处理

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,详情请参见 请求签名 文档。
Pic-Operations 为 json 格式的字符串,具体参数信息可参见 图片持久化处理
fileid ObjectKey 相同时,处理后的图片将覆盖原图存储;不相同时将分别存储原图和处理后图片。
fileid 的值需要经过 URLEncode。

处理参数说明

操作名称:watermark,数字1,表示水印类型为图片水印。
参数
含义
是否必选
ObjectKey
对象文件名,例如 folder/sample.jpg。
watermark/1
代表当前的处理为图片水印。
/image/
水印图片的链接,需要经过 URL 安全的 Base64 编码。例如,水印图片为: http://examplebucket-1250000000.cos.ap-shanghai.myqcloud.com/shuiyin_2.png,则该处编码后的字符串为 aHR0cDovL2V4YW1wbGVidWNrZXQtMTI1MDAwMDAwMC5jb3MuYXAtc2hhbmdoYWkubXlxY2xvdWQuY29tL3NodWl5aW5fMi5wbmc
是,与/image_key/参数二选一
/image_key/
如果您在添加水印时不希望暴露水印所在的图片地址,可使用该参数。
该参数表示存储桶中水印图片所在的路径及名称,需要经过 URL 安全的 Base64 编码。例如,水印图片在本存储桶中的路径及名称为:
image/shuiyin_2.png
则该处编码后的字符串为: aW1hZ2Uvc2h1aXlpbl8yLnBuZw
是,与/image/参数二选一
/gravity/
图片水印位置,九宫格位置(参考九宫格方位图 ),默认值为 SouthEast。
/dx/
水平(横轴)边距,单位为像素,默认值为0。
/dy/
垂直(纵轴)边距,单位为像素,默认值为0。
/blogo/
水印图适配功能,仅适用于水印图尺寸比原图大的场景(如水印墙)。共有两种类型:
当 blogo 设置为1时,水印图会被缩小至与原图相似大小后添加
当 blogo 设置为2时,水印图会被直接裁剪至与原图相似大小后添加
/scatype/
根据原图的大小,缩放调整水印图的大小,需要与 spcent 搭配使用:
当 scatype 设置为1时,按原图的宽缩放
当 scatype 设置为2时,按原图的高缩放
当 scatype 设置为3时,按原图的整体面积缩放
/spcent/
与 scatype 搭配使用:
当 scatype 设置为1时,该有效值为[1,1000],单位为千分比
当 scatype 设置为2时,该有效值为[1,1000],单位为千分比
当 scatype 设置为3时,该有效值为[1,1000],单位为千分比。
示例: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个条件:
水印图片与原图片必须位于同一个存储桶下。
水印图片链接需使用 COS 域名(不能使用 CDN 加速域名,例如 examplebucket-1250000000.file.myqcloud.com/shuiyin_2.png 不可用 ),且需保证水印图可访问(如果水印图读取权限为私有,则需要携带有效签名)。
水印图片链接必须以http://开始,不能省略 HTTP 头,也不能填 HTTPS 头,例如 examplebucket-1250000000.cos.ap-shanghai.myqcloud.com/shuiyin_2.pnghttps://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%后,效果如下:



案例三:将添加图片水印与其他图片基础处理同时使用

您可以通过管道操作符,将其他处理操作与添加图片水印连接起来同时处理。
例如先将图片宽高缩小50%,再添加图片水印。
https://examples-1251000004.cos.ap-shanghai.myqcloud.com/sample.jpeg?imageMogr2/thumbnail/!50p|watermark/1/image/aHR0cDovL2V4YW1wbGVzLTEyNTEwMDAwMDQucGljc2gubXlxY2xvdWQuY29tL3NodWl5aW4uanBn/gravity/southeast
效果图如下所示:




案例四:添加图片水印并携带私有文件签名

处理方式同上,仅增加签名部分,并与图片处理参数以“&”连接,示例如下:
http://examples-1251000004.cos.ap-shanghai.myqcloud.com/sample.jpeg?q-sign-algorithm=<signature>&watermark/1/image/aHR0cDovL2V4YW1wbGVzLTEyNTEwMDAwMDQucGljc2gubXlxY2xvdWQuY29tL3NodWl5aW4uanBn/gravity/southeast
说明
<signature>为签名部分,获取方式请参考 请求签名

案例五:添加访问权限为私有读的图片作为水印

添加的私有图片链接需要携带签名参数保证水印图可访问,示例如下:
http://examples-1251000004.cos.ap-shanghai.myqcloud.com/sample.jpeg?watermark/1/image/aHR0cDovL2V4YW1wbGVzLTEyNTEwMDAwMDQucGljc2gubXlxY2xvdWQuY29tL3NodWl5aW4uanBnP3Etc2lnbi1hbGdvcml0aG09PHNpZ25hdHVyZT4/gravity/southeast

注意事项

为了避免未授权人员通过访问不携带处理参数的链接实现访问和下载原图的情况,您可同时将处理参数签入到请求签名中,处理参数整体是参数的 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