Copy an object to change its storage class using the Node.js SDK - Object Storage Service

Object Storage Service (OSS) supports five storage classes: Standard, Infrequent Access (IA), Archive, Cold Archive, and Deep Cold Archive. Each class is designed for different data access patterns, from frequently accessed hot data to rarely accessed cold data.

Once created, an object's content cannot be modified. To change the storage class, copy the object onto itself with the x-oss-storage-class header set to the target class. The client.copy() method handles this operation.

Prerequisites

Before you begin, make sure that you have:

An OSS bucket containing at least one object
The ali-oss SDK installed (npm install ali-oss)
The OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables configured with valid credentials

Usage notes

Changing a storage class is a copy operation. OSS copies the object in place and assigns the new class.
Standard and IA objects can be converted to any other class directly.
Archive, Cold Archive, and Deep Cold Archive objects must be restored before they can be converted. Initiate a restore operation and wait for it to complete before copying with a new storage class.
Storage class transitions may affect billing. Minimum storage duration requirements apply to IA (30 days), Archive (60 days), Cold Archive (180 days), and Deep Cold Archive (180 days). Converting before the minimum duration incurs early deletion fees.

Sample code

Initialize the client

All examples on this page use the following client initialization. Replace yourregion and yourbucketname with your actual values.

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

const client = new OSS({
  // Specify the region of your bucket, such as oss-cn-hangzhou.
  region: 'yourregion',
  // Obtain credentials from environment variables.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  bucket: 'yourbucketname',
});

Change the storage class of an object

The following example converts an object to the Archive storage class. To convert to a different class, replace the x-oss-storage-class header value with the corresponding value from the table below.

async function changeStorageClass() {
  try {
    const result = await client.copy('Objectname', 'Objectname', {
      headers: { 'x-oss-storage-class': 'Archive' },
    });
    console.log('Storage class changed to Archive:', result.res.status);
  } catch (err) {
    console.error('Failed to change storage class:', err.message);
  }
}

changeStorageClass();

Storage class header values

Storage class	`x-oss-storage-class` value
Standard	`Standard`
Infrequent Access (IA)	`IA`
Archive	`Archive`
Cold Archive	`ColdArchive`
Deep Cold Archive	`DeepColdArchive`

Verify the storage class after conversion

After changing the storage class, verify the result by retrieving the object metadata:

async function verifyStorageClass() {
  try {
    const head = await client.head('Objectname');
    console.log('Current storage class:', head.res.headers['x-oss-storage-class']);
  } catch (err) {
    console.error('Failed to retrieve object metadata:', err.message);
  }
}

verifyStorageClass();

Reference

CopyObject