Initialize an OSSClient instance for OSS SDK for Node.js to connect to OSS - Object Storage Service

An OSSClient instance is the client of Object Storage Service (OSS) SDK for Node.js to manage OSS resources such as buckets and objects. When you use OSS SDK for Node.js to initiate an OSS request, you must initialize an OSSClient instance and modify the default configuration items based on your business requirements.

Create an OSSClient instance

(Recommended) Use the V4 signature algorithm

We recommend that you use the V4 signature algorithm which provides better security. In this case, you must declare authorizationV4. OSS SDK for Node.js 6.20.0 and later support V4 signatures.

The following sample code provides an example on how to use an OSS endpoint to create an OSSClient instance by using the V4 signature algorithm. If you want to use other methods to create an OSSClient instance by using the V4 signature algorithm, refer to the following sample code and change the variables:

const OSS = require('ali-oss');

const client = new OSS({
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
  region: 'yourRegion',
  authorizationV4: true,
  // Specify the name of the bucket. 
  bucket: 'yourBucketName',
});

(Not recommended) Use the V1 signature algorithm

Important

From December 1, 2024, the V1 signature algorithm of Object Storage Service (OSS) is no longer available to new customers with new UIDs. From June 1, 2025, OSS no longer updates and maintains the V1 signature algorithm, and the V1 signature algorithm is no longer available for new buckets. Upgrade V1 signatures to V4 signatures at the earliest opportunity to prevent impact on your business.

Create an OSSClient instance by using an OSS endpoint

The following sample code provides an example on how to create an OSSClient instance by using an OSS endpoint:

const OSS = require('ali-oss');

const client = new OSS({
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
  region: 'yourRegion',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Specify the name of the bucket. 
  bucket: 'yourBucketName',
});

Create an OSSClient instance by using a custom domain name

The following sample code provides an example on how to create an OSSClient instance by using a custom domain name. For more information, see Map a custom domain name to the default domain name of a bucket.

Important

If you use a custom domain name, you cannot use the client.listBuckets() method.

const OSS = require('ali-oss')

const client = new OSS({  
 // Use a custom domain name as the endpoint of a bucket to access the bucket. 
 endpoint: 'http://img.example.com', 
 // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
 accessKeyId: process.env.OSS_ACCESS_KEY_ID,
 accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
 cname: true,
 // Specify the name of the bucket. 
 bucket: 'yourBucketName',
});

Configure an OSSClient instance

When you initialize an OSSClient instance, you can specify configuration parameters based on your business requirements. For example, you can specify a request timeout period by specifying timeout or temporary access credentials by specifying stsToken. For more information about the supported configuration parameters and configuration examples, see Configuration parameters.