Properties

owners

An object of convenience methods to add or delete owner ACL permissions for a given entity.

The supported methods include:

  • myFile.acl.owners.addAllAuthenticatedUsers
  • myFile.acl.owners.deleteAllAuthenticatedUsers
  • myFile.acl.owners.addAllUsers
  • myFile.acl.owners.deleteAllUsers
  • myFile.acl.owners.addDomain
  • myFile.acl.owners.deleteDomain
  • myFile.acl.owners.addGroup
  • myFile.acl.owners.deleteGroup
  • myFile.acl.owners.addProject
  • myFile.acl.owners.deleteProject
  • myFile.acl.owners.addUser
  • myFile.acl.owners.deleteUser
Returns

object 

Example

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

//-
// Add a user as an owner of a file.
//-
var myBucket = gcs.bucket('my-bucket');
var myFile = myBucket.file('my-file');
myFile.acl.owners.addUser('email@example.com', function(err, aclObject) {});

//-
// For reference, the above command is the same as running the following.
//-
myFile.acl.add({
  entity: 'user-email@example.com',
  role: gcs.acl.OWNER_ROLE
}, function(err, aclObject) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
myFile.acl.owners.addUser('email@example.com').then(function(data) {
  var aclObject = data[0];
  var apiResponse = data[1];
});

readers

An object of convenience methods to add or delete reader ACL permissions for a given entity.

The supported methods include:

  • myFile.acl.readers.addAllAuthenticatedUsers
  • myFile.acl.readers.deleteAllAuthenticatedUsers
  • myFile.acl.readers.addAllUsers
  • myFile.acl.readers.deleteAllUsers
  • myFile.acl.readers.addDomain
  • myFile.acl.readers.deleteDomain
  • myFile.acl.readers.addGroup
  • myFile.acl.readers.deleteGroup
  • myFile.acl.readers.addProject
  • myFile.acl.readers.deleteProject
  • myFile.acl.readers.addUser
  • myFile.acl.readers.deleteUser
Returns

object 

Example

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

//-
// Add a user as a reader of a file.
//-
myFile.acl.readers.addUser('email@example.com', function(err, aclObject) {});

//-
// For reference, the above command is the same as running the following.
//-
myFile.acl.add({
  entity: 'user-email@example.com',
  role: gcs.acl.READER_ROLE
}, function(err, aclObject) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
myFile.acl.readers.addUser('email@example.com').then(function(data) {
  var aclObject = data[0];
  var apiResponse = data[1];
});

writers

An object of convenience methods to add or delete writer ACL permissions for a given entity.

The supported methods include:

  • myFile.acl.writers.addAllAuthenticatedUsers
  • myFile.acl.writers.deleteAllAuthenticatedUsers
  • myFile.acl.writers.addAllUsers
  • myFile.acl.writers.deleteAllUsers
  • myFile.acl.writers.addDomain
  • myFile.acl.writers.deleteDomain
  • myFile.acl.writers.addGroup
  • myFile.acl.writers.deleteGroup
  • myFile.acl.writers.addProject
  • myFile.acl.writers.deleteProject
  • myFile.acl.writers.addUser
  • myFile.acl.writers.deleteUser
Returns

object 

Example

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

//-
// Add a user as a writer of a file.
//-
myFile.acl.writers.addUser('email@example.com', function(err, aclObject) {});

//-
// For reference, the above command is the same as running the following.
//-
myFile.acl.add({
  entity: 'user-email@example.com',
  role: gcs.acl.WRITER_ROLE
}, function(err, aclObject) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
myFile.acl.writers.addUser('email@example.com').then(function(data) {
  var aclObject = data[0];
  var apiResponse = data[1];
});

Methods

add

add(options, callback) returns Promise containing AddAclResponse

Add access controls on a Bucket or File.

Parameter

options

object

Configuration options.

callback

Optional

AddAclCallback

Callback function.

See also

BucketAccessControls: insert API Documentation

ObjectAccessControls: insert API Documentation

Returns

Promise containing AddAclResponse 

Example

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

var 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) {
  var aclObject = data[0];
  var apiResponse = data[1];
});

Example of adding an owner to a file:

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

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

/**
 * TODO(developer): Uncomment the following line before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';
// const filename = 'Name of file to access, e.g. file.txt';
// const userEmail = 'Email of user to add, e.g. developer@company.com';

// Makes the user an owner of the file. 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.
storage
  .bucket(bucketName)
  .file(filename)
  .acl.owners.addUser(userEmail)
  .then(() => {
    console.log(`Added user ${userEmail} as an owner on file ${filename}.`);
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

Example of adding an owner to a bucket:

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

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

/**
 * TODO(developer): Uncomment the following line before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';
// const userEmail = 'Email of user to add, e.g. developer@company.com';

// 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.
storage
  .bucket(bucketName)
  .acl.owners.addUser(userEmail)
  .then(() => {
    console.log(
      `Added user ${userEmail} as an owner on bucket ${bucketName}.`
    );
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

Example of adding a default owner to a bucket:

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

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

/**
 * TODO(developer): Uncomment the following line before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';
// const userEmail = 'Email of user to add, e.g. developer@company.com';

// 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.
storage
  .bucket(bucketName)
  .acl.default.owners.addUser(userEmail)
  .then(() => {
    console.log(
      `Added user ${userEmail} as an owner on bucket ${bucketName}.`
    );
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

delete

delete(options, callback)

Delete access controls on a Bucket or File.

Parameter

options

Optional

object

Configuration object.

callback

function()

The callback function.

See also

BucketAccessControls: delete API Documentation

ObjectAccessControls: delete API Documentation

Example

var storage = require('@google-cloud/storage')();
var myBucket = storage.bucket('my-bucket');
var 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) {
  var apiResponse = data[0];
});

Example of removing an owner from a bucket:

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

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

/**
 * TODO(developer): Uncomment the following line before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';
// const userEmail = 'Email of user to remove, e.g. developer@company.com';

// 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.
storage
  .bucket(bucketName)
  .acl.owners.deleteUser(userEmail)
  .then(() => {
    console.log(`Removed user ${userEmail} from bucket ${bucketName}.`);
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

Example of removing a default owner from a bucket:

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

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

/**
 * TODO(developer): Uncomment the following line before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';
// const userEmail = 'Email of user to remove, e.g. developer@company.com';

// 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.
storage
  .bucket(bucketName)
  .acl.default.owners.deleteUser(userEmail)
  .then(() => {
    console.log(`Removed user ${userEmail} from bucket ${bucketName}.`);
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

Example of removing an owner from a bucket:

function removeFileOwner(bucketName, filename, userEmail) {
  // Imports the Google Cloud client library
  const Storage = require('@google-cloud/storage');

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

  /**
   * TODO(developer): Uncomment the following line before running the sample.
   */
  // const bucketName = 'Name of a bucket, e.g. my-bucket';
  // const filename = 'Name of file to access, e.g. file.txt';
  // const userEmail = 'Email of user to remove, e.g. developer@company.com';

  // 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.
  storage
    .bucket(bucketName)
    .file(filename)
    .acl.owners.deleteUser(userEmail)
    .then(() => {
      console.log(`Removed user ${userEmail} from file ${filename}.`);
    })
    .catch(err => {
      console.error('ERROR:', err);
    });

get

get(options, callback) returns Promise containing GetAclResponse

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

Parameter

options

Optional

(object or function())

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

callback

Optional

GetAclCallback

Callback function.

See also

BucketAccessControls: get API Documentation

ObjectAccessControls: get API Documentation

Returns

Promise containing GetAclResponse 

Example

var storage = require('@google-cloud/storage')();
var myBucket = storage.bucket('my-bucket');
var 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) {
  var aclObject = data[0];
  var apiResponse = data[1];
});

