Object tagging and lifecycle management (Node.js SDK)

How tag filters work

When you add tag conditions to a lifecycle rule, the rule applies only to objects whose tags match all specified key-value pairs exactly. If you combine a prefix with tag conditions, an object must match the prefix and every tag condition for the rule to apply.

Prerequisites

Before you begin, ensure that you have:

• An OSS bucket

• The OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables set with valid credentials

• The oss:PutBucketLifecycle permission to create lifecycle rules

• The oss:GetBucketLifecycle permission to view lifecycle rules

Create a lifecycle rule with tag conditions

The tag field in a lifecycle rule takes an array of key-value pairs. Every object that matches all tags in the array is subject to the rule.

To apply a rule only to objects under the one/ prefix that have both key1: value1 and key2: value2:

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

const client = new OSS({
  region: 'yourregion',
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  bucket: 'yourbucketname',
});

const tag = [
  { key: 'key1', value: 'value1' },
  { key: 'key2', value: 'value2' },
];

client.putBucketLifecycle('yourbucketname', [
  {
    id: 'rule1',
    prefix: 'one',       // Applies only to objects with the prefix "one"
    status: 'Enabled',
    tag,                 // AND logic: object must match both tags
    expiration: {
      days: 60,          // Delete objects 60 days after last modified
    },
    transition: {
      days: 10,          // Transition to Infrequent Access (IA) 10 days after last modified
      storageClass: 'IA',
    },
  },
]);

Retrieve tag conditions from a lifecycle rule

Use getBucketLifecycle to inspect the rules configured on a bucket. Each rule object contains a tag array if tag conditions are set.

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

const client = new OSS({
  region: 'yourregion',
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  bucket: 'yourbucketname',
});

async function getBucketLifecycle() {
  try {
    const result = await client.getBucketLifecycle('peiyu-demo-2s');

    // Iterate over each rule and print its tag conditions
    if (result.rules) {
      result.rules.forEach((rule) => {
        if (rule.tag) {
          rule.tag.forEach((tag) => {
            console.log(`key: ${tag.key}, value: ${tag.value}`);
          });
        }
      });
    }
  } catch (error) {
    console.log(error);
  }
}

getBucketLifecycle();

result.rules is an array of all lifecycle rules on the bucket. For each rule, rule.tag is an array of { key, value } objects — one entry per tag condition.

What's next

• PutBucketLifecycle — full API reference for creating and updating lifecycle rules

• GetBucketLifecycle — full API reference for retrieving lifecycle rules

• Complete Node.js SDK examples on GitHub