全部文档
当前文档

暂无内容

如果没有找到您期望的内容,请尝试其他搜索词

文档中心

JavaScript(旧版已下线)

最近更新时间:2023-01-03 11:58:56

KS3 SDK For javascript 使用指南

SDK下载地址

下载地址 https://github.com/ks3sdk/ks3-js-sdk.git

目录


1、概述

开发者使用本 SDK 可以方便的从浏览器端上传文件至金山云存储,可使开发者忽略上传底层实现细节,而更多的关注 UI 层的展现。

2、常见术语介绍

Object(对象,文件)

在KS3中,用户操作的基本数据单元是Object。单个Object允许存储0~48.8TB的数据。 Object 包含key和data。其中,key是Object的名字;data是Object 的数据。key为UTF-8编码,且编码后的长度不得超过1024个字符。

Key(文件名)

即Object的名字,key为UTF-8编码,且编码后的长度不得超过1024个字符。Key中可以带有斜杠,当Key中带有斜杠的时候,将会自动在控制台里组织成目录结构。

其他术语请参考概念与术语

3、快速入门

  1. 通过git下载SDK到本地

git clone https://github.com/ks3sdk/ks3-js-sdk.git

  1. SDK构成介绍及引入
  • plupload.full.min.js ,建议 3.1.2 及以上版本,下载地址:https://www.plupload.com/download/
  • ks3jssdk.js,SDK主体文件,封装了上传功能,源码位于src目录内, 压缩版本位于dist目录内

将js文件引入到项目文件中,必须先引入plupload.full.min.js

    <script type="text/javascript" src="js/plupload.full.min.js"></script>
    <script type="text/javascript" src="js/ks3jssdk.min.js"></script>
  1. 运行
var ks3Options = {
    KSSAccessKeyId: "Your KSSAccessKeyId",
    policy: "Your policy",
    signature: "Your signature",
    bucket_name: "Your bucket name",
    key: '${filename}',
    acl:"private", //此处需要与policy中的acl值保持一致,默认值:private。
    uploadDomain: "http://ks3-cn-beijing.ksyuncs.com/destination", //北京region
    autoStart: false
};
var pluploadOptions = {
    drop_element: document.body
};
var tempUpload = new ks3FileUploader(ks3Options, pluploadOptions);
document.getElementById('start-upload').onclick = function (){
        tempUpload.uploader.start()
};

4、SDK 详细介绍

构造函数

初始化一个 ks3FileUploader 实例:new ks3FileUploader(ks3PostOptions, pluploadOptions);

参数
  • ks3PostOptions, 金山云存储上传需要的配置参数:

    • KSSAccessKeyId: AccessKey

    • policy: 请求中用于描述获准行为的安全策略。没有安全策略的请求被认为是匿名请求,只能访问公共可写空间。详见:Policy、Signature构建方法

    • signature: 根据Access Key Secret和policy计算的签名信息,KS3验证该签名信息从而验证该Post请求的合法性。详见:Policy、Signature构建方法

    • bucket_name: 上传的空间名

    • key: 被上传键值的名称。如果用户想要使用文件名作为键值,可以使用${filename} 变量。例如:如果用户想要上传文件local.jpg,需要指明specify /user/betty/${filename},那么键值就会为/user/betty/local.jpg。

    • acl: 上传文件访问权限,有效值: private | public-read

    • uploadDomain: 上传域名,http://destination-bucket.endpoint或者 http://endpoint/destination-bucket, endpoint命名规范参见:https://docs.ksyun.com/documents/6761

    • autoStart: 是否在文件添加完毕后自动上传,默认为false

    • onInitCallBack: function(){}, //上传初始化时调用的回调函数

    • onErrorCallBack: function(){}, //发生错误时调用的回调函数

    • onFilesAddedCallBack: function(){}, //文件添加到浏览器时调用的回调函数

    • onBeforeUploadCallBack: function(){}, //文件上传之前时调用的回调函数

    • onStartUploadFileCallBack: function(){}, //文件开始上传时调用的回调函数

    • onUploadProgressCallBack: function(){}, //上传进度时调用的回调函数

    • onFileUploadedCallBack: function(){}, //文件上传完成时调用的回调函数

    • onUploadCompleteCallBack: function(){} //所有上传完成时调用的回调函数

  • pluploadOptions, plupload上传插件需要的配置参数:

    • runtimes: 默认值为:"html5,flash,silverlight,html4",上传模式,上传器将会依次采用能够工作的模式运行

    • browse_button: 默认为'browse', 触发对话框的DOM元素自身或者其ID

    • url: 上传地址,默认为 ks3PostOptions.uploadDomain

    • flash_swf_url : 默认为'js/Moxie.swf', Flash组件的相对路径,请根据该组件在实际项目中的位置修改

    • silverlight_xap_url : 默认为'js/Moxie.xap', Silverlight组件的相对路径,同flash_swf_url;

      5、属性

