aliyunOSS

来自于:开发者立即使用

概述

aliyunOSS封装了阿里云OSS云储存平台的SDK,集成了异步上传,追加上传,断点续传三种上传方式;异步下载、图片处理功能;使用之前须开通阿里云OSS服务,获取 accessKeyId 和 accessKeySecret。本文档假设您已经开通了阿里云OSS 服务,并创建了AccessKeyId 和AccessKeySecret。

环境要求

1.iOS系统版本:iOS 7.0及以上

2.必须注册有Aliyun.com用户账户,并开通OSS服务。

  1. Android 自签名模式说明,当配置serverUrl时使用自签名,serverUrl为开发者自己业务服务器地址,模块会通过post请求该地址,并携带参数signContent,服务器拿到该参数后,通过aliyun定义的签名方式进行签名,并以文本的形式加签名字符串返回。签名方式如下:signature = "OSS " + AccessKeyId + ":" + base64(hmac-sha1(AccessKeySecret, content)),详情点击这里

模块接口

initOSSClient

初始化sdk

初始化,支持明文模式和自签名模式 。移动终端是一个不受信任的环境,如果把AccessKeyId和AccessKeySecret直接保存在终端本地用来加签请求,存在极高的风险。明文模式鉴权必须设置accessKeyId和accessKeySecret,此方式建议只在测试时使用。正式环境请使用自签名模式,此模式serverUrl为必须。

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

params

accessKeyId:

  • 类型:字符串
  • 描述:(可选项)从阿里云获取的accessKeyId

accessKeySecret:

  • 类型:字符串
  • 描述:(可选项)从阿里云获取的accessKeySecret

endpoint:

serverUrl:

callback(ret)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
     status : true    //布尔类型;表示是否初始化成功     
}

示例代码

明文模式:

var aliyunOSS = api.require('aliyunOSS');
aliyunOSS.initOSSClient({
    endpoint : 'https://oss-cn-hangzhou.aliyuncs.com',
    accessKeyId : 'your accessKeyId',
    accessKeySecret:"your accessKeySecret",
},function(ret,err){
  if(ret){
        alert(JSON.stringify(ret));
    }
});

自签名模式:

var aliyunOSS = api.require('aliyunOSS');
aliyunOSS.initOSSClient({
    endpoint : "https://oss-cn-hangzhou.aliyuncs.com",
    serverUrl : "https://localhost:8080/distribute-token.json",
},function(ret,err){
       if(ret){
        alert(JSON.stringify(ret));
    }
    else{
        alert(JSON.stringify(err));
    }
});

可用性

Android系统

可提供的1.0.0及更高版本

upload

文件上传, 通过NSURL上传一个文件

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

params

bucketName:

  • 类型:字符串
  • 描述:Bucket名称。

objectKey:

  • 类型:字符串
  • 注意:路径默认是”根目录”,不需要以’/‘开头。
  • 描述:Object名称。如:"folder/subfolder/file"

file:

  • 类型:字符串
  • 描述:要上传的文件,支持fs://、cache://等文件路径协议及真实路径。

uploadType:

  • 类型:数字
  • 描述:上传文件的类型,1为异步上传,2为追加上传,3为断点续传(Android仅支持异步上传)
  • 默认:1

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    oper: 'complete',        // 上传完成,字符串类型
    requestId:'requestId',   // x-oss-request-id是由Aliyun OSS创建,并唯一标识这个response的UUID。如果在使用OSS服务时遇到问题,可以凭借该字段联系OSS工作人员,快速定位问题。字符串类型
    etag:'etag'              // ETag (entity tag) 在每个Object生成的时候被创建,用于标示一个Object的内容。
 对于Put Object请求创建的Object,ETag值是其内容的MD5值;对于其他方式创建的Object,ETag值是其内容的UUID。
 ETag值可以用于检查Object内容是否发生变化。字符串类型
}

err:

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

示例代码

var aliyunOSS = api.require('aliyunOSS');
aliyunOSS.upload({
    file : "fs://a.jpg",
    bucketName : "iOS_test",
    objectKey : "example.png",
    uploadType :1,
}, function(ret, err) {
    if(ret){
        alert(JSON.stringify(ret));
    }
    else{
        alert(JSON.stringify(err));
    }
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

download

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

OSS图片处理提供以下功能:

  • 获取图片信息
  • 图片格式转换
  • 图片缩放、裁剪、旋转
  • 图片效果
  • 图片添加图片、文字、图文混合水印
  • 自定义图片处理样式,在控制台的 图片处理 -> 样式管理 中定义
  • 通过级联处理调用多个图片处理功能

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

params

bucketName:

  • 类型:字符串
  • 描述:Bucket名称。

objectKey:

  • 类型:字符串
  • 描述:待下载的阿里OSS文件名,"folder/subfolder/file"

process:

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

saveFileName:

  • 类型:字符串
  • 描述:下载文件路径(仅支持 fs://)

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    oper: 'complete',          //字符串类型;下载成功
    path: '/sdcard/0/a.txt',   //字符串类型;文件保存路径
    contentLength:456789,      //文件字节数
}

err:

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

示例代码

var aliyunOSS = api.require('aliyunOSS');
aliyunOSS.download({
    bucketName:'bucketName',
    objectKey : 'example.jpg',
    process:"image/resize,m_fixed,w_100,h_100"
}, function(ret, err) {
      if(ret){
        alert(JSON.stringify(ret));
    }
    else{
        alert(JSON.stringify(err));
    }
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

deleteObject

删除单个文件,要求对所在的Bucket有写权限。

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

params

bucketName:

  • 类型:字符串
  • 描述:Bucket名称。

objectKey:

  • 类型:字符串
  • 描述:待删除的阿里OSS文件名,"folder/subfolder/file"

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
   status:true         //删除成功
}

示例代码

var aliyunOSS = api.require('aliyunOSS');
aliyunOSS.deleteObject({
    bucketName:'bucketName',
    objectKey :'example.jpg',
}, function(ret, err) {
      if(ret){
        alert(JSON.stringify(ret));
    }
    else{
        alert(JSON.stringify(err));
    }
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本