This topic describes how to install Object Storage Service (OSS) SDK for Node.js.

Prerequisites

  • Alibaba Cloud OSS is activated.
  • The AccessKey ID and AccessKey secret of a RAM user are created.

    Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS because the account has permissions on all API operations. We recommend that you use the AccessKey pair of a RAM user. If you deploy your service on the server, you can use a RAM user or STS credentials to call API operations or perform routine operations. If you deploy your service on the client, use STS credentials to call API operations. For more information, see Resource Access Management.

Background information

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

Demos in documents on the official website are based on OSS SDK for Node.js V6.x. If your OSS SDK for Node.js version is earlier than 6.x, see 5.x. To upgrade your OSS SDK for Node.js version to 6.x, see Upgrading Notes.

For more information about the source code of OSS SDK for Node.js, see GitHub. For more information, see documents.

Install OSS SDK for Node.js

OSS supports Node.js 8.0.0 and later. To use OSS SDK for Node.js in Node.js versions earlier than 8.0.0, use OSS SDK for Node.js V4.x.

Run npm install ali-oss --save to install the SDK package. For more information, visit npm.

If you encounter network issues when you use npm, we recommend that you use cnpm, which is the npm image provided by Taobao.

Use OSS SDK for Node.js

You can use OSS SDK for Node.js in synchronous and asynchronous modes. new OSS() is used to create OSS clients in synchronous and asynchronous modes.

  • Synchronous mode: The async and await methods are used to synchronize asynchronous operations.
  • Asynchronous mode: Perform asynchronous operations in a way 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.

The following code provides examples on how to upload an object in synchronous mode and download an object in asynchronous mode:

  • Synchronous mode
    let client = new OSS(...);
    async function put () {
      try {
        // Set 'object' to the name of the object uploaded to OSS. The name cannot contain bucket names. 
        // Set 'localfile' to the full path of the local file from which the object is uploaded to OSS. 
        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', e);
      }
    }
    await put();
  • Asynchronous mode
    let client = new OSS(...);
    
    // Set 'object' to the name of the object downloaded from OSS. The name is a full path that cannot contain bucket names. 
    // Set 'localfile' to the full path of the local file to which the object is downloaded. 
    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', e);
    });