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 及更高版

是否仍需要帮助? 请保持联络!
最后更新于 2024/12/2