Class Acl

Cloud Storage uses access control lists (ACLs) to manage object and bucket access. ACLs are the mechanism you use to share objects with other users and allow other users to access your buckets and objects.

An ACL consists of one or more entries, where each entry grants permissions to an entity. Permissions define the actions that can be performed against an object or bucket (for example, READ or WRITE); the entity defines who the permission applies to (for example, a specific user or group of users).

Where an entity value is accepted, we follow the format the Cloud Storage API expects.

Refer to https://cloud.google.com/storage/docs/json_api/v1/defaultObjectAccessControls for the most up-to-date values.

user-userId - user-email - group-groupId - group-email - domain-domain - project-team-projectId - allUsers - allAuthenticatedUsers

Examples:

The user "liz@example.com" would be user-liz@example.com. - The group "example@googlegroups.com" would be group-example@googlegroups.com. - To refer to all members of the Google Apps for Business domain "example.com", the entity would be domain-example.com.

For more detailed information, see About Access Control Lists.

Acl

Inheritance

AclRoleAccessorMethods > Acl

Package

@google-cloud/storage

Constructors

(constructor)(options)

constructor(options: AclOptions);

Constructs a new instance of the Acl class

Parameter

Name	Description
options	`AclOptions`

Properties

default

default: Acl;

pathPrefix

pathPrefix: string;

request_

request_: (reqOpts: DecorateRequestOptions, callback: BodyResponseCallback) => void;

Methods

add(options)

add(options: AddAclOptions): Promise<AddAclResponse>;

Add access controls on a Bucket or File.

See BucketAccessControls: insert API Documentation See ObjectAccessControls: insert API Documentation

Parameter

Name	Description
options	`AddAclOptions` Configuration options.

Returns

Type	Description
Promise<AddAclResponse>

Examples


const storage = require('@google-cloud/storage')();
const myBucket = storage.bucket('my-bucket');
const myFile = myBucket.file('my-file');

const options = {
  entity: 'user-useremail@example.com',
  role: gcs.acl.OWNER_ROLE
};

myBucket.acl.add(options, function(err, aclObject, apiResponse) {});

