Imgxs ################### 服务概述 =================== Imgxs 是新浪云提供的一个在线实时图像处理服务。 以http协议提供服务，通过在uri中添加命令实现图片的缩放、剪裁、特效、水印等功能。 服务开启及配置 =================== 在管理面板开启服务 ------------------- 进入新浪云图片处理服务管理面板 https://imgxs.sinacloud.com，点击 **+创建新实例** ，选择一个图片的源站，并输入实例的名称即可创建一个图片处理的实例。 .. image:: /images/imgxs/create_instance.png .. image:: /images/imgxs/create_detail.png .. note:: 实例的名称会用于当前创建的图片处理服务默认的二级域名，一旦创建无法修改。 选择认证方式 ------------------- 创建实例后进入实例的管理页面，从 **实例概览** 页面选择操作 **访问验证** 即可选择认证方式，如图所示： .. image:: /images/imgxs/update_verify.png *认证方式分为以下几种：* + 无需认证，可直接访问。 + basic 认证，此方式用户名密码是通过base64编码存储在header中，如果您走的是非加密方式传输，该方法容易泄漏密码。 + SAE签名认证。'SAE 用户名:签名'。签名算法：base64(hmac_sha1(密码, 请求方法+'\\n'+请求日期+'\\n'+请求的uri)) 实例的用户名和密码为实例的Accesskey和Secretkey，从 **实例概览** 页面即可查看，如图所示。 .. image:: /images/imgxs/view_ak_sk.png 配置上游服务器 ------------------- 单个实例最多可以配置10个上游服务器，创建实例后可以修改或者新增上游服务器信息。 + 新增源站 从实例的管理页面，选择 **源站管理**，点击 **+增加一个源** 选择源站的类型即可新增一个上游服务器，新增成功后系统会自动分配一个源站的标识（3位的字符串）。 .. image:: /images/imgxs/add_ups.png .. note:: 如果源站为多个，请以英文逗号隔开，例如 ``1.1.1.1,2.2.2.2`` ，当源站为多个时，系统会自动按负载均衡策略请求，超时时会重试。 + 修改源站信息 从源站的列表中点击 **修改源站** 即可修改当前上游服务器信息。 + 配置上游认证脚本 如果上游服务器需要认证（例如云存储的bucket设置为匿名不可读，storage的bucket设置为私有时），需要配置认证字符串，该字符串实则是一段兼容php语法的脚本。访问上游资源时会在我们提供的运行时环境中执行这段脚本得到最终的签名。 运行时环境提供了以下函数和常量，不允许自定义变量。自定义的字符串常量用英文［双／单］引号，字符串相加用（ . ）注意前后的空格。 ============= ========== ================================================ ================================================== 名称 类型 作用 语法以及说明 ============= ========== ================================================ ================================================== scs 函数 新浪云存储签名函数 string scs(string $AccessKey, string $SecretKey) ssr 函数 新浪storage签名函数 string ssr(string $accessKey, string $secretKey) base64 函数 base64编码 string base64(string $str) hmac_sha1 函数 HMAC-SHA1 运算 string hmac_sha1(string $secretKey, string $str) http_time 函数 返回一个可以用在http头部时间的格式化字符串 string http_time(int $sec) // $sec: 秒为单位的时间戳 substr 函数 截取字符串 string substr(string $string, int $start [,int $length]) METHOD 常量 向上游发起请求的方法 METHOD 取值：GET HEAD 等 DATE_STAMP 常量 向上游发起请求的时间戳 秒为单位的时间戳 DATE 常量 向上游发起请求的时间 和http_time(DATE_STAMP)是等价的 // DATE的格式："Thu, 18 Nov 2010 11:27:35 GMT" RESOURCE 常量 上游的资源 ============= ========== ================================================ ================================================== .. note:: 根据新浪云储存文档说明，签名字符串为： ``"SINA AccessKey:" . substr(base64(hmac_sha1(SecretKey, METHOD . "\n\n\n" . DATE . "\n" . RESOURCE)), 5, 10)`` 等价于scs函数。 绑定独立域名 ------------------- 图片处理实例支持绑定独立域名，可以绑定独立域名访问该实例。从实例的管理首页，选择左侧标签 **域名绑定** 即可。点击 **+绑定一个域名** 输入待绑定的域名提交后按系统提示完成验证域名解析和CNAME解析即可。 .. image:: /images/imgxs/bind_domain.png .. note:: + 仅支持已备案域名绑定，如果未备案请从 http://ba.sinacloud.com 先完成备案。 + 当前普通用户单实例支持绑定一个独立域名，如果需要支持多个，请升级账户等级。 上传SSL证书开启HTTPS访问 ------------------------- 图片处理服务绑定的独立域名支持上传SSL证书开启HTTPS访问，绑定独立域名通过验证后即可上传SSL证书。从域名列表的 **操作** 中选择 **上传证书**，按要求输入证书内容、证书密钥、中间证书内容即可。 .. note:: 系统默认分配的二级域名支持HTTPS访问，例如 https://imgxs.applinzi.com 保存指令（缩短URL） ------------------------- 当对图片处理的指令较多时，如果在每次请求都带上指令，会导致图片的URL较长，可以将指令保存为一个指令集。 例如 f_webp,w_670,h_500,t_hello+sae-jwwz-30-FF4500--10-30,p_dGVzdGltZ3hzL2xvZ28vc2luYWNsb3VkLnBuZw==-70--northeast|t_Imgxs-yst-50-DEB887-south 对图片做大小变化、并加水印，指令较长。可以从管理面板中保存该指令，进入管理面板，选择左侧导航 **指令管理**，进入指令管理功能。点击 **+增加一个指令**，输入指令列表，提交后系统会自动生成一个标识。 .. image:: /images/imgxs/add_cmd.png 例如源站访问地址为 http://imgxs.applinzi.com/f_webp,w_670,h_500,t_hello+sae-jwwz-30-FF4500--10-30,p_dGVzdGltZ3hzL2xvZ28vc2luYWNsb3VkLnBuZw==-70--northeast|t_Imgxs-yst-50-DEB887-south/scs/testimgxs/hunter.jpg ，保存指令后，系统分配的标识为 ``sae`` ，图片访问路径可以缩短为 ``http://imgxs.applinzi.com/sc_sae/scs/testimgxs/hunter.jpg`` .. note:: 保存后生成的指令标识需要加 ``sc_`` 前缀才能访问。 设置404默认图片 ------------------------- 如果需要使用默认的占位图片或者404图片，可以在源站的同级目录下放置一个名为 ``notfound.jpg`` 的图片。 .. note:: 当前 ``notfound.jpg`` 需要放在同级目录下，例如你访问的资源在 /a/b/c 目录下，需要将 ``notfound.jpg`` 放在/a/b/c/notfound.jpg这个位置。 服务使用 =================== 访问方式 ------------- http://appname.applinzi.com/cmd/ups/ups-path .. note:: + appname是服务开启设置的服务名（例如imgxs）。 + cmd就是图片处理指令（例如 ``w_400,h_300`` 将图片处理为400像素宽，300像素高）。 + ups是配置的上游服务器 （添加源站后系统自动分配，例如 ``scs``）。 + ups-path是上游图片（例如源站为云存储时，一个bucket为testimgxs，该bucket下有一张名为hunter.jpg的图片，路径则为 ``/testimgxs/hunter.jpg`` ）。组合以上，处理后的图片访问地址为 ``http://imgxs.applinzi.com/w_400,h_300/scs/testimgxs/hunter.jpg`` ，图片支持png，jpeg，jpg，webp这几种格式。 错误代码 ------------- 错误以json格式返回，json包括了Code和Message和Resource字段。 如： + {"Resource":"\/w_500,sc_sae\/scs\/testimgxs\/hunter.jpg","Message":"Group[1] SubCmd(sc_sae) mutually exclusive of cmd","Code":"InvalidRequest"} 代表指令sc和w指令互斥。 + {"Resource":"\/w_500\/se1\/testimgx\/huntefdsar.jpg","Message":"resolver host error","Code":"UpstreamError"} 代表上游服务器配置错误。 其中错误的Code包括： - ServiceClose: 没有开启服务或服务已关闭。 - InvalidRequest: 请求uri不正确，具体错误还需要看Message。 - InvalidFileType: 不支持上游文件类型。 - UpstreamError: 上游错误。 - UnAuthorized：服务认证不通过。 - NotFound： 上游资源不存在。默认还会获取相同路径下的notfound.jpg图片做处理，只有两个资源都不存在才会报错。 - InternalError：服务端异常。 指令说明 ------------- 指令是对图片的操作方式，可以由多组指令共同处理，每组指令之间通过管道符（|）分割。 组内指令用英文逗号分隔，同一组内不允许有相同的指令。 例如：w_300,h_300,r_30,p_png,t_hello+world--30-FF4500-southeast|t_hello+liwq--50--center **版本（v）** + 格式：v_version + 取值：version取值0-100 + 说明：用于刷新缓存，多组指令只有最后一组指令中的版本生效。 **图片格式（f）** + 格式：f_format + 取值：format 取值 png，jpeg，jpg，webp，tiff，tif，gif + 说明：转换为指定的图片格式。合成gif格式的图片还需要特效指令的支持。如果客户端支持建议使用webp格式。 **图片质量（q）** + 格式：q_quality + 取值：quality取值0-100，默认为75。 + 说明：图片压缩质量，仅对jpeg、jpg、webp、tiff、tif格式有作用。如果没有特殊需求，建议使用默认quality。 **图片宽度（w）** + 格式：w_width + 取值：width 取值0-4000。 + 说明：如果指定了宽度没指定高度，则按照宽度等比例缩放图片。 **图片高度（h）** + 格式：h_highly + 取值：highly取值0-3000。 + 说明：如果指定了高度没指定宽度，则按照高度等比例缩放图片。如果同时指定了宽度和高度，则不保证原图比例。 **剪裁（c）** + 格式：c_[gravity-]x-y + 取值：`gravity`_ 为图片剪裁的位置，可选。若不指定，x、y 为选定的横纵坐标，0-0为图片的左上角。若指定gravity，x、y为相对于gravity的横纵坐标。 `gravity`_ 取值除了位置说明中的northwest等值，还可以指定用来剪裁单个人脸的'face'和多个人脸的'faces'。 `gravity`_ 还可以指定为centergreed，从图片中间位置贪婪地剪裁一个正方形图像，方便制作九宫格缩略图。 + 说明： **圆角（r）** + 格式：r_radius + 取值：radius取值0-360或max。 + 说明：圆角剪裁，不支持jpg、jpeg、gif格式 **旋转（re）** + 格式：re_degrees + 取值：degrees取值0-360，flip:垂直翻转，flop:水平翻转。 + 说明：图片旋转。 **特效（e）** + 格式：e_effect-parameter + 取值：effect取值 - grayscale: 黑白。 (*参数:* 无) - negate: 反色。 (*参数:* 无) - contrast: 自动对比度。 (*参数:* 无) - oilpaint: 油画。 (*参数:* parameter取值1-8，默认3.) - brightness: 亮度。 (*参数:* parameter取值0-1000，默认120.) - blur: 模糊。 (*参数:* parameter取值0-2000，默认50.) - sharpen: 锐化。 (*参数:* parameter取值1-2000，默认50.) - spread: 毛玻璃。 (*参数:* parameter取值1-100，默认2.) - charcoal: 炭笔。 (*参数:* parameter取值1-100，默认2.) - red: 增加红色。 (*参数:* parameter取值1-100，默认2.) - green: 增加绿色。 (*参数:* parameter取值1-100，默认2.) - blue: 增加蓝色。 (*参数:* parameter取值1-100，默认2.) - yellow: 增加黄色。 (*参数:* parameter取值1-100，默认2.) - gray: 灰色。 (*参数:* parameter取值1-100，默认2.) - mosaic: 拼接。 (*参数:* parameter取值pic-w-h-x-y，pic为图片的base64编码，为空则为uri指定的图片。w为图片宽度，h为图片高度，x,y拼接横纵坐标。) - dynamic: 动图。 (*参数:* parameter取值pics-delay，pics为多张图片的base64编码，格式：prefix[seq1,seq2,seq3].format，最多允许8张图片。同时必须指定图片格式为gif。例如：``echo -n 'dynamic/pic_[1,3,4].jpg' |base64`` 把pic_1.jpg pic_3.jpg pic_4.jpg 和uri指定的图片4张图片合成gif动图。) + 说明： **边框（b）** + 格式：b_width-highly-color + 取值：width边框宽度，highly边框高度。color边框颜色，颜色为颜色的代码（如：FF4500）。 + 说明：边框。 **文字水印（t）** + 格式：t_text-font-size-color-gravity-x-y-angle + 取值：text为水印文字。 `font`_ 为字体样式。size为字体大小。color为字体颜色，格式为颜色代码（如：FF4500）。 `gravity`_ 为文字位置。x、y为相对于gravity的横纵坐标。angle为文字角度。 + 说明：添加文字水印。 **图片水印（p）** + 格式：p_picture-w-h-gravity-x-y-re + 取值：picture为水印图片，w为水印图片的宽度，h为水印图片的高度，`gravity`_ 为水印图片位置，x、y为水印图片添加到原图相对于gravity的横纵坐标，re为水印图片旋转的角度。 + 说明：添加图片水印。picture为水印图片的base64编码。例如：``echo -n 'logo/sinacloud_logo.png' |base64`` **命令简化（sc）** + 格式：sc_cmd + 取值：cmd 为上述多组指令组合的字符串。 + 说明：简化命令。简化指令只能和版本一同使用，否则会报指令无效。在控制面板设置简化指令，例如设置了sc1:w_300,h_300,r_30,p_png,t_hello+world--30-FF4500-southeast|t_hello+liwq--50--center。则通过sc_sc1就可以调用到该简化指令。简化指令为开发提供了方便。 字体样式 ------------ .. _font: +----------+--------+----------+ |字体 |命令 | 说明 | +==========+========+==========+ | 微软仿宋 | msfs | 无 | +----------+--------+----------+ | 微软雅黑 | msyh | 无 | +----------+--------+----------+ | 微软楷体 | mskt | 无 | +----------+--------+----------+ | 少儿简体 |fzsejt | 无 | +----------+--------+----------+ |瘦金书简体|fzsjsjt | 无 | +----------+--------+----------+ | 简花蝶体 | jhdt | 无 | +----------+--------+----------+ | 简娃娃篆 | jwwz | 无 | +----------+--------+----------+ |微软简仿宋|msjfs |仅支持英文| +----------+--------+----------+ |微软简行楷|msjxk |仅支持英文| +----------+--------+----------+ | 淹水体 | yst |仅支持英文| +----------+--------+----------+ 位置说明 -------------- .. _gravity: .. code-block:: console northwest | north | northeast ------------+------------+------------ west | center | east ------------+------------+------------ southwest | south | southeast 指令示例 =================== 示例实例说明 --------------- + 以下示例实例名为imgxs，上游服务器scs（上游服务器标识）为云储存服务，云存储bucket为testimgxs，该bucket设置为匿名用户不可读，需要通过签名才能访问，该实例上游服务器scs已经配置签名为 **云存储标准签名**。 + 测试图片为testimgxs（bucket）下的hunter.jpg图片，原图大小为1024x768。 + 配置了简化指令sc1为f_webp,w_670,h_500,t_hello+sae-jwwz-30-FF4500--10-30,p_dGVzdGltZ3hzL2xvZ28vc2luYWNsb3VkLnBuZw==-70---580-10|t_Imgxs-yst-50-DEB887-south 格式转换 --------------- 把原图jpg格式转为png格式。 http://imgxs.applinzi.com/f_png/scs/testimgxs/hunter.jpg 图片缩放 --------------- - 原图等比例缩小一倍 http://imgxs.applinzi.com/w_512/scs/testimgxs/hunter.jpg - 同时指定宽度300和高度300缩小 http://imgxs.applinzi.com/w_300,h_300/scs/testimgxs/hunter.jpg 图片剪裁 --------------- - 剪裁图片中间（center）的图像 http://imgxs.applinzi.com/c_384-288,w_256/scs/testimgxs/hunter.jpg http://imgxs.applinzi.com/c_center-10-10/scs/testimgxs/hunter.jpg - 贪婪模式剪裁图片中间（centergreed）的图像 http://imgxs.applinzi.com/c_centergreed-0-0/scs/testimgxs/hunter.jpg http://imgxs.applinzi.com/c_centergreed-0-0|h_300/scs/testimgxs/hunter.jpg - 剪裁图片中的人脸 http://imgxs.applinzi.com/f_png,c_face/scs/testimgxs/face/charles.png 图片圆角、旋转 --------------- 格式转换＋按高度等比例缩小＋圆角＋旋转＋增加蓝色效果 http://imgxs.applinzi.com/f_png,h_300,r_90,re_330,e_blue-10/scs/testimgxs/hunter.jpg 加边框 --------------- 加一个金色的边框：色码表，金色的颜色代码为#FFD700 http://imgxs.applinzi.com/f_png,h_300,b_10-3-ffd700/scs/testimgxs/hunter.jpg 加文字水印 --------------- 添加文字水印：在图片左上角添加“hello world”，字体样式为微软仿宋，大小为20px，颜色为金黄色，坐标为（5，20）。在图片右下角添加日期。 http://imgxs.applinzi.com/f_png,h_300,t_hello+world-msfs-20-ffd700--5-20%7Ct_2020.05.01--10--southeast-10-10-90/scs/testimgxs/hunter.jpg 加图片水印 --------------- 添加图片水印：在图片左上角添加一个宽度为50px的logo，logo后添加一行文字“@sae”，在图片下方添加一个logo。其中dGVzdGltZ3hzL2xvZ28vc2luYWNsb3VkLnBuZw== 为logo图片路径的base64编码。 http://imgxs.applinzi.com/f_png,w_500,p_dGVzdGltZ3hzL2xvZ28vc2luYWNsb3VkLnBuZw==-50--northwest-0-0,t_@sae--15-00ffff--55-13%7Cp_dGVzdGltZ3hzL2xvZ28vc2luYWNsb3VkLnBuZw==---south/scs/testimgxs/hunter.jpg 图像拼接 --------------- 把logo拼接到图片下方。 http://imgxs.applinzi.com/f_png,h_300,e_mosaic-dGVzdGltZ3hzL2xvZ28vc2luYWNsb3VkLnBuZw==----300/scs/testimgxs/hunter.jpg 生成动图 --------------- 把apple.jpg、apple1.jpg、apple2.jpg、apple3.jpg、apple4.jpg这5张图片合成一张动图： http://imgxs.applinzi.com/f_gif,w_400,h_250,t_sae%E5%88%B6%E4%BD%9C-jwwz-30--southeast--20,e_dynamic-dGVzdGltZ3hzL2FwcGxlL2FwcGxlX1sxLDIsMyw0XS5qcGc=-200/scs/testimgxs/apple/apple.jpg .. note:: 图片的格式：``echo -n 'testimgxs/apple/apple_[1,2,3,4].jpg' |base64``