安装

下载SDK

目前官网文档中的demo都是基于SDK 6.X，版本低于6.X的可参考 5.X开发文档，如要升级至6.X请参考升级文档。

• Github地址
• API文档
• ChangeLog

环境准备

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

  OSS Browser.js SDK基于Node.js环境构建，通过Browserify和Babel产生适用于浏览器的代码。

  但是由于浏览器环境的特殊性，无法使用以下功能：

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

使用方式

OSS Browser.js SDK支持同步和异步的使用方式：

• 同步方式：基于ES7规范的async/await，使得异步方式同步化。

• 异步方式：与Callback方式类似，API接口返回Promise，使用.then()处理返回结果，使用.catch()处理错误。

以下是使用同步或者异步方式上传文件，然后下载文件的示例说明：

• 同步方式

  // 实例化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这种模式的，因此需要在开发环境中配合相关的打包工具，比如webpack、browserify等。

    let OSS = require('ali-oss');
    
    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>'
    });

  • 使用Bower：

    对于Web项目，你也可以通过Bower安装SDK：

    bower install ali-oss
    

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

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