aliOSSLite
概述
aliOSSLite 封装了阿里云 OSS 云储存平台的 SDK，集成了文件上传、断点续传、获取文件列表等功能；使用之前须开通阿里云 OSS 服务，获取 accessKeyId 和 accessKeySecret。如有任何 Bug 、建议或使用方面的问题，欢迎邮我 jarviszheng(at)qq.com 。 使用示例 Demo 帖
init
初始化 调用其它接口之前必须先初始化，支持明文模式、自签名模式、STS鉴权模式 ，明文模式鉴权必须设置 accessKeyId 和 accessKeySecret，此方式建议只在本地测试时使用，正式环境请使用自签名模式或 STS 鉴权模式。
自签名和 STS 鉴权模式阿里云设置步骤：
登录阿里云服务器管理控制台，开通访问控制 RAM
自签名:用户管理新建用户，并授权 AliyunOSSFullAccess 权限, 记录 AccessKey 和 secret
STS 鉴权:在自签名基础上，用户管理授权 AliyunSTSAssumeRoleAccess 权限，角色管理新建角色 ，授权 AliyunOSSFullAccess 权限
授权示例代码
init({params},callback(ret, err))
params
accessKeyId：
- 类型：字符串
- 描述：（可选项）从阿里云获取的 accessKeyId
accessKeySecret：
- 类型：字符串
- 描述：（可选项）从阿里云获取的 accessKeySecret
endpoint：
- 类型：字符串
- 描述：OSS 区域地址，如：
https://oss-cn-beijing.aliyuncs.com
bucketName：
- 类型：字符串
- 描述：Bucket 名称，该参数设置默认操作的 Bucket。如您有多个 Bucket 要操作，使用其它方法时有参数可动态改变 Bucket。
params：
- 类型：json
- 描述：（可选项）自签名/STS 鉴权模式时向 signUrl/stsUrl 发送（POST 方式）的自定义数据，注：只支持一级 JSON，并且不能包含键为 content 的字段。
headers：
- 类型：json
- 描述：（可选项）自签名/STS 鉴权模式时向 signUrl/stsUrl 发送（POST 方式）的自定义头信息。
timeout：
- 类型：整型
- 描述：（可选项）连接超时，默认 15 秒
socketTimeout：
- 类型：整型
- 描述：（可选项）传输文件最大允许时间，默认 15 秒
concurrent：
- 类型：整型
- 描述：（可选项）最大并发请求数，默认 5 个
retry：
- 类型：整型
- 描述：（可选项）失败后最大重试次数，默认 2 次
signUrl：
- 类型：字符串
- 描述：（可选项）自签名 URL 地址，POST 请求，使用自签名模式时设置。该地址接收名为 content 的参数，按阿里云自签名算法返回加签后的字符串即可。 形如：
OSS LTAIkdm8dtCB1v0c:rGBQZQC2C+elImt+7sja+nh9rZg=
stsUrl：
- 类型：字符串
- 描述：（可选项）STS 鉴权地址，POST 请求，使用 STS 鉴权模式时设置。该地址访问后需返回如下格式的 JSON 字符串（参数名称必须和下面的一致） ：
{
"StatusCode": 200,
"AccessKeyId":"STS.iA645eTOXEqP3cg3VeHf",
"AccessKeySecret":"rV3VQrpFQ4BsyHSAvi5NVLpPIVffDJv4LojUBZCf",
"Expiration":"2015-11-03T09:52:59Z",
"SecurityToken":"CAES7QIIARKAAZPlqaN9ILiQZPS+JDk..."
}
STS 鉴权详情请参考：https://help.aliyun.com/document_detail/32046.html
callback(ret, err)
ret：
- 类型：JSON 对象
- 内部字段：
{
msg: "初始化成功！";
}
err：
- 类型：JSON 对象
- 内部字段：
{
msg: "缺少必要参数！"; // 错误描述
}
示例代码
明文模式：
var aliOSSLite = api.require("aliOSSLite");
aliOSSLite.init(
{
endpoint: "https://oss-cn-beijing.aliyuncs.com",
accessKeyId: "YOUR ACCESS KEY ID",
accessKeySecret: "YOUR ACCESS KEY SECRET",
bucketName: "YOUR BUCKET NAME",
},
function (ret, err) {
alert(JSON.stringify(ret));
alert(JSON.stringify(err));
}
);
自签名模式：
aliOSSLite.init(
{
endpoint: "https://oss-cn-beijing.aliyuncs.com",
signUrl: "http://localhost/aliOSSLite/sign.php",
bucketName: "YOUR BUCKET NAME",
},
function (ret, err) {
alert(JSON.stringify(ret));
alert(JSON.stringify(err));
}
);
自签名 sign.php 只需要返回签名字符串即可，具体加密方式参见 阿里云文档签名算法.
PHP 代码（其它语言同理，只需要返回【"OSS " + AccessKeyId + ":" + 加密字符串】该字符串即可）：
$AccessKeyId="YOUR ACCESS KEY ID";
$AccessKeySecret="YOUR ACCESS KEY SECRET";
// content 参数由插件自动拼装发送（POST）给服务端，服务端只需按名称（content）获取该值参与加密即可。
$content=$_REQUEST['content'];
// 将获取的 content 以 AccessKeySecret作为加密KEY， 先经过hmac-sha1加密再 base64 编码后获取签名
$sign=base64_encode(hash_hmac('sha1',$content,$AccessKeySecret,true));
echo "OSS " . $AccessKeyId . ":" . $sign; // 按阿里云规则返回签名字符串
可用性
iOS 系统，Android 系统
可提供的 1.0.0 及更高版本
upload
文件上传
upload({params}, callback(ret, err))
params
file：
- 类型：字符串
- 描述：要上传的文件，支持 fs://、cache://等文件路径协议及真实路径。
name：
- 类型：字符串
- 描述：上传 OSS 后保存的文件名
bucketName：
- 类型：字符串
- 描述：（可选项）上传至的 Bucket 名称，如不设置将使用初始化时的默认 Bucket。该参数用于操作多个 Bucket 时，动态改变目标 Bucket。
verify：
- 类型：字符串
- 描述：（可选项）文件完整性检验，目前只支持参数 CRC。
callback(ret, err)
ret：
- 类型：JSON 对象
- 内部字段：
上传中返回上传进度
{
oper: "progress", //字符串
progress:"0.05%" //字符串
}
上传成功返回
{
oper: "complete", //字符串
requestId:"requestId", //字符串 具体含义参考阿里云
ETag:"etag"
}
err：
- 类型：JSON 对象
- 内部字段：
{
code: 404, //错误码，数字类型；
msg:"错误信息描述"
}
示例代码
var aliOSSLite = api.require("aliOSSLite");
aliOSSLite.upload(
{
file: "fs://a.jpg",
name: "abc.jpg",
},
function (ret, err) {
if (ret.oper == "progress") {
progress1 = $api.byId("progress1");
if (progress1) {
$api.html(progress1, ret.progress);
} else {
$api.append(document.body, '<div id="progress1">Progress</div>');
}
} else if (ret.oper == "complete") {
alert(JSON.stringify(ret));
}
if (err) {
alert(err.msg);
}
}
);
可用性
iOS 系统，Android 系统
可提供的 1.0.0 及更高版本
resumableUpload
断点续传
resumableUpload({params}, callback(ret, err))
params
file：
- 类型：字符串
- 描述：要上传的文件，支持 fs://、cache://等文件路径协议及真实路径。
name：
- 类型：字符串
- 描述：上传 OSS 后保存的文件名
bucketName：
- 类型：字符串
- 描述：（可选项）上传至的 Bucket 名称，如不设置将使用初始化时的默认 Bucket。该参数用于操作多个 Bucket 时，动态改变目标 Bucket。
verify：
- 类型：字符串
- 描述：（可选项）文件完整性检验，目前只支持参数 CRC。
callback(ret, err)
ret：
- 类型：JSON 对象
- 内部字段：
上传中返回上传进度
{
oper: "progress", //字符串
progress:"0.05%" //字符串
}
上传成功返回
{
oper: "complete", //字符串
requestId:"requestId" //字符串
}
err：
- 类型：JSON 对象
- 内部字段：
{
code: 404, //错误码，数字类型；
msg:"错误信息描述"
}
示例代码
var aliOSSLite = api.require("aliOSSLite");
aliOSSLite.resumableUpload(
{
file: "fs://a.jpg",
name: "a.jpg",
verify: "CRC",
},
function (ret, err) {
if (ret.oper == "progress") {
progress1 = $api.byId("progress1");
if (progress1) {
$api.html(progress1, ret.progress);
} else {
$api.append(document.body, '<div id="progress1">Progress</div>');
}
} else if (ret.oper == "complete") {
alert(JSON.stringify(ret));
}
if (err) {
alert(err.msg);
}
}
);
api.getPicture(
{
sourceType: "album",
mediaValue: "pic",
},
function (ret, err) {
if (ret && ret.data != "") {
aliOSSLite.upload(
{
file: ret.data, // getPicture返回的图片路径
name: "upload.jpg", // 上传至OSS的保存路径
},
function (ret2, err2) {
// alert("ret:"+JSON.stringify(ret2));
if (ret2.oper == "progress") {
$api.css(progress, "width: " + ret2.progress);
} else if (ret2.oper == "complete") {
alert(JSON.stringify(ret2));
}
if (err2) {
alert(err2.msg);
}
}
);
}
}
);
可用性
iOS 系统，Android 系统
可提供的 1.0.0 及更高版本
listObjects
获取 OSS 服务器中的文件列表。
listObjects({params}, callback(ret, err))
params
prefix：
- 类型：字符串
- 描述：（可选项）文件名前辍，即以该参数开始的文件才会被返回。设置后可以用于获取某个目录下的文件。注：返回的文件名仍然包含该前辍。
maxKeys：
- 类型：数字
- 描述：（可选项）文件最大数量限制。默认为 100，阿里限制不能超过 1000。
marker：
- 类型：字符串
- 描述：（可选项）获取文件列表时的起始偏移位置。该参数的值由第一次使用该方法后返回，通过循环调用该接口并设置此参数，可实现分页。
current：
- 类型：布尔
- 描述：（可选项）只获取请求路径下的文件及文件夹，文件夹将排在前边，其只含
key,isDir属性。
bucketName：
- 类型：字符串
- 描述：（可选项）目标 Bucket 名称，如不设置将使用初始化时的默认 Bucket。该参数用于操作多个 Bucket 时，动态改变目标 Bucket。
##callback(ret, err)
ret：
- 类型：JSON 对象
- 内部字段：
{
oper: "success", //字符串
// 返回的文件列表 JSON 数组
objects: [{
key: 'pic/', //文件名 包含前辍的完整路径
isDir: true, // 是不是文件夹
size: 99, // 文件大小
status: 'Normal' , // 文件状态
ETag:"fba9dede5f27731c9771645a39863328",
lastModified:"2018/03/08 20:20:20" // 最后修改时间
}],
length:1, // 数字 当前返回结果中包含的文件数量
marker:'pic/', // 字符串， 下次查询偏移位置，使用该值设置下次查询的marker参数，可实现分页。
}
err：
- 类型：JSON 对象
- 内部字段：
{
code: 500, //错误码，数字类型；
msg: "错误描述 "
}
示例代码
var aliOSSLite = api.require("aliOSSLite");
aliOSSLite.listObjects(
{
prefix: "pic/",
},
function (ret, err) {
alert("ret:" + JSON.stringify(ret));
alert("err:" + JSON.stringify(err));
}
);
可用性
iOS 系统，Android 系统
可提供的 2.0.0 及更高版本
url
授权第三方访问，可授权第三方访问文件。
url({params}, callback(ret, err))
params
bucketName：
- 类型：字符串
- 描述：（可选项）目标 Bucket 名称，如不设置将使用初始化时的默认 Bucket。该参数用于操作多个 Bucket 时，动态改变目标 Bucket。
objectKey：
- 类型：字符串
- 描述：要授权访问的文件。
expired：
- 类型：整型
- 描述：（可选项）链接失效时间，单位：秒，默认 3600 秒
process：
- 类型：字符串
- 描述：（可选项）文件为图片时对图片的处理（如缩放等），具体参数请参考阿里云文档。
##callback(ret, err)
ret：
- 类型：JSON 对象
- 内部字段：
{
url: "https://www....";
}
err：
- 类型：JSON 对象
- 内部字段：
{
code: 500, //错误码，数字类型；
msg: "错误描述 "
}
示例代码
var aliOSSLite = api.require("aliOSSLite");
aliOSSLite.url(
{
objectKey: "food.jpg",
process: "image/resize,w_200",
},
function (ret2, err2) {
if (ret2) {
alert(ret2.url);
}
if (err2) {
alert(err2.msg);
}
}
);
可用性
iOS 系统，Android 系统
可提供的 2.1.2 及更高版