Object Storage Service:FAQ (Node.js SDK)

Why does my request return "The region must be conform to the specifications"?

The Region parameter value is invalid. Verify that the region ID is correct and matches a supported OSS region. For a full list of valid region IDs, see Regions and endpoints.

How do I enable HTTPS?

Set secure to true when initializing the client:

const client = new OSS({
  secure: true,
  // ... other options
});

How do I track upload progress?

Pass a progress callback to multipartUpload. For a complete example, see Multipart upload.

How do I upload a Base64-encoded image?

Convert the Base64 string to a File object, then pass it to multipartUpload:

function dataURLtoFile(dataurl, filename) {
  let arr = dataurl.split(','), mime = arr[0].match(/:(.*?);/)[1],
    bstr = atob(arr[1]), n = bstr.length, u8arr = new Uint8Array(n);
  while(n--){
    u8arr[n] = bstr.charCodeAt(n);
  }
  return new File([u8arr], filename, {type:mime});
}

let file = dataURLtoFile('base64 content', '');

client.multipartUpload('oss file name', file).then((res) => {
  console.log(res)
}).catch((err) => {
  console.log(err)
});

How do I upload an object to a specific directory?

Prefix the object name with the directory path. OSS uses object name prefixes to simulate directories — there are no actual directories in OSS. For background, see Comparison between OSS and file systems.

const OSS = require("ali-oss");
const client = new OSS({
  // Specify the region where the bucket is located. For example, set the region to oss-cn-hangzhou for the China (Hangzhou) region.
  region: 'yourregion',
  // Obtain access credentials from environment variables. Before you run this sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Specify the bucket name.
  bucket: 'yourbucketname'
});

client
  .multipartUpload("base-dir/" + "object-name", "local-file", {
    progress: async function (p) {
      console.log("Progress: " + p);
    },
  })
  .then((result) => {
    console.log(result);
  })
  .then((res) => {
    console.log(res);
  })
  .catch((err) => {
    console.log(err)
  });

How do I generate a signed URL for uploading?

The answer depends on the HTTP method you use:

How do I track download progress?

You can calculate the progress in OSS SDK for Node.js based on the size of the download traffic.

How do I get the signed URL of an object?

Call signatureUrl on the client. For usage details and options, see the GitHub example.

Note: Treat signed URLs as bearer tokens. Anyone with the URL can access the object until it expires. Share signed URLs only with intended recipients, and use short expiration times for sensitive operations.

Download fails with "Response timeout for 60000ms, please increase the timeout or use multipartDownload"

This error occurs when downloading objects larger than 1 GB. The default download timeout is 60,000 ms.

To resolve the issue, use one or both of the following approaches:

1. Switch to streaming download (recommended). Streaming download transfers the object in increments instead of buffering the entire response in memory, which avoids timeouts on large objects. See Streaming download.

2. Increase the timeout value. If streaming download still times out on a slow connection, increase the timeout value in the client configuration. See Parameters for all configurable options.