Object Storage Service:Pay-by-requester mode (Node.js SDK)

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 Node.js OSS SDK (ali-oss) installed

Enable or disable pay-by-requester mode

Call putBucketRequestPayment with the Payer parameter set to Requester to enable pay-by-requester mode, or BucketOwner to disable it.

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

const client = new OSS({
  // Set region to the region where the bucket is located.
  // For example, if the bucket is in the China (Hangzhou) region, set region to oss-cn-hangzhou.
  region: '<your-region>',
  // Credentials are read from environment variables.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  bucket: '<your-bucket-name>',
});

async function setBucketRequestPayment(bucket, payer) {
  try {
    // Payer values:
    // 'Requester'   - enables pay-by-requester mode; the requester pays traffic and request fees.
    // 'BucketOwner' - disables pay-by-requester mode (default); the bucket owner pays all fees.
    const result = await client.putBucketRequestPayment(bucket, payer);
    console.log(result);
  } catch (e) {
    console.log(e);
  }
}

setBucketRequestPayment('<your-bucket-name>', 'Requester');

Get the pay-by-requester mode configuration

Call getBucketRequestPayment to retrieve the current payer configuration of a bucket. The response includes a payer field with the value Requester or BucketOwner.

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

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

async function getBucketRequestPayment(bucket) {
  try {
    const result = await client.getBucketRequestPayment(bucket);
    console.log(result.payer); // 'Requester' or 'BucketOwner'
  } catch (e) {
    console.log(e);
  }
}

getBucketRequestPayment('<your-bucket-name>');

Access objects as a requester

When a bucket has pay-by-requester mode enabled, requesters must include the x-oss-request-payer: requester header in every HTTP request that reads or writes objects. Requests without this header return an error.

The following example shows how to add this header for PutObject, GetObject, and DeleteObject. The same pattern applies to other object read and write operations.

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

const bucket = '<your-bucket-name>';
const payer = 'Requester';

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

async function main() {
  await put();
  await get();
  await del();
}

async function put() {
  const result = await client.putBucketRequestPayment(bucket, payer);
  console.log('putBucketRequestPayment:', result);
  // Include x-oss-request-payer in the PutObject request.
  const response = await client.put('fileName', path.normalize('D:\\localpath\\examplefile.txt'), {
    headers: {
      'x-oss-request-payer': 'requester',
    },
  });
  console.log('put:', response);
}

async function get() {
  const result = await client.putBucketRequestPayment(bucket, payer);
  console.log('putBucketRequestPayment:', result);
  // Include x-oss-request-payer in the GetObject request.
  const response = await client.get('fileName', {
    headers: {
      'x-oss-request-payer': 'requester',
    },
  });
  console.log('get:', response);
}

async function del() {
  const result = await client.putBucketRequestPayment(bucket, payer);
  console.log('putBucketRequestPayment:', result);
  // Include x-oss-request-payer in the DeleteObject request.
  const response = await client.delete('fileName', {
    headers: {
      'x-oss-request-payer': 'requester',
    },
  });
  console.log('delete:', response);
}

main();

What's next

• For the complete sample code, see GitHub examples.

• For the PutBucketRequestPayment API reference, see PutBucketRequestPayment.

• For the GetBucketRequestPayment API reference, see GetBucketRequestPayment.