Object Storage Service:Manage object ACLs (Harmony SDK)

Prerequisites

Before you begin, ensure that you have:

• An OSS bucket. For region and endpoint information, see Regions and endpoints

• The RAM permissions required for each operation:

  • To set an object ACL: oss:PutObjectAcl

  • To retrieve an object ACL: oss:GetObjectAcl

  For instructions on granting these permissions, see Attach a custom policy to a RAM user

ACL types

OSS supports four ACL values for objects:

Object ACLs take precedence over bucket ACLs. For example, if an object in a private bucket has its ACL set to public-read, any user — including anonymous users — can read the object. If an object has no ACL configured, it inherits the bucket's ACL.

Set an object ACL

Use putObjectAcl to set the ACL on an object.

import Client, { EObjectAcl, RequestError } from '@aliyun/oss';

// Initialize the OSS client with STS credentials.
const client = new Client({
  // AccessKey ID obtained from Security Token Service (STS).
  accessKeyId: 'yourAccessKeyId',
  // AccessKey secret obtained from STS.
  accessKeySecret: 'yourAccessKeySecret',
  // Security token obtained from STS.
  securityToken: 'yourSecurityToken',
  // Region where the bucket is located, for example: oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
});

const bucket = 'yourBucketName';
const key = 'yourObjectName';

const putObjectAcl = async () => {
  try {
    const res = await client.putObjectAcl({
      bucket,
      key,
      acl: EObjectAcl.PRIVATE, // Set to private, public-read, public-read-write, or default.
    });

    console.log(JSON.stringify(res));
  } catch (err) {
    if (err instanceof RequestError) {
      console.log('code: ', err.code);           // Error code.
      console.log('message: ', err.message);     // Error message.
      console.log('requestId: ', err.requestId); // Request ID for troubleshooting.
      console.log('status: ', err.status);       // HTTP status code.
      console.log('ec: ', err.ec);               // EC.
    } else {
      console.log('unknown error: ', err);
    }
  }
};

putObjectAcl();

Get an object ACL

Use getObjectAcl to retrieve the current ACL of an object.

import Client, { RequestError } from '@aliyun/oss';

// Initialize the OSS client with STS credentials.
const client = new Client({
  // AccessKey ID obtained from Security Token Service (STS).
  accessKeyId: 'yourAccessKeyId',
  // AccessKey secret obtained from STS.
  accessKeySecret: 'yourAccessKeySecret',
  // Security token obtained from STS.
  securityToken: 'yourSecurityToken',
  // Region where the bucket is located, for example: oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
});

const bucket = 'yourBucketName';
const key = 'yourObjectName';

const getObjectAcl = async () => {
  try {
    const res = await client.getObjectAcl({
      bucket,
      key,
    });

    console.log(JSON.stringify(res));
  } catch (err) {
    if (err instanceof RequestError) {
      console.log('code: ', err.code);           // Error code.
      console.log('message: ', err.message);     // Error message.
      console.log('requestId: ', err.requestId); // Request ID for troubleshooting.
      console.log('status: ', err.status);       // HTTP status code.
      console.log('ec: ', err.ec);               // EC.
    } else {
      console.log('unknown error: ', err);
    }
  }
};

getObjectAcl();

Replace the following placeholders with your actual values: