Object Storage Service:Initialization (Browser.js SDK)

Basic usage

Use when: Getting started or running a quick test with STS credentials.

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

const store = new OSS({
  region: 'yourRegion',
  authorizationV4: true,
  accessKeyId: 'your access key',
  accessKeySecret: 'your access secret',
  stsToken: 'yourSecurityToken',
  bucket: 'your bucket name',
});

Use an accelerated endpoint

Use when: Your users are geographically distributed and you want to reduce upload and download latency.

Two accelerated endpoints are available:

Global Accelerator: oss-accelerate.aliyuncs.com

Outside the Chinese mainland: oss-accelerate-overseas.aliyuncs.com

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

const store = new OSS({
  region: 'yourRegion',
  authorizationV4: true,
  accessKeyId: 'your access key',
  accessKeySecret: 'your access secret',
  stsToken: 'yourSecurityToken',
  bucket: 'your bucket name',
  endpoint: 'oss-accelerate.aliyuncs.com',
});

Use a custom domain name

Use when: You serve OSS content through your own domain (CNAME record pointing to OSS).

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

const store = new OSS({
  region: 'yourRegion',
  authorizationV4: true,
  accessKeyId: 'your access key',
  accessKeySecret: 'your access secret',
  stsToken: 'yourSecurityToken',
  cname: true,
  endpoint: 'your custom domain',
});

Auto-refresh an STS token

Use when: Building a long-running upload or download flow where the initial STS token may expire.

The refreshSTSToken callback fetches fresh credentials from your STS server. Set refreshSTSTokenInterval to a value less than the STS token's expiration period so credentials are refreshed before they expire.

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

const store = new OSS({
  region: 'yourRegion',
  authorizationV4: true,
  accessKeyId: 'your STS key',
  accessKeySecret: 'your STS secret',
  stsToken: 'your STS token',
  refreshSTSToken: async () => {
    const info = await fetch('you sts server');
    return {
      accessKeyId: info.accessKeyId,
      accessKeySecret: info.accessKeySecret,
      stsToken: info.stsToken,
    };
  },
  refreshSTSTokenInterval: 300000,
});

Retry a stream upload

Use when: Uploading a stream that may fail due to transient network errors. Note that putStream does not support automatic retries, so implement the retry loop manually.

for (let i = 0; i <= store.options.retryMax; i++) {
  try {
    const result = await store.putStream('<example-object>', fs.createReadStream('<example-path>'));
    console.log(result);
    break; // break if success
  } catch (e) {
    console.log(e);
  }
}

Use V4 signature with additional headers

Use when: Your request includes custom headers that must be covered by the V4 signature (for example, to prevent request tampering).

Specify the header keys in additionalHeaders. These keys must also appear in the actual request headers.

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

const store = new OSS({
  accessKeyId: 'your access key',
  accessKeySecret: 'your access secret',
  bucket: 'your bucket name',
  region: 'oss-cn-hangzhou',
  authorizationV4: true,
  stsToken: 'yourSecurityToken',
});

try {
  const bucketInfo = await store.getBucketInfo('your bucket name');
  console.log(bucketInfo);
} catch (e) {
  console.log(e);
}

try {
  const putObjectResult = await store.put('your bucket name', 'your object name', {
    headers: {
      // The headers of this request
      header1: 'value1',
      header2: 'value2',
    },
    // The keys of the request headers to include in the V4 signature calculation. Ensure that these additional headers are included in the request headers.
    additionalHeaders: ['additional header1', 'additional header2'],
  });
  console.log(putObjectResult);
} catch (e) {
  console.log(e);
}