平安云 - 云以致用智造未来

JavaScript SDK

1. 简介 JavaScript SDK 适用于 IE9+、Chrome、Firefox、Safari 等浏览器，基于平安云OBS- API 构建。开发者使用本JS-SDK 可以方便的从浏览器端上传文件至平安云OBS，并对上传成功后的图片进行下载，删除，数据处理操作。 本 SDK 为客户端 JavaSript SDK，没有包含 token(用户操作凭证) 生成实现，为了安全，建议您通过网络从用户的签名服务端获取token，具体生成代码请参考后面签名服务模板。 如果您还没有开通或者还不了解平安云 OBS 服务，请登录<a href="/ssr/products/OBS" target="_blank">OBS产品主页 </a>进行了解。 <ul> <li>上传 <ul> <li> html5、Flash、html4 模式直接上传和分片上传 </li> <li> 继承了 Plupload 的功能，可筛选文件上传、拖曳上传等 </li> </ul> </li> <li>下载 用户通过JS SDK生成文件下载的 URL，用户访问该 URL 进行有效时间内下载。 </li> </ul> 2. SDK下载 JavaScript SDK 开发包最新版本<a href="https://pcp-portal-sca.obs-cn-shenzhen.pinganyun.com/sdk%2Fobs-javascript-sdk-1.3.1.zip?response-content-disposition=attachment%3Bfilename%3Dobs-javascript-sdk-1.3.1.zip" target="_blank">v1.3.1</a> 3. API概览 <table> <caption> </caption> <thead> <tr> <th>API</th> <th>描述</th> </tr> </thead> <tbody> <tr> <td> 签名服务准备 </td> <td> 本 SDK 依赖服务端颁发的上传凭证，可以通过网络从用户的服务端获取。 </td> </tr> <tr> <td> 初始化 </td> <td> 要接入平安云 OBS 存储，您需要拥有一对有效的 Access Key 和 Secret Key 进行签名认证。可以通过如下步骤获得： 开通 OBS 账号，登录 OBS 平台，查看 Access Key 和 Secret Key。 </td> </tr> <tr> <td> 上传 </td> <td> 上传文件 </td> </tr> <tr> <td> 下载 </td> <td> 下载文件 </td> </tr> </tbody> </table> 4. API描述 （1）签名服务准备 接口描述 本 SDK 依赖服务端颁发的上传凭证，可以通过网络从用户的服务端获取。 用户服务端可以通过下面两种方式去生成签名: <ul> <li>用户按照签名规则自行生成，详细的签名规则见 <a href="#JavaScript_SDK__aaa">附录OBS签名文档</a>。</li> <li>调用 OBS JAVA SDK 中 getSign 接口去生成签名，请参考下面的代码示例去返回 JSON 数据。</li> </ul> 后端服务应提供一个 URL 地址，供 SDK 获取签名使用，前端通过 Ajax 请求该地址后获得签名。Ajax 请求成功后，服务端应返回如下格式的 json。 示例 <pre> { // 根据算签规则计算出的签名 "signature":"TjEc68iSYpmw1qRiyIrJMnOF1M=", // 用户公钥 "AWSAccessKeyId":"TjEc68iSYpmw1qRiyIrJMnOF1M=", // 当前标准格式GMT时间 "date":"Mon, 28 Aug 2017 02:51:10 GMT", // 仅为下载URL时使用，当前时间的time值+过期的秒数，具体见附录OBS签名文档。 "expires":"1503889172" }</pre> 如果用户调用 OBS JAVA SDK 中 getSign 接口去生成签名，可以参考如下代码模板。 示例签名服务器 URL：http://xxx:8080/getSign <pre> @RequestMapping(value = "/getSign") public String getSign( @RequestParam(value = "path") String path, @RequestParam(value = "method") String method, @RequestParam(value = "contentType", required = false) String contentType, @RequestParam(value = "date", required = false) String date, @RequestParam(value = "expires", required = false) String expires, @RequestParam(value = "contentDisposition", required = false) String contentDisposition ) throws Exception { RadosgwService service = RadosgwServiceFactory.getFromConfigObject(new ObsClientConfig() { public String getUserAgent() { return ""; } public String getObsUrl() { return obsUrl; } public String getObsAccessKey() { return "<***user Access Key ***>"; } public String getObsSecret() { return "<***user Secret Key ***>"; } }); AuthSignData signData = new AuthSignData(); signData.setRequestPath(path); signData.setRequestMethod(method); signData.setContentType(contentType); if (expires == null || expires.equals("")) { signData.getSignData().put("Date", date); } else { signData.getSignData().put("Date", expires); signData.setResponseContentDisposition(contentDisposition); } String signature = service.getSign(signData); JSONObject json = new JSONObject(); json.put("AWSAccessKeyId", "<***user Access Key ***>"); json.put("signature", signature); json.put("date", date); json.put("expires", expires); return json.toString(); }</pre> 入参信息说明，请参见附录<a href="#JavaScript_SDK__aaa">签名规则</a>。 对使用该 SDK 的开发者而言，请参考后面具体的操作请求去进行相应的入参信息配置。 （2）初始化 接口描述 要接入平安云 OBS 存储，您需要拥有一对有效的 Access Key 和 Secret Key 进行签名认证。可以通过如下步骤获得： 1）开通 OBS 账号 2）登录 OBS 平台，查看 Access Key 和 Secret Key 3）在页面中引入<code>fincloud-pingan-obs-javascript-sdk-1.3.0.js</code>。 <pre>  </pre> 4）配置用户自己的签名服务器路径，目的：用户通过唯一的Access Key 和 Secret Key，根据签名规则，计算出用户端的签名，如果该签名和OBS服务端签名一致，那么验证通过，用户将能操作文件进行上传/下载。 （3）上传 接口描述 <ul> <li>要接入平安云 OBS在页面中引入 plupload.dev.js 和 moxie.js，可以从最新版本的压缩包中获取。</li> <li>在页面中引入fincloud-pingan-obs-javascript-sdk-1.3.0.js</li> <li>初始化 uploader (请确保在执行初始化时，页面已经引入 plupload)：</li> <li>分片上传默认支持一片5M，支持10000片上传。用户可以根据自己的业务需要，设置分片的大小，但一片最小必须是5M，建议最大不要超过30M。</li> </ul> 示例 <pre> var uploader = new PaObs.uploader({ runtimes : 'html5,flash,html4', //上传模式，依次退化 browse_button : 'selectfiles', //上传选择的点选按钮，必需 container: 'container', //上传区域DOM ID，默认是browser_button的父元素 endpoint: 'obs-cn-shanghai.yun.pingan.com', //上传地址PingAn-OBS-endpoint,从平安云OBS控制台获取. bucket:'user-bucket', //上传的bucket. //key:'objectKey', //对象存储的key，如果key为null，将用文件名作为key. //unique_names: true, //是否生成唯一的id作为对象的key.默认false，key为文件名。若开启该选项，JS-SDK会为每个文件自动生成key filters: [{title: "Image files", extensions: "jpg,gif,png"}, {title: 'Zip files', extensions: 'zip,7z,rar'}, {title: 'txt files', extensions: 'txt'} ], //文件限制 resize: { width: 500, height: 500, crop: true, quality: 60, preserve_headers: false }, //重置图片参数 uptoken_url:'', //签名路径，如果配置该URL，返回值将严格按照obs附件文档要求(用户服务端生成Token文档). uptoken_func: function (bucket, path, method, contentType, date, contentDisposition) { //如果同时设置了uptoken_url和uptoken_func，其优先级为uptoken_url > uptoken_func var requestTokenURL = 'http://<***user token server***>/getSign' + '?bucket=' + encodeURIComponent(bucket) + '&path=' + encodeURIComponent(path) + '&method=' + encodeURIComponent(method) + '&contentType=' + encodeURIComponent(contentType) + '&date=' + encodeURIComponent(date) + '&contentDisposition=' + encodeURIComponent(contentDisposition); var ajax = {}; if (window.XMLHttpRequest) { ajax = new XMLHttpRequest(); } else { ajax = new ActiveXObject("Microsoft.XMLHTTP"); } ajax.open('GET', requestTokenURL, false); ajax.send(); if (ajax.status == 200) { var res = JSON.parse(ajax.responseText); return res; } else { logger.error("***get uptoken failed from: ", requestTokenURL); uploader.trigger('Error', { status: 204, response: "getUpToken failed", file: file, code: plupload.HTTP_ERROR }); return ''; } }, //如果签名路径为空，用户可以自定义自己的签名获取方式，但返回值严格按照obs的json格式. init: { PostInit: function () { document.getElementById('obsfile').innerHTML = ''; document.getElementById('postfiles').onclick = function () { uploader.start(); return false; }; }, FilesAdded: function (up, files) {}, BeforeUpload: function(up, file) {}, UploadProgress: function (up, file) {}, FileUploaded: function (up, file, info) {}, Error: function (up, err) {}, UploadComplete: function() {}, } }); uploader.init(); </pre> 如果一个页面中有多个上传实例，可以按如下操作： <pre> var option1 = { key : val , …… }; var uploader = PaObs.uploader(option1); var PaObs2 = new PaObsJsSDK(); var option2 = { key : val , …… }; var uploader2 = PaObs2.uploader(option2); </pre> （4）下载 接口描述 <ul> <li>在页面中引入<code>fincloud-pingan-obs-javascript-sdk-1.3.0.js</code></li> <li>支持公私有url下载。</li> <li>支持参数选择缩略图下载，需要在公私有url上添加format值。</li> </ul> 示例 <pre> // 公有url生成 var url = PaObs.getUrl ({ domain: 'bucketXXX.obs-cn-shanghai.yun.pingan.com', //下载文件时所用的加速域名，或者OBS访问域名(访问域名从用户OBS控制台获取) bucket: 'bucketXXX', //下载文件的bucket key: 'objectKey', //下载文件的对象key format: 'imageView/0/w/500/h/500' //配置该参数去进行缩略图下载. }); // 私有url生成 var url = PaObs.getUrlWithToken({ domain: 'bucketXXX.obs-cn-shanghai.yun.pingan.com', //下载文件时所用的加速域名，或者OBS访问域名(访问域名从用户OBS控制台获取) bucket: 'bucketXXX', //下载文件的bucket key: 'objectKey', //下载文件的对象key downtoken_url: 'http://TokenServer/getSign', //下载文件的token获取路径. //downtoken_func:'' //如果用户自定义获取token方法，请配置该参数，并将downtoken_url设置为null expireSeconds: 120, //配置下载链接过期时间，以秒为单位. format: 'imageView/0/w/500/h/500' //配置该参数去进行缩略图下载. });</pre> 关于format :'imageView/{mode}/w/{weight}/h/{height}/format/{imageFormat}'说明: imageView是OBS API图片处理关键字。格式转换，获取适配图片，支持格式 jpeg，tiff, gif, bmp, png ，其中 gif 格式只会保留第一帧图片，此方法将占用一个 Http 连接，在 Content 读取完毕或显示关闭时释放连接。 mode：缩放方式，有效值 0~5： <ul> <li>0：限定缩略图的长边最多为，短边最多为，进行等比缩放，不裁剪。如果只指定 w 参数则表示限定长边（短边自适应），只指定 h 参数则表示限定短边（长边自适应）。</li> <li>1：限定缩略图的宽最少为，高最少为，进行等比缩放，居中裁剪。转后的缩略图通常恰好是 x 的大小（有一个边缩放的时候会因为超出矩形框而被裁剪掉多余部分）。如果只指定 w 参数或只指定 h 参数，代表限定为长宽相等的正方图。</li> <li>2：限定缩略图的宽最多为，高最多为，进行等比缩放，不裁剪。如果只指定 w 参数则表示限定宽（长自适应），只指定 h 参数则表示限定长（宽自适应）。它和模式0类似，区别只是限定宽和高，不是限定长边和短边。从应用场景来说，模式0适合移动设备上做缩略图，模式2适合PC上做缩略图。</li> <li>3：限定缩略图的宽最少为，高最少为，进行等比缩放，不裁剪。如果只指定 w 参数或只指定 h 参数，代表长宽限定为同样的值。你可以理解为模式1是模式3的结果再做居中裁剪得到的。</li> <li>4：限定缩略图的长边最少为，短边最少为，进行等比缩放，不裁剪。如果只指定 w 参数或只指定 h 参数，表示长边短边限定为同样的值。这个模式很适合在手持设备做图片的全屏查看（把这里的长边短边分别设为手机屏幕的分辨率即可），生成的图片尺寸刚好充满整个屏幕（某一个边可能会超出屏幕）。</li> <li>5：限定缩略图的长边最少为，短边最少为，进行等比缩放，居中裁剪。如果只指定 w 参数或只指定 h 参数，表示长边短边限定为同样的值。同上模式4，但超出限定的矩形部分会被裁剪。 `width:` 图片宽度，非负数，有效值（0-6000) <ul> <li>w代表width宽度，图片宽度，非负数，有效值（0-6000)</li> <li>h代表height高度，图片高度，非负数，有效值（0-6000)</li> <li>imageFormat：图片格式(非必传)，支持jpeg, tiff, gif, bmp, png</li> </ul> </li> </ul> 5. 常见问题 因为本JS-SDK主要基于 plupload，用户可以通过参阅 plupload 文档资料，可以对OBS的 demo 进行修改，以满足自己的业务需求，plupload 插件的使用文档请参阅plupload官方文档。 （1）关于上传文件命名问题 在 upload.js 里面，unique_names 是 plupload 插件下面的一个参数，当值为 true 时会为每个上传的文件生成一个唯一的文件名，这个是 plupload 插件自动生成的，如果设置成 false，OBS会以上传的原始名进行命名。 （2）使用plupload的resize设置压缩上传，可以使用该参数对将要上传的图片进行压缩，该参数是一个对象，里面包括5个属性： <pre> resize: { width: 100, height: 100, crop: true, quality: 60, preserve_headers: false }</pre> <ul> <li>width：指定压缩后图片的宽度，如果没有设置该属性则默认为原始图片的宽度</li> <li>height：指定压缩后图片的高度，如果没有设置该属性则默认为原始图片的高度</li> <li>crop：是否裁剪图片</li> <li>quality：压缩后图片的质量，只对jpg格式的图片有效，默认为90。quality可以跟width和height一起使用，但也可以单独使用，单独使用时，压缩后图片的宽高不会变化，但由于质量降低了，所以体积也会变小</li> <li>preserve_headers：压缩后是否保留图片的元数据，true为保留，false为不保留,默认为true。删除图片的元数据能使图片的体积减小一点。</li> </ul> （3）限制上传文件的类型 通过 plupload 中设定 filter 参数直接在 JS 前端限定，如下： <pre> filters: { mime_types : [ //只允许上传图片和zip文件 { title : "Image files", extensions : "jpg,gif,png" }, { title : "Zip files", extensions : "zip" } ], max_file_size : '400kb', //最大只能上传400kb的文件 prevent_duplicates : true //不允许选取重复文件.     }</pre> 可以使用该参数来限制上传文件的类型，大小等，该参数以对象的形式传入，它包括三个属性： <ul> <li>mime_types：用来限定上传文件的类型，为一个数组，该数组的每个元素又是一个对象，该对象有title和extensions两个属性，title为该过滤器的名称，extensions为文件扩展名，有多个时用逗号隔开。该属性默认为一个空数组，即不做限制。</li> <li>max_file_size：用来限定上传文件的大小，如果文件体积超过了该值，则不能被选取。值可以为一个数字，单位为b,也可以是一个字符串，由数字和单位组成，如’200kb’</li> <li>prevent_duplicates：是否允许选取重复的文件，为true时表示不允许，为false时表示允许，默认为false。如果两个文件的文件名和大小都相同，则会被认为是重复的文件</li> </ul> （4）设置每次只能选择一个文件 通过 plupload 插件中的 multi_selection 参数控制，如下： <pre> <code>multi_selection: false</code></pre> （5）设置取消上传，暂停上传 在 index.html 中加入两个控制按钮： <pre> <code>uploader.stop();</code></pre> （6）分片上传 目前JS SDK支持直传和分片上传。 当设置上传参数chunk_size:'0'的时候，上传方式为直传. 当未设置上传参数chunk_size的时候，上传文件大于5M，默认分片上传，每片为5M. （7）关于请求 token 出现跨域 因为都是建议用户从后端 SDK 获取 token，然后在 upload.js 里设置参数 uptoken_url:'获取uptoken的url'，这里就有可能出现跨域的现象，此时在服务端添加 response.setHeader("Access-Control-Allow-Origin","*"); 相应头字段即可。 （8）关于多个按钮选择文件的 Demo 很多用户都在问 JSSDK 多文件选择的 Demo，其实只需要在 upload.js 文件里多 new 几个 Uploader 对象，然后在主页上写好对应的上传按钮就可以了。upload.js 里面多 new 几个 uploader 对象。 6. 附录：签名规则 签名是系统根据签名规则生成出来的字符串，用于判断客户端和服务端生成的签名是否一致，以此来判断用户是否有权限在OBS进行操作。 用户签名分为： <ul> <li> Header签名: 用户可以在HTTP请求中增加 Authorization 的 Header 来包含签名（Signature）信息，表明这个消息已被授权。 </li> <li> URL签名：除了使用 Authorization Head，用户还可以在URL中加入签名信息，这样用户就可以把该URL转给第三方实现授权访问, 并且可以设置过期时间等。 </li> </ul> Header 签名 用户可以在HTTP请求中增加 Authorization 的 Header 来包含签名（Signature）信息，表明这个消息已被授权。 Authorization 字段计算的方法: <pre> Authorization = "AWS " + AccessKeyId + ":" + Signature Signature = base64(hmacSha1(AccessKeySecret, VERB + "\n" + Content_MD5 + "\n" + Content_Type + "\n" + Date + "\n" + CanonicalizedResource))</pre> <ul> <li>AccessKeySecret 表示签名所需的密钥</li> <li>VERB 表示HTTP 请求的 Method，主要有 PUT，GET，POST，HEAD，DELETE 等</li> <li>\n 表示换行符</li> <li>Content_MD5 表示请求内容数据的MD5值，对消息内容（不包括头部）计算MD5值获得128比特位数字，对该数字进行base64编码而得到。该请求头可用于消息合法性的检查（消息内容是否与发送时一致），如”eB5eJF1ptWaXm4bijSPyxw==”，也可以为空。为了避免影响性能，JS-SDK目前Content-MD5为null。</li> <li>Content_Type 表示请求内容的类型，如” application/x-www-form-urlencoded”，如果是POST请求，该值为“multipart/form-data”</li> <li>Date 表示此次操作的时间，且必须为GMT格式，如”Sun, 22 Nov 2015 08:16:38 GMT”</li> <li>CanonicalizedResource 表示用户想要访问的 OBS 资源</li> </ul> 其中，Date 和 CanonicalizedResource 不能为空；如果请求中的 Dat e时间和 OBS 服务器的时间差 15 分钟以上，OBS 服务器将拒绝该服务，并返回 HTTP 403 错误。 URL签名 除了使用 Authorization Head，用户还可以在URL中加入签名信息，这样用户就可以把该URL转给第三方实现授权访问，并且设置过期时间等。 URL签名示例： <pre> <code>http://obs.pingan.com.cn/xiaoming-bucket-0009/aaa?AWSAccessKeyId=sk-xiaoming009&Expires=1503903538&Signature=s5rmkBZ1DvkQRplG5GJ7HGd%2Fzik%3D&response-content-disposition=test.jpg</code></pre> URL签名，必须至少包含Signature，Expires，AWSAccessKeyId三个参数 <ul> <li>Expires 这个参数的值是一个UNIX时间（自UTC时间1970年1月1号开始的秒数，详见wiki），用于标识该URL的超时时间。如果OBS接收到这个URL请求的时候晚于签名中包含的Expires参数时，则返回请求超时的错误码。例如：当前时间是1141889060，开发者希望创建一个60秒后自动失效的URL，则可以设置Expires时间为1141889120。</li> <li>AWSAccessKeyId即密钥中的AccessKeyId。</li> <li>Signature 表示签名信息。所有的OBS支持的请求和各种Header参数，在URL中进行签名的算法和在Header中包含签名的算法基本一样。</li> </ul> Authorization 字段计算的方法 <pre> Signature = urlencode(base64(hmacSha1(AccessKeySecret, VERB + "\n" + CONTENT_MD5 + "\n" + CONTENT_TYPE + "\n" + EXPIRES + "\n" + CanonicalizedResource)))</pre> 其中，与header中包含签名相比主要区别如下： <ul> <li>通过URL包含签名时，之前的Date参数换成Expires参数。</li> <li>不支持同时在URL和Head中包含签名。</li> <li>如果传入的Signature，Expires，AWSAccessKeyId出现不止一次，以第一次为准。</li> <li>请求先验证请求时间是否晚于Expires时间，然后再验证签名。</li> <li>将签名字符串放到url时，注意要对url进行urlencode</li> </ul> 具体的计算签名的开源代码，请参考 OBS JAVA SDK 的 getSign 接口。

以上内容是否解决了您的问题？是否