Example of printing a file's ACL:

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

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

/**
 * TODO(developer): Uncomment the following line before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';
// const filename = 'File to access, e.g. file.txt';

// Gets the ACL for the file
storage
  .bucket(bucketName)
  .file(filename)
  .acl.get()
  .then(results => {
    const acls = results[0];

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

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

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

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

/**
 * TODO(developer): Uncomment the following line before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';
// const filename = 'File to access, e.g. file.txt';
// const userEmail = 'Email of user to check, e.g. developer@company.com';

const options = {
  // Specify the user
  entity: `user-${userEmail}`,
};

// Gets the user's ACL for the file
storage
  .bucket(bucketName)
  .file(filename)
  .acl.get(options)
  .then(results => {
    const aclObject = results[0];

    console.log(`${aclObject.role}: ${aclObject.entity}`);
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

Example of printing a bucket's ACL:

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

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

/**
 * TODO(developer): Uncomment the following line before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';

// Gets the ACL for the bucket
storage
  .bucket(bucketName)
  .acl.get()
  .then(results => {
    const acls = results[0];

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

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

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

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

/**
 * TODO(developer): Uncomment the following line before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';
// const userEmail = 'Email of user to check, e.g. developer@company.com';

const options = {
  // Specify the user
  entity: `user-${userEmail}`,
};

// Gets the user's ACL for the bucket
storage
  .bucket(bucketName)
  .acl.get(options)
  .then(results => {
    const aclObject = results[0];

    console.log(`${aclObject.role}: ${aclObject.entity}`);
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

update

update(options, callback) returns Promise containing UpdateAclResponse

Update access controls on a Bucket or File.

Parameter

options

object

Configuration options.

callback

Optional

UpdateAclCallback

Callback function.

See also

BucketAccessControls: update API Documentation

ObjectAccessControls: update API Documentation

Returns

Promise containing UpdateAclResponse 

Example

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

var 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) {
  var aclObject = data[0];
  var apiResponse = data[1];
});