Object Storage Service:Data retention policies (Node.js SDK)

Policy states

A retention policy has two states that determine which operations are permitted:

Key constraint: Once locked, a policy cannot be canceled and its retention period cannot be shortened. Lock only when you are ready for full compliance enforcement.

Prerequisites

Before you begin, make sure you have:

• An OSS bucket

• The OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables set with valid access credentials

Create a data retention policy

Creates a new retention policy in InProgress state. The response includes a worm ID that you use for subsequent lock and extend operations.

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

const client = new OSS({
  // Region where the bucket is located, for example: oss-cn-hangzhou
  region: '<region-id>',
  // Read access credentials from environment variables
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  bucket: '<bucket-name>',
});

async function initiateBucketWorm() {
  // Specify the retention period in days
  const days = '<retention-days>';
  const res = await client.initiateBucketWorm('<bucket-name>', days);
  // Save the worm ID — you need it to lock or extend the policy
  console.log(res.wormId);
}

initiateBucketWorm();

Parameters:

Return value:

Cancel a data retention policy

Cancels an InProgress (unlocked) retention policy. This operation is only available before the policy is locked — locked policies cannot be canceled.

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

const client = new OSS({
  region: '<region-id>',
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  bucket: '<bucket-name>',
});

async function abortBucketWorm() {
  try {
    await client.abortBucketWorm('<bucket-name>');
    console.log('Policy canceled.');
  } catch (err) {
    console.log(err);
  }
}

abortBucketWorm();

Lock a data retention policy

Locks the retention policy, putting it into full compliance mode. Requires the worm ID returned when the policy was created.

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

const client = new OSS({
  region: '<region-id>',
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  bucket: '<bucket-name>',
});

async function completeBucketWorm() {
  try {
    await client.completeBucketWorm('<bucket-name>', '<worm-id>');
    console.log('Policy locked.');
  } catch (err) {
    console.log(err);
  }
}

completeBucketWorm();

Parameters:

Get a data retention policy

Retrieves the current retention policy, including its state and retention period.

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

const client = new OSS({
  region: '<region-id>',
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  bucket: '<bucket-name>',
});

async function getBucketWorm() {
  try {
    const res = await client.getBucketWorm('<bucket-name>');
    console.log(res.wormId);  // Policy ID
    console.log(res.state);   // "InProgress" (unlocked) or "Locked"
    console.log(res.days);    // Retention period in days
  } catch (err) {
    console.log(err);
  }
}

getBucketWorm();

Return values:

Extend the retention period

Extends the retention period of a locked policy. The new period must be longer than the current period — decreasing the retention period is not supported.

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

const client = new OSS({
  region: '<region-id>',
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  bucket: '<bucket-name>',
});

async function extendBucketWorm() {
  try {
    // The new value must be greater than the current retention period
    const res = await client.extendBucketWorm('<bucket-name>', '<worm-id>', '<new-retention-days>');
    console.log(res);
  } catch (err) {
    console.log(err);
  }
}

extendBucketWorm();

Parameters:

References

• GitHub examples — complete sample code

• InitiateBucketWorm API reference

• AbortBucketWorm API reference

• CompleteBucketWorm API reference

• GetBucketWorm API reference

• ExtendBucketWorm API reference