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.

Values in options have the following properties:

Parameter

entity

string

Whose permissions will be added.

role

string

Permissions allowed for the defined entity. See Access Control.

generation

Optional

number

File Objects Only Select a specific revision of this file (as opposed to the latest version, the default).

userProject

Optional

string

The ID of the project which will be billed for the request.

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) returns Promise containing RemoveAclResponse

Delete access controls on a Bucket or File.

Parameter

options

object

Configuration object.

Values in options have the following properties:

Parameter

entity

string

Whose permissions will be revoked.

generation

Optional

int

File Objects Only Select a specific revision of this file (as opposed to the latest version, the default).

userProject

Optional

string

The ID of the project which will be billed for the request.

callback

RemoveAclCallback

The callback function.

See also

BucketAccessControls: delete API Documentation

ObjectAccessControls: delete API Documentation

Returns

Promise containing RemoveAclResponse 

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.

Values in options have the following properties:

Parameter

entity

Optional

string