aliyunOSS

来自于：开发者立即使用

initOSSClient upload download deleteObject

概述

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 对象
  • 内部字段：
  1. {
  2.      status : true    //布尔类型；表示是否初始化成功     
  3. }

示例代码

明文模式：

  1. var aliyunOSS = api.require('aliyunOSS');
  2. aliyunOSS.initOSSClient({
  3.     endpoint : 'https://oss-cn-hangzhou.aliyuncs.com',
  4.     accessKeyId : 'your accessKeyId',
  5.     accessKeySecret:"your accessKeySecret",
  6. },function(ret,err){
  7.   if(ret){
  8.         alert(JSON.stringify(ret));
  9.     }
  10. });

自签名模式：

  1. var aliyunOSS = api.require('aliyunOSS');
  2. aliyunOSS.initOSSClient({
  3.     endpoint : "https://oss-cn-hangzhou.aliyuncs.com",
  4.     serverUrl : "https://localhost:8080/distribute-token.json",
  5. },function(ret,err){
  6.        if(ret){
  7.         alert(JSON.stringify(ret));
  8.     }
  9.     else{
  10.         alert(JSON.stringify(err));
  11.     }
  12. });

可用性

iOS，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 对象
  • 内部字段：
  1. {
  2.     progress:100,            // 数字类型，上传进度 (ios保留两位小数点)
  3.     oper: 'complete',        // 上传完成，字符串类型
  4.     requestId:'requestId',   // x-oss-request-id是由Aliyun OSS创建，并唯一标识这个response的UUID。如果在使用OSS服务时遇到问题，可以凭借该字段联系OSS工作人员，快速定位问题。字符串类型
  5.     etag:'etag'              // ETag (entity tag) 在每个Object生成的时候被创建，用于标示一个Object的内容。
  6.  对于Put Object请求创建的Object，ETag值是其内容的MD5值；对于其他方式创建的Object，ETag值是其内容的UUID。
  7.  ETag值可以用于检查Object内容是否发生变化。字符串类型
  8. }

err：

  • 类型：JSON对象
  • 内部字段：
  1. {
  2.     code: 404,       //数字类型；错误码
  3.     msg:"错误信息描述" //字符串类型；
  4. }

示例代码

  1. var aliyunOSS = api.require('aliyunOSS');
  2. aliyunOSS.upload({
  3.     file : "fs://a.jpg",
  4.     bucketName : "iOS_test",
  5.     objectKey : "example.png",
  6.     uploadType :1,
  7. }, function(ret, err) {
  8.     if(ret){
  9.         alert(JSON.stringify(ret));
  10.     }
  11.     else{
  12.         alert(JSON.stringify(err));
  13.     }
  14. });

可用性

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 对象
  • 内部字段：
  1. {
  2.     progress:10,               // 数字类型，下载进度 (ios保留两位小数点，需要console.log获取，alert会阻止程序进程) 
  3.     oper: 'complete',          //字符串类型；下载成功
  4.     path: '/sdcard/0/a.txt',   //字符串类型；文件保存路径
  5.     contentLength:456789,      //文件字节数
  6. }

err：

  • 类型：JSON对象
  • 内部字段：
  1.  {
  2.     code: 404,        //数字类型；错误码
  3.     msg:"错误信息描述"  //字符串类型；
  4.   }

示例代码

  1. var aliyunOSS = api.require('aliyunOSS');
  2. aliyunOSS.download({
  3.     bucketName:'bucketName',
  4.     objectKey : 'example.jpg',
  5.     process:"image/resize,m_fixed,w_100,h_100",
  6.     saveFileName:fs://test.jpg
  7. }, function(ret, err) {
  8.       if(ret){
  9.         console.log(JSON.stringify(ret));
  10.     }
  11.     else{
  12.         alert(JSON.stringify(err));
  13.     }
  14. });

可用性

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 对象
  • 内部字段：
  1. {
  2.    status:true         //删除成功
  3. }

示例代码

  1. var aliyunOSS = api.require('aliyunOSS');
  2. aliyunOSS.deleteObject({
  3.     bucketName:'bucketName',
  4.     objectKey :'example.jpg',
  5. }, function(ret, err) {
  6.       if(ret){
  7.         alert(JSON.stringify(ret));
  8.     }
  9.     else{
  10.         alert(JSON.stringify(err));
  11.     }
  12. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本