//-
// For file ACL operations, you can also specify a `generation` property.
// Here is how you would grant ownership permissions to a user on a
specific
// revision of a file.
//-
myFile.acl.add({
  entity: 'user-useremail@example.com',
  role: gcs.acl.OWNER_ROLE,
  generation: 1
}, function(err, aclObject, apiResponse) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
myBucket.acl.add(options).then(function(data) {
  const aclObject = data[0];
  const apiResponse = data[1];
});

Example of adding an owner to a file:


  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // The ID of your GCS bucket
  // const bucketName = 'your-unique-bucket-name';

  // The name of the file to access
  // const fileName = 'file.txt';

  // The email address of the user to add
  // const userEmail = 'user-email-to-add';

  // Imports the Google Cloud client library
  const {Storage} = require('@google-cloud/storage');

  // Creates a client
  const storage = new Storage();

  async function addFileOwner() {
    await storage
      .bucket(bucketName)
      .file(fileName)
      .acl.owners.addUser(userEmail);

    console.log(`Added user ${userEmail} as an owner on file ${fileName}.`);
  }

  addFileOwner().catch(console.error);

Example of adding an owner to a bucket:


  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // The ID of your GCS bucket
  // const bucketName = 'your-unique-bucket-name';

  // The email address of the user to add
  // const userEmail = 'user-email-to-add';

  // Imports the Google Cloud client library
  const {Storage} = require('@google-cloud/storage');

  // Creates a client
  const storage = new Storage();

  async function addBucketOwner() {
    // Makes the user an owner of the bucket. You can use addAllUsers(),
    // addDomain(), addProject(), addGroup(), and addAllAuthenticatedUsers()
    // to grant access to different types of entities. You can also use "readers"
    // and "writers" to grant different roles.
    await storage.bucket(bucketName).acl.owners.addUser(userEmail);

    console.log(`Added user ${userEmail} as an owner on bucket ${bucketName}.`);
  }

  addBucketOwner().catch(console.error);

Example of adding a default owner to a bucket:


  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // The ID of your GCS bucket
  // const bucketName = 'your-unique-bucket-name';

  // The email address of the user to add
  // const userEmail = 'user-email-to-add';

  // Imports the Google Cloud client library
  const {Storage} = require('@google-cloud/storage');

  // Creates a client
  const storage = new Storage();

  async function addBucketDefaultOwner() {
    // Makes the user an owner in the default ACL of the bucket. You can use
    // addAllUsers(), addDomain(), addProject(), addGroup(), and
    // addAllAuthenticatedUsers() to grant access to different types of entities.
    // You can also use "readers" and "writers" to grant different roles.
    await storage.bucket(bucketName).acl.default.owners.addUser(userEmail);

    console.log(`Added user ${userEmail} as an owner on bucket ${bucketName}.`);
  }

  addBucketDefaultOwner().catch(console.error);

add(options, callback)

add(options: AddAclOptions, callback: AddAclCallback): void;

Parameters

Name	Description
options	`AddAclOptions`
callback	`AddAclCallback`

Returns

Type	Description
void

delete(options)

delete(options: RemoveAclOptions): Promise<RemoveAclResponse>;

Delete access controls on a Bucket or File.

See BucketAccessControls: delete API Documentation See ObjectAccessControls: delete API Documentation

Parameter

Name	Description
options	`RemoveAclOptions` Configuration object.

Returns

Type	Description
Promise<RemoveAclResponse>

Examples


const storage = require('@google-cloud/storage')();
const myBucket = storage.bucket('my-bucket');
const myFile = myBucket.file('my-file');

myBucket.acl.delete({
  entity: 'user-useremail@example.com'
}, function(err, apiResponse) {});

//-
// For file ACL operations, you can also specify a `generation` property.
//-
myFile.acl.delete({
  entity: 'user-useremail@example.com',
  generation: 1
}, function(err, apiResponse) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
myFile.acl.delete().then(function(data) {
  const apiResponse = data[0];
});

Example of removing an owner from a bucket:


  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // The ID of your GCS bucket
  // const bucketName = 'your-unique-bucket-name';

  // The email address of the user to remove
  // const userEmail = 'user-email-to-remove';

  // Imports the Google Cloud client library
  const {Storage} = require('@google-cloud/storage');

  // Creates a client
  const storage = new Storage();

  async function removeBucketOwner() {
    // Removes the user from the access control list of the bucket. You can use
    // deleteAllUsers(), deleteDomain(), deleteProject(), deleteGroup(), and
    // deleteAllAuthenticatedUsers() to remove access for different types of entities.
    await storage.bucket(bucketName).acl.owners.deleteUser(userEmail);

    console.log(`Removed user ${userEmail} from bucket ${bucketName}.`);
  }

  removeBucketOwner().catch(console.error);

Example of removing a default owner from a bucket:


  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // The ID of your GCS bucket
  // const bucketName = 'your-unique-bucket-name';

  // The email address of the user to remove
  // const userEmail = 'user-email-to-remove';

  // Imports the Google Cloud client library
  const {Storage} = require('@google-cloud/storage');

  // Creates a client
  const storage = new Storage();

  async function removeBucketDefaultOwner() {
    // Removes the user from the access control list of the bucket. You can use
    // deleteAllUsers(), deleteDomain(), deleteProject(), deleteGroup(), and
    // deleteAllAuthenticatedUsers() to remove access for different types of entities.
    await storage.bucket(bucketName).acl.default.owners.deleteUser(userEmail);

    console.log(`Removed user ${userEmail} from bucket ${bucketName}.`);
  }

  removeBucketDefaultOwner().catch(console.error);

Example of removing an owner from a bucket:


  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // The ID of your GCS bucket
  // const bucketName = 'your-unique-bucket-name';

  // The ID of your GCS file
  // const fileName = 'your-file-name';

  // The email address of the user to remove
  // const userEmail = 'user-email-to-remove';

  // Imports the Google Cloud client library
  const {Storage} = require('@google-cloud/storage');

  // Creates a client
  const storage = new Storage();

  async function removeFileOwner() {
    // Removes the user from the access control list of the file. You can use
    // deleteAllUsers(), deleteDomain(), deleteProject(), deleteGroup(), and
    // deleteAllAuthenticatedUsers() to remove access for different types of entities.
    await storage
      .bucket(bucketName)
      .file(fileName)
      .acl.owners.deleteUser(userEmail);

    console.log(`Removed user ${userEmail} from file ${fileName}.`);
  }

  removeFileOwner().catch(console.error);

delete(options, callback)

delete(options: RemoveAclOptions, callback: RemoveAclCallback): void;

Parameters

Name	Description
options	`RemoveAclOptions`
callback	`RemoveAclCallback`

Returns

Type	Description
void

get(options)

get(options?: GetAclOptions): Promise<GetAclResponse>;

Get access controls on a Bucket or File. If an entity is omitted, you will receive an array of all applicable access controls.

See BucketAccessControls: get API Documentation See ObjectAccessControls: get API Documentation

Parameter

Name	Description
options	`GetAclOptions` Configuration options. If you want to receive a list of all access controls, pass the callback function as the only argument.

Returns

Type	Description
Promise<GetAclResponse>

Examples


const storage = require('@google-cloud/storage')();
const myBucket = storage.bucket('my-bucket');
const myFile = myBucket.file('my-file');

myBucket.acl.get({
  entity: 'user-useremail@example.com'
}, function(err, aclObject, apiResponse) {});

//-
// Get all access controls.
//-
myBucket.acl.get(function(err, aclObjects, apiResponse) {
  // aclObjects = [
  //   {
  //     entity: 'user-useremail@example.com',
  //     role: 'owner'
  //   }
  // ]
});

//-
// For file ACL operations, you can also specify a `generation` property.
//-
myFile.acl.get({
  entity: 'user-useremail@example.com',
  generation: 1
}, function(err, aclObject, apiResponse) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
myBucket.acl.get().then(function(data) {
  const aclObject = data[0];
  const apiResponse = data[1];
});

Example of printing a file's ACL:


  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // The ID of your GCS bucket
  // const bucketName = 'your-unique-bucket-name';

  // The ID of your GCS file
  // const fileName = 'your-file-name';

  // Imports the Google Cloud client library
  const {Storage} = require('@google-cloud/storage');

  // Creates a client
  const storage = new Storage();

  async function printFileAcl() {
    // Gets the ACL for the file
    const [acls] = await storage.bucket(bucketName).file(fileName).acl.get();

    acls.forEach(acl => {
      console.log(`${acl.role}: ${acl.entity}`);
    });
  }

  printFileAcl().catch(console.error);

Example of printing a file's ACL for a specific user:


  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // The ID of your GCS bucket
  // const bucketName = 'your-unique-bucket-name';

  // The ID of your GCS file
  // const fileName = 'your-file-name';

  // The email address of the user to check
  // const userEmail = 'user-email-to-check';

  // Imports the Google Cloud client library
  const {Storage} = require('@google-cloud/storage');

  // Creates a client
  const storage = new Storage();

  async function printFileAclForUser() {
    const options = {
      // Specify the user
      entity: `user-${userEmail}`,
    };

    // Gets the user's ACL for the file
    const [aclObject] = await storage
      .bucket(bucketName)
      .file(fileName)
      .acl.get(options);

    console.log(`${aclObject.role}: ${aclObject.entity}`);
  }

  printFileAclForUser().catch(console.error);

Example of printing a bucket's ACL:


  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // The ID of your GCS bucket
  // const bucketName = 'your-unique-bucket-name';

  // Imports the Google Cloud client library
  const {Storage} = require('@google-cloud/storage');

  // Creates a client
  const storage = new Storage();

  async function printBucketAcl() {
    // Gets the ACL for the bucket
    const [acls] = await storage.bucket(bucketName).acl.get();

    acls.forEach(acl => {
      console.log(`${acl.role}: ${acl.entity}`);
    });
  }
  printBucketAcl().catch(console.error);

Example of printing a bucket's ACL for a specific user:


  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // The ID of your GCS bucket
  // const bucketName = 'your-unique-bucket-name';

  // The email address of the user to check
  // const userEmail = 'user-email-to-check';

  // Imports the Google Cloud client library
  const {Storage} = require('@google-cloud/storage');

  // Creates a client
  const storage = new Storage();

  async function printBucketAclForUser() {
    const options = {
      // Specify the user
      entity: `user-${userEmail}`,
    };

    // Gets the user's ACL for the bucket
    const [aclObject] = await storage.bucket(bucketName).acl.get(options);

    console.log(`${aclObject.role}: ${aclObject.entity}`);
  }

  printBucketAclForUser().catch(console.error);

get(options, callback)

get(options: GetAclOptions, callback: GetAclCallback): void;

Parameters

Name	Description
options	`GetAclOptions`
callback	`GetAclCallback`

Returns

Type	Description
void

get(callback)

get(callback: GetAclCallback): void;

Parameter

Name	Description
callback	`GetAclCallback`

Returns

Type	Description
void

update(options)

update(options: UpdateAclOptions): Promise<UpdateAclResponse>;

Update access controls on a Bucket or File.

See BucketAccessControls: update API Documentation See ObjectAccessControls: update API Documentation

Parameter

Name	Description
options	`UpdateAclOptions` Configuration options.

Returns

Type	Description
Promise<UpdateAclResponse>

Example


const storage = require('@google-cloud/storage')();
const myBucket = storage.bucket('my-bucket');
const myFile = myBucket.file('my-file');

const options = {
  entity: 'user-useremail@example.com',
  role: gcs.acl.WRITER_ROLE
};

myBucket.acl.update(options, function(err, aclObject, apiResponse) {});

//-
// For file ACL operations, you can also specify a `generation` property.
//-
myFile.acl.update({
  entity: 'user-useremail@example.com',
  role: gcs.acl.WRITER_ROLE,
  generation: 1
}, function(err, aclObject, apiResponse) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
myFile.acl.update(options).then(function(data) {
  const aclObject = data[0];
  const apiResponse = data[1];
});

update(options, callback)

update(options: UpdateAclOptions, callback: UpdateAclCallback): void;

Parameters

Name	Description
options	`UpdateAclOptions`
callback	`UpdateAclCallback`

Returns

Type	Description
void