How to manage the ACL of an object by using OSS SDK for Harmony - Object Storage Service

This topic describes how to manage the access control lists (ACLs) of objects by using Object Storage Service (OSS) SDK for Harmony.

Usage notes

For more information about regions and endpoints, see Regions and endpoints.
To configure the ACL for an object, you must have the oss:PutObjectAcl permission. To query the ACL of an object, you must have the oss:GetObjectAcl permission. For more information, see Attach a custom policy to a RAM user.

Types of ACLs

The following table describes the ACLs that you can configure for an object.

ACL	Description	Value
Inherited from the bucket	The ACL of the object is the same as that of the bucket in which the object is stored.	default
Private	Only the object owner and authorized users have read and write permissions on the object. Other users cannot access the object.	private
Public-read	Only the object owner and authorized users have read and write permissions on the object. Other users have only read permissions on the object. Exercise caution when you set the object ACL to this value.	public-read
Public-read-write	All users have read and write permissions on the object. Exercise caution when you set the object ACL to this value.	public-read-write

The ACL of an object takes precedence over the ACL of the bucket in which the object is stored. For example, if the ACL of an object in a private bucket is set to public-read, all users, including anonymous users, can read the object. If the ACL of an object is not configured, the ACL of the object is the same as that of the bucket in which the object is stored.

Examples

Configure the ACL for an object

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

// Create an OSSClient instance.
const client = new Client({
  // Specify the AccessKey ID obtained from Security Token Service (STS).
  accessKeyId: 'yourAccessKeyId',
  // Specify the AccessKey secret obtained from STS.
  accessKeySecret: 'yourAccessKeySecret',
  // Specify the security token obtained from STS.
  securityToken: 'yourSecurityToken',
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
});

// Specify the name of the bucket.
const bucket = 'yourBucketName';
// Specify the name of the object for which you want to configure the ACL.
const key = 'yourObjectName';

/**
 * Configure the ACL for the object. 
 * Use the putObjectAcl method to configure the ACL for the object. 
 */
const putObjectAcl = async () => {
  try {
    // Use the putObjectAcl method to configure the ACL for the object.
    const res = await client.putObjectAcl({
      bucket, // Specify the name of the bucket.
      key, // Specify the name of the object.
      acl: EObjectAcl.PRIVATE, //Set the ACL of the object to private.
    });

    // Display the result of the request.
    console.log(JSON.stringify(res));
  } catch (err) {
    // Capture exceptions during the request.
    if (err instanceof RequestError) {
      // If known types of errors exist, display information, such as the error code, error message, request ID, HTTP status code, and EC.
      console.log('code: ', err.code); // The error code.
      console.log('message: ', err.message); // The error message.
      console.log('requestId: ', err.requestId); // The request ID.
      console.log('status: ', err.status); // The HTTP status code.
      console.log('ec: ', err.ec); // The EC.
    } else {
      // Display other unknown types of errors.
      console.log('unknown error: ', err);
    }
  }
};

// Call the putObjectAcl function to configure the ACL for the object.
putObjectAcl();

Query the ACL of an object

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

// Create an OSSClient instance.
const client = new Client({
  // Specify the AccessKey ID obtained from Security Token Service (STS).
  accessKeyId: 'yourAccessKeyId',
  // Specify the AccessKey secret obtained from STS.
  accessKeySecret: 'yourAccessKeySecret',
  // Specify the security token obtained from STS.
  securityToken: 'yourSecurityToken',
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
});

// Specify the name of the bucket.
const bucket = 'yourBucketName';
// Specify the name of the object whose ACL you want to query.
const key = 'yourObjectName';

/**
 * Query the ACL of the object. 
 * Use the getObjectAcl method to query the ACL of the object. 
 */
const getObjectAcl = async () => {
  try {
    // Use the getObjectAcl method to query the ACL of the object.
    const res = await client.getObjectAcl({
      bucket, // Specify the name of the bucket.
      key, // Specify the name of the object.
    });

    // Display the ACL of the object.
    console.log(JSON.stringify(res));
  } catch (err) {
    // Capture exceptions during the request.
    if (err instanceof RequestError) {
      // If known types of errors exist, display information, such as the error code, error message, request ID, HTTP status code, and EC.
      console.log('code: ', err.code); // The error code.
      console.log('message: ', err.message); // The error message.
      console.log('requestId: ', err.requestId); // The request ID.
      console.log('status: ', err.status); // The HTTP status code.
      console.log('ec: ', err.ec); // The EC.
    } else {
      // Display other unknown types of errors.
      console.log('unknown error: ', err);
    }
  }
};

// Call the getObjectAcl function to query the ACL of the object.
getObjectAcl();