This topic describes how to install the OSS SDK for Node.js. Demos in documents on the Alibaba Cloud official site are based on the 6.X version of the OSS SDK for Node.js. For more information about demos based on earlier SDK versions, see documents for earlier SDK versions. To upgrade the OSS SDK for Node.js to 6.X version, see the upgrade documents.

Preparations

  • Prerequisites
    • Activated OSS service. If you have not activated or do not know about Alibaba Cloud OSS, log on to the OSS product page for more information.
    • Created an AccessKey pair that consists of an AccessKey ID and an AccessKey secret. The AccessKey pair of an Alibaba Cloud account can access all OSS API operations. We recommend that you use the AccessKey pair following the security best practices. If you deploy your service on the server, you can use a RAM user or an STS token to call API operations or perform regular operations. If you deploy your service on the client, use an STS token to call API operations. For more information, see Overview.
  • Environment

    The OSS SDK for Node.js is built based on the Node.js environment.

Usage

The OSS SDK for Node.js can be used in both synchronous and asynchronous modes.

  • Synchronous mode: The async and await methods are used to synchronize asynchronous operations.
  • Asynchronous mode: Perform asynchronous operations by using a method similar to callback. The API operation returns a Promise object for a request. The .then() method is used to process the returned result, and the .catch() method is used to handle errors.

new OSS() is used to create OSS clients in both synchronous and asynchronous modes.

The following code provides example on how to upload an object and download the object in synchronous and asynchronous modes:

  • Synchronous mode
    let client = new OSS(...);
    async function put () {
      try {
        // object indicates the name of the object uploaded to OSS. localfile indicates the local file name or path to upload.
        let r1 = await client.put('object','localfile'); 
        console.log('put success: %j', r1);
        let r2 = await client.get('object');
        console.log('get success: %j', r2);
      } catch(e) {
        console.error('error: %j', err);
      }
    }
    put();
  • Asynchronous mode
    let client = new OSS(...);
    
    // object indicates the name of the object uploaded to OSS. localfile indicates the local file name or path to upload.
    client.put('object', 'localfile').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);
    });
    					

Installation

  • Use Node.js to install the OSS SDK

    Supported Node.js version:

    Node.js 8.0.0 or later is supported. When Node.js is earlier than 8.0.0, use the 4.X version of the OSS SDK for Node.js.

    Run the following command to use npm to install the OSS SDK for Node.js:

    npm install ali-oss
    					

    The following code provides an example on how to perform dependency injection in the framework, such as Vue and React, to use the OSS SDK for Node.js:

    let OSS = require('ali-oss');
    
    let client = new OSS({
      region: '<oss region>',
      // The AccessKey pair of an Alibaba Cloud account can access all OSS API operations. We recommend that you use the AccessKey pair following the security best practices. If you deploy your service on the server, you can use a RAM user or an STS token to access OSS. If you deploy your service on the client, use an STS token to access OSS.
      accessKeyId: '<Your accessKeyId>',
      accessKeySecret: '<Your accessKeySecret>',
      bucket: '<Your bucket name>'
    });
    					
  • If network errors occur when you use npm, you can use the following npm image: cnpm.