uploader:返回一个 plupload 插件的 Uploader 对象。 欲查看更多关于plupload的信息,参见:https://www.plupload.com/docs/

5.1 方法概览

注意: Object提供的方法默认使用http协议,如果需要使用https,请在应用时首先重置协议: Ks3.config.protocol = ‘https’;

5.2 详情介绍

1.List-Objects

枚举bucket中的object【Ks3.listObject(params, cb)】;
参数说明

  • params: object对象,包含:
    • Bucket: 需要获取object列表的bucketName
    • delimiter: 是用来对Object名字进行分组的一个字符,不能为空字符串
    • maker: 指定需要列出object的开始位置
    • max-keys: 返回的object的数量,默认是1000
    • prefix: 限定返回object的前缀
  • cb: 回调函数,创建成功与否都会调用此方法。参见回调函数说明

2.Delete Object

删除指定Object 【Ks3.delObject(params, cb)】;
参数说明

  • params: object对象,包含:
    • Bucket: 需要删除的object所在的bucketName
    • Key: object key
  • cb: 回调函数,创建成功与否都会调用此方法。参见回调函数说明

3.Get Object

获取指定Object 【Ks3.getObject(params, cb)】;
参数说明

  • params: object对象,包含:
    • Bucket: 要操作的bucketName;
    • Key: object key
    • range: 实现分块多线程下载,值为字符串,格式:range: 'bytes=x-y',x、y为整数,且y>=x
  • cb: 回调函数,创建成功与否都会调用此方法。参见回调函数说明

4.Put-Object

不超过5G的文件上传(同名Object上传,覆盖原有Object) 【Ks3.putObject(params, cb)
参数说明

  • params: object对象,包含:

    • Bucket: 要操作的bucketName;
    • Key: 上传的object的名称;
    • File: 上传的文件;
    • ProgressListener: Function 上传进度监听函数
    • ACL: 用于对象的预定义权限, 有效值:private | public-read;
  • cb: 回调函数,参见回调函数说明

5.Head Object

获取object的元数据 【Ks3.headObject()
参数说明

  • params: object对象,包含:
    • Bucket: 要操作的bucketName;
    • Key: object key;
  • cb: 回调函数,参见回调函数说明

6.Initiate Multipart Upload

初始化一个分块上传,接口返回一个upload ID,upload ID与当前分块上传的所有块相关联,在后续的请求已经上传的块、完成分块上传、取消分块上传的时候都会用到此ID。 【Ks3.multitpart_upload_init(params, cb)
参数说明

  • params: object对象,包含:
    • Bucket: 指定上传到该bucket下;
    • Key: object key
    • ACL: 上传的object的key; *cb: 回调函数,参见回调函数说明

7.Upload Part

开始执行分块上传,初始化分块上传之后调用该接口 【Ks3.upload_part(params, cb)
参数说明

  • params: object对象,包含:
    • Bucket: 指定上传到该bucket下;
    • Key: object key;
    • type: 指定Content-Type;
    • PartNumber: 分块序号;
    • UploadId: 初始化分块上传时获取的上传id;
    • body: 当前上传内容的blob对象;
  • cb: 回调函数,参见回调函数说明

    8.Complete Multipart Upload

    当分块上传完成之后,通过该接口告知服务器上传完成,并通过你提供的xml文件,进行分块组装。在xml文件中,块号必须使用升序排列。必须提供每个块的ETag值 【Ks3.upload_complete(params, cb)
    参数说明

  • params: object对象,包含:
    • Bucket: 指定上传到该bucket下;
    • Key: object key;
    • UploadId: 初始化分块上传时获取的上传id;
    • body: 指定块号(必须升序排列)和每块Etag值的xml
  • cb: 回调函数,参见回调函数说明

9.Abort Multipart Upload

取消分块上传 【Ks3.abort_multipart_upload(params, cb)
参数说明

  • params: object对象,包含:
    • Bucket: 当前正在进行分块上传的目标bucketName;
    • Key: object key;
    • uploadId: 初始化分块上传时获取的上传id;
  • cb: 回调函数,参见回调函数说明

    10.List Parts

    罗列出分块上传已经上传成功的快 【Ks3.upload_list_part(params, cb)
    参数说明

  • params: object对象,包含:
    • Bucket: 当前正在进行分块上传的目标bucketName;
    • Key: object key;
    • uploadId: 初始化分块上传时获取的上传id;
  • cb: 回调函数,参见回调函数说明

