Installation

Last Updated: Oct 13, 2017

Install the SDK

Prerequisites

  • Activate OSS service.

    If you haven’t activated or do not know about Alibaba Cloud OSS, log on to the OSS product page for details.

  • Create AccessKeyId and AccessKeySecret.

    The Alibaba Cloud account AccessKey gives you permission to access all APIs, thus, we recommend that you follow Alibaba Cloud Best Practices for creating an AccessKeyId and an AccessKeySecret. If you deploy the service on the server, you can use an RAM sub-account or STS for API access or daily O&M management and control. If you deploy the service on the client, we recommend that you use STS for API access. For specific descriptions, see Access control.

Environment requirement

The OSS JavaScript SDK is built on the Node.js environment. It generates code that adapts to the browser through Browserify and Babel. You can use the OSS JavaScript SDK in the browser and the Node.js environment.

However, because of the special natures of the browser environment, some features cannot be used:

  • Stream upload: The chunked encoding cannot be used in the browser. This feature is replaced by multipart upload.

  • Operations on the local file: You cannot directly operate on local file systems in the browser. You can download the object as a signed URL.

  • Bucket-related operations (listBuckets/BucketACL/BucketLogging). The OSS currently does not support bucket-related cross-origin requests, so bucket-related operations can be performed in the console.

Usage methods

The OSS JavaScript SDK supports both synchronous and asynchronous use.

  • Synchronous mode: Similar to the coroutine mode. co and yield are used based on Generator Function.

  • Asynchronous mode: Similar to the callback mode. The API returns the Promise, uses the .then() method to process the returned result and uses the .catch() method to process errors.

In synchronous mode, the new OSS() method is used to create a client. In the asynchronous mode, the new OSS.Wrapper() method is used to create a client.

Next we will name examples to upload an object first and then download the object respectively.

Synchronous mode

  1. // var client = new OSS(...);
  2. var co = require('co');
  3. co(function* () {
  4. var r1 = client.put('object', '/tmp/file');
  5. console.log('put success: %j', r1);
  6. var r2 = client.get('object');
  7. console.log('get success: %j', r2);
  8. }).catch(function (err) {
  9. console.error('error: %j', err);
  10. });

Asynchronous mode

  1. // var client = new OSS.Wrapper(...);
  2. client.put('object', '/tmp/file').then(function (r1) {
  3. console.log('put success: %j', r1);
  4. return client.get('object');
  5. }).then(function (r2) {
  6. console.log('get success: %j', r2);
  7. }).catch(function (err) {
  8. console.error('error: %j', err);
  9. });

Installation

Usage in the browser

Supported browsers:

  • IE (>=10) and Edge
  • Mainstream Chrome/Firefox/Safari versions
  • Mainstream Android/iOS/WindowsPhone versions

To use the SDK in a browser, you only need to contain the following <script> tag in the webpage tag:

  1. <script src="http://gosspublic.alicdn.com/aliyun-oss-sdk-4.3.0.min.js"></script>

You will be able to use the OSS.Wrapper object in the code:

  1. <script type="text/javascript">
  2. var client = new OSS.Wrapper({
  3. region: '<oss region>',
  4. //The Alibaba Cloud account AccessKey gives you permission to access all APIs, so we suggest you follow Alibaba Cloud Best Practices for accessing an API using STS.
  5. accessKeyId: '<Your accessKeyId(STS)>',
  6. accessKeySecret: '<Your accessKeySecret(STS)>',
  7. stsToken: '<Your securityToken(STS)>',
  8. bucket: '<Your bucket name>'
  9. });
  10. </script>

Use Node.js

Supported Node.js versions:

  • 4.x
  • 5.x
  1. Use npm to install the SDK:

    1. npm install ali-oss
  2. Use it in your project:

    1. var OSS = require('ali-oss');
    2. var client = new OSS({
    3. region: '<oss region>',
    4. //The Alibaba Cloud account AccessKey gives you permission to access all APIs, so we suggest you follow Alibaba Cloud Best Practices for deploying the service on the server using an RAM sub-account or STS, or deploying the service on the client using STS.
    5. accessKeyId: '<Your accessKeyId>',
    6. accessKeySecret: '<Your accessKeySecret>',
    7. bucket: '<Your bucket name>'
    8. });

If you run into any network problems when using npm, you can use the npm image provided by Taobao: cnpm.

Use Bower

  1. For Web projects, install the SDK through Bower:

    1. bower install ali-oss
  2. Add the <script> tag in the webpage:

    1. <script src="bower_components/ali-oss/dist/aliyun-oss-sdk.min.js"></script>
Thank you! We've received your feedback.