OSS Browser.js SDK的安装。

下载SDK

目前官网文档中的demo都是基于SDK 6.X,版本低于6.X的可参考 5.X开发文档, 升级6.X请移步升级文档

环境准备

  • 要求
    • 开通阿里云OSS服务,如果您还不了解阿里云OSS服务,请登录 OSS产品主页了解。详情请参见产品介绍
    • 创建AccessKeyId和AccessKeySecret,由于云账号AccessKey有所有API访问权限,建议遵循阿里云安全最佳实践。如果部署在服务端可以使用RAM子账号或STS来进行API访问或日常运维管控操作,如果部署在客户端请使用STS方式来进行API访问。详情请参见访问控制。
  • 环境要求

    OSS BrowserJS-SDK基于Node.js环境构建,通过BrowserifyBabel产生适用于浏览器的代码。

    但是由于浏览器环境的特殊性,有一些功能无法使用:

    • 流式上传:浏览器中无法设置chunked编码,用分片上传替代
    • 操作本地文件:浏览器中不能直接操作本地文件系统,用签名URL的方式下载
    • Bucket相关的操作(listBuckets/BucketACL/BucketLogging等),由于OSS暂时不支持Bucket相关的跨域请求,Bucket相关的操作可以在控制台进行

使用方式

OSS BrowserJS-SDK同时支持同步和异步的使用方式

  • 同步方式:基于ES7规范的async/await,使得异步方式同步化

  • 异步方式:类似callback的方式,API接口返回Promise,使用.then()处理返回结果,使用.catch()处理错误

无论同步方式还是异步方式,均使用new OSS()创建client。

下面分别举例,先上传一个文件,然后立即下载这个文件:

  • 同步方式
    // 实例化OSS Client,具体的参数可参文档配置项
    let client = new OSS(...);
    
    async function put () {
      try {
        // object表示上传到OSS的名字,可自己定义
        // file浏览器中需要上传的文件,支持HTML5 file 和 Blob类型
        let r1 = await client.put('object', file);
        console.log('put success: %j', r1);
        let r2 = await client.get('object');
        console.log('get success: %j', r2);
      } catch (e) {
        console.error('error: %j', e);
      }
    }
    
    put();
    
  • 异步方式
    // 实例化OSS Client,具体的参数可参文档配置项
    let client = new OSS(...);
    
    // object表示上传到OSS的名字,可自己定义
    // file浏览器中需要上传的文件,支持HTML5 file 和 Blob类型
    client.put('object', file).then(function (r1) {
      console.log('put success: %j', r1);
      return client.get('object');
    }).then(function (r2) {
      console.log('get success: %j', r2);
    }).catch(function (err) {
      console.error('error: %j', err);
    });
    

安装

  • 在浏览器中使用

    支持的浏览器:

    • IE(>=10)和Edge
    • 主流版本的Chrome/Firefox/Safari
    • 主流版本的Android/iOS/WindowsPhone

    Browser.js SDK 的安装方式有以下几种。

    • 浏览器引入:
      注意 因为部分浏览器不支持promise,需要引入promise兼容库。 例如:IE10和IE11 需要引入promise-polyfill。
      <!-- 引入在线资源 -->
      <script src="http://gosspublic.alicdn.com/aliyun-oss-sdk-x.x.x.min.js"></script>
      
      <!-- 引入本地资源 -->
      <script src="./aliyun-oss-sdk-x.x.x.min.js"></script>
      
      说明
      • x.x.x代表版本号,具体版本信息可在这访问查看
      • 引入在线资源方式依赖于CDN服务器的稳定性,推荐用户使用离线方式引入,即通过本地资源或自行构建的方式。

      就可以在代码中使用OSS对象:

      <script type="text/javascript">
        let client = new OSS({
          region: '<oss region>',
      	//云账号AccessKey有所有API访问权限,建议遵循阿里云安全最佳实践,创建并使用STS方式来进行API访问
          accessKeyId: '<Your accessKeyId(STS)>',
          accessKeySecret: '<Your accessKeySecret(STS)>',
          stsToken: '<Your securityToken(STS)>',
          bucket: '<Your bucket name>'
        });
      </script>
      
    • 使用npm安装SDK的开发包:
      npm install ali-oss
      

      成功安装完成之后,即可使用 import 或 require 进行引用。由于浏览器中原生是不支持require这种模式的,因此需要在开发环境中配合相关的打包工具,比如webpackbrowserify等。

      let OSS = require('ali-oss');
      
      let client = new OSS({
        region: '<oss region>',
        //云账号AccessKey有所有API访问权限,建议遵循阿里云安全最佳实践,部署在服务端使用RAM子账号或STS,部署在客户端使用STS。
        accessKeyId: '<Your accessKeyId>',
        accessKeySecret: '<Your accessKeySecret>',
        bucket: '<Your bucket name>'
      });
      
    • 使用Bower

      对于Web项目,你也可以通过Bower安装SDK:

      bower install ali-oss
      

      然后在网页中添加<script>标签:

      <script src="bower_components/ali-oss/dist/aliyun-oss-sdk.min.js"></script>