6、FAQ

  1. 请给我一份适用于KS3 Javascript SDK policy文件示例:

答:

{
    "expiration": "2015-12-02T10:57:30.000Z",
    "conditions": [{
            "acl": "public-read"
        }, {
            "bucket": "test"
        }, {
            "key": "cloud/img/201512/ab1c145071ef03e90383ea5db4039e5d.png"
        },
        ["starts-with", "$name", ""],
    ]
}
  1. 如何在初始化 ks3FileUploader 实例后更改acl, key, signature,policy等选项?

答:

//tempUpload 为 ks3FileUploader 实例
tempUpload.uploader.setOption("multipart_params", {
                "key": your.key,
                "acl": your.acl,
                "signature" : your.signature,
                "KSSAccessKeyId": your.KSSAccessKeyId,
                "policy": your.policy
            })
  1. 上传时返回403,该怎么办?

答:请做如下调试:

(1) 检查 KSSAccessKeyId 是否填写正确;

(2) 检查 policy 是否正确;

比如:在policy中定义的 acl 是 "public-read", 那么在表单项中的acl也必须是 "public-read".

以chrome浏览器控制台为例,参见下图:

示例图片

  1. 我想在上传之前计算图片MD5, 该怎么做?

答: 下载第三方适用于javascript MD5库,比如:https://github.com/brix/crypto-js

在文件上传之前,计算MD5, 比如:在文件添加之后:

    onFilesAddedCallBack: function(uploader, obj){
        var reader = new FileReader();
        reader.readAsBinaryString(obj[0].getSource().getSource())

        reader.onload = function(){
            console.log(CryptoJS.MD5(reader.result).toString())
        }
    }
  1. 为什么 onUploadProgressCallBack 中没有返回进度?

答: 在不支持HTML5的浏览器中,没有进度返回。 只能在 onErrorCallBack 回调中得到上传完成信号。

  1. 在使用js sdk上传文件时,为什么无法获得ETag响应头?

答:需要在CORS配置里面配置Exposed Header,设定允许从应用程序进行访问的响应头部。

解决方法: 登录控制台,选择要上传文件的bucket,进入【空间设置】->【CORS配置】,设置允许跨境请求的域名(Allow Origin)、方法(Method)、请求头(Allow Header),添加Exposed Header,输入“ETag”,点击确认。

注意事项: 配置桶CORS策略后,会有2分钟缓存生效时间,不是立即生效。

7、Demo示例程序

运行示例程序demo/index.html,其中包括

  1. post方式上传文件到某个bucket中

注意:如果bucket不是公开读写的,需要先鉴权,即提供policy和signature表单域,详见JSSDK中demo/main.js

  1. 查看bucket中的文件对象(List Object),并转换成json格式

  2. 上传图片增加水印(异步数据处理示例)

注意: 由于安全性考虑,由后台程序server.js计算signature,进行鉴权并请求ks3 API

server.js为一个nodeJS web服务,启动后会监听本地的3000端口

回调参数说明

Ks3.listObject

  • Object

    Ks3.delObject

  • code: xhr status code

    Ks3.headObject

  • err: {"msg":String}, 值为null时成功
  • xhr

    Ks3.getObject

  • err: {"msg":String}, 值为null时成功
  • Blob: Blob流
  • xhr

    Ks3.putObject

  • err: {"msg":String}, 值为null时成功

    Ks3.multitpart_upload_init

  • err: {"msg":String}, 值为null时成功
  • uploadId 分块上传ID

    Ks3.upload_part

  • err: {"msg":String}, 值为null时成功
  • partNumber 本次上传PartNumber, 合并分块使用
  • etag 本次上传Etag, 合并分块使用

    Ks3.upload_list_part

  • err: {"msg":"request failed","status": xhr.status}, 值为null时成功
  • res: xhr response

    Ks3.upload_complete

  • err: {"msg":String}, 值为null时成功
  • res: xhr response

    Ks3.abort_multipart_upload

  • err: {"msg":"request failed","status": xhr.status}, 值为null时成功
  • object: {"status":xhr.status}, 值为null时失败

    8、许可协议

    www.gnu.org/licenses/gpl-2.0.html

更多详细信息,请参阅官方文档

文档导读
纯净模式常规模式

纯净模式

点击可全屏预览文档内容
文档反馈