aliOSS

来自于:开发者立即使用

概述

aliOSS封装了阿里云OSS云储存平台的SDK,集成了文件上传、断点续传、文件下载、图片处理、新增Bucket、获取文件列表、复制文件、判断文件存在、获取文件元信息等功能;使用之前须开通阿里云OSS服务,获取 accessKeyId 和 accessKeySecret。如有任何Bug或建议,Send email to my google mail:zhengjunwhizz

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的字段。

signUrl:

  • 类型:字符串
  • 描述:(可选项)自签名URL地址,使用自签名模式时设置。该地址接收名为 content 的参数,按阿里云自签名算法返回加签后的字符串即可。

stsUrl:

  • 类型:字符串
  • 描述:(可选项)STS鉴权地址,使用STS鉴权模式时设置。该地址访问后需返回如下格式的JSON字符串(参数名称必须和下面的一致) :
    {
      "StatusCode": 200,
      "AccessKeyId":"STS.iA645eTOXEqP3cg3VeHf",
      "AccessKeySecret":"rV3VQrpFQ4BsyHSAvi5NVLpPIVffDJv4LojUBZCf",
      "Expiration":"2015-11-03T09:52:59Z",
      "SecurityToken":"CAES7QIIARKAAZPlqaN9ILiQZPS+JDkS/GSZN45RLx4YS/p3OgaUC+oJ..."
    }
    
    STS鉴权详情请参考:https://help.aliyun.com/document_detail/32046.html

callback(ret, err)

ret:

  • 类型:JSON对象
  • 内部字段:
{
    msg: "初始化成功!"      
}

err:

  • 类型:JSON对象
  • 内部字段:
{
    msg: "缺少必要参数!"         // 错误描述
}

示例代码

明文模式:

var aliOSS = api.require('aliOSS');
aliOSS.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));
});

自签名模式:

aliOSS.init({
    endpoint : "https://oss-cn-beijing.aliyuncs.com",
    signUrl : "http://localhost/aliOSS/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" 
}

更新说明:为了统一,原1.X版本返回值etag已废弃,如果您使用过旧版本的etag,请修改为新的ETag。

err:

  • 类型:JSON对象
  • 内部字段:
{
    code: 404,   //错误码,数字类型;
    msg:"错误信息描述"          
}

示例代码

var aliOSS = api.require('aliOSS');
aliOSS.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 aliOSS = api.require('aliOSS');
aliOSS.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 != "") {
            alioss.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及更高版本

getObject

下载文件,当下载图片并且传入process参数时可以处理图片。

getObject({params}, callback(ret, err))

params

objectKey:

  • 类型:字符串
  • 描述:待下载的阿里OSS文件名

saveAs:

  • 类型:字符串
  • 描述:下载到本地保存的文件名,支持fs://,cache://等文件路径协议及真实路径。

process:

  • 类型:字符串
  • 描述:(可选项)下载图片时对图片进行处理的命令。处理命令参见阿里文档:图片处理

bucketName:

  • 类型:字符串
  • 描述:(可选项)目标Bucket名称,如不设置将使用初始化时的默认Bucket。该参数用于操作多个Bucket时,动态改变目标Bucket。

verify:

  • 类型:字符串
  • 描述:(可选项)文件完整性检验,目前只支持参数CRC。

callback(ret, err)

ret:

  • 类型:JSON对象
  • 内部字段:

下载中返回下载进度

{
    oper: "progress",   //字符串
    progress: "0.05%"   //字符串
}

下载成功返回

{
       oper: "complete",   //字符串类型
    path: "/sdcard/0/a.txt",   //文件保存路径
    contentLength:456789, // 数字 ,文件字节数
    contentType:"image/jpg", 
    ETag:"fba9dede5f27731c9771645a39863328",
    lastModified:"2017/03/08 20:20:20"
}

err:

  • 类型:JSON对象
  • 内部字段:
{
    code: 500,   //错误码,数字类型
    msg:"错误描述"   
}

示例代码

var aliOSS = api.require('aliOSS');
aliOSS.getObject({
    objectKey : '5/68/10.mp4',
    saveAs : "fs://g.mp4"
}, 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);
    }
});

图片处理

var aliOSS = api.require('aliOSS');
aliOSS.getObject({
    objectKey : 'abc.jpg',
    saveAs : "fs://d.jpg",
    process:"image/resize,m_fixed,w_100,h_100"
}, 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及更高版本

getHead

获取文件元信息

getHead({params}, callback(ret, err))

params

objectKey:

  • 类型:字符串
  • 描述:阿里云OSS文件名

bucketName:

  • 类型:字符串
  • 描述:(可选项)目标Bucket名称,如不设置将使用初始化时的默认Bucket。该参数用于操作多个Bucket时,动态改变目标Bucket。

callback(ret, err)

ret:

  • 类型:JSON对象
  • 内部字段:
{
    oper: "success",   //字符串
    contentLength:456789, // 数字 ,文件字节数
    contentType:"image/jpg", 
    ETag:"fba9dede5f27731c9771645a39863328",
    lastModified:"2017/03/08 20:20:20"
}

err:

  • 类型:JSON对象
  • 内部字段:
{
    code: 500,    //错误码,数字类型;
    msg:"错误描述 "
}

示例代码

var aliOSS = api.require('aliOSS');
aliOSS.getHead({
    objectKey : '10.mp4',
}, function(ret, err) {
    alert("ret:"+JSON.stringify(ret));
    alert("err:"+JSON.stringify(err));
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

exist

判断文件是否存在于OSS服务器

exist({params}, callback(ret, err))

params

objectKey:

  • 类型:字符串
  • 描述:阿里云OSS文件名

bucketName:

  • 类型:字符串
  • 描述:(可选项)目标Bucket名称,如不设置将使用初始化时的默认Bucket。该参数用于操作多个Bucket时,动态改变目标Bucket。

callback(ret, err)

ret:

  • 类型:JSON对象
  • 内部字段:
{
    oper: "success",   //字符串
    exist: true // Boolean 存在为true 不存在为false

}

err:

  • 类型:JSON对象
  • 内部字段:
{
    code: 500,    //错误码,数字类型;
    msg: "错误描述 "
}

示例代码

var aliOSS = api.require('aliOSS');
aliOSS.exist({
    objectKey : '10.mp4',
}, function(ret, err) {
    alert("ret:"+JSON.stringify(ret));
    alert("err:"+JSON.stringify(err));
});

可用性

iOS系统,Android系统

可提供的2.0.0及更高版本

delete

删除OSS服务器中的文件,要求对Bucket有写权限。注:删除时并不会对文件存在与否进行检测,即文件不存在于OSS服务器中也会返回成功。

delete({params}, callback(ret, err))

params

objectKey:

  • 类型:字符串
  • 描述:阿里云OSS文件名

bucketName:

  • 类型:字符串
  • 描述:(可选项)目标Bucket名称,如不设置将使用初始化时的默认Bucket。该参数用于操作多个Bucket时,动态改变目标Bucket。

callback(ret, err)

ret:

  • 类型:JSON对象
  • 内部字段:
{
    oper: "success",   //字符串
    deleted: true // Boolean 成功为true 不成功为false

}

err:

  • 类型:JSON对象
  • 内部字段:
{
    code: 500,    //错误码,数字类型;
    msg: "错误描述 "
}

示例代码

var aliOSS = api.require('aliOSS');
aliOSS.delete({
    objectKey : '10.mp4',
}, function(ret, err) {
    alert("ret:"+JSON.stringify(ret));
    alert("err:"+JSON.stringify(err));
});

可用性

iOS系统,Android系统

可提供的2.0.0及更高版本

listObjects

获取OSS服务器中的文件列表。

listObjects({params}, callback(ret, err))

params

prefix:

  • 类型:字符串
  • 描述:(可选项)文件名前辍,即以该参数开始的文件才会被返回。设置后可以用于获取某个目录下的文件。注:返回的文件名仍然包含该前辍。

maxKeys:

  • 类型:数字
  • 描述:(可选项)文件最大数量限制。默认为100,阿里限制不能超过1000。

marker:

  • 类型:字符串
  • 描述:(可选项)获取文件列表时的起始偏移位置。该参数的值由第一次使用该方法后返回,通过循环调用该接口并设置此参数,可实现分页。

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 aliOSS = api.require('aliOSS');
aliOSS.listObjects({
    prefix : 'pic/',
}, function(ret, err) {
    alert("ret:"+JSON.stringify(ret));
    alert("err:"+JSON.stringify(err));
});

可用性

iOS系统,Android系统

可提供的2.0.0及更高版本

copy

复制OSS服务器内文件。不能复制超过1G的文件,不能在不同数据中心间复制。

copy({params}, callback(ret, err))

params

bucketName:

  • 类型:字符串
  • 描述:(可选项)源Bucket名称。默认为接口初始化时的Bucket。

objectKey:

  • 类型:字符串
  • 描述:源文件。

toBucketName:

  • 类型:字符串
  • 描述:(可选项)目标Bucket名称。默认和源Bucket相同。

toObjectKey:

  • 类型:字符串
  • 描述:复制后保存的文件名。

callback(ret, err)

ret:

  • 类型:JSON对象
  • 内部字段:
{
    oper: "success",   //字符串
     result: true //Boolean

}

err:

  • 类型:JSON对象
  • 内部字段:
{
    code: 500,    //错误码,数字类型;
    msg: "错误描述 "
}

示例代码

var aliOSS = api.require('aliOSS');
aliOSS.copy({
    toBucketName:"wiz-alioss1",
    objectKey:"pic.jpg",
    toObjectKey:"copied.jpg"
}, function(ret, err) {
    alert("ret:"+JSON.stringify(ret));
    alert("err:"+JSON.stringify(err));
});

可用性

iOS系统,Android系统

可提供的2.0.0及更高版本

createBucket

新建Bucket,需要相应权限。

copy({params}, callback(ret, err))

params

bucketName:

  • 类型:字符串
  • 描述:新建Bucket名称。名称需要符合阿里云规范,否则返回异常。

callback(ret, err)

ret:

  • 类型:JSON对象
  • 内部字段:
{
    oper: "success",   //字符串
     result: true //Boolean

}

err:

  • 类型:JSON对象
  • 内部字段:
{
    code: 500,    //错误码,数字类型;
    msg: "错误描述 "
}

示例代码

var aliOSS = api.require('aliOSS');
aliOSS.createBucket({
    bucketName:"wiz-alioss1"
}, function(ret, err) 
    alert("ret:"+JSON.stringify(ret))
    alert("err:"+JSON.stringify(err))
})

可用性

iOS系统,Android系

可提供的2.0.0及更高版