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).

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');

// The name of the bucket to access, e.g. "my-bucket"
// const bucketName = "my-bucket";

// The name of the file to access, e.g. "file.txt"
// const filename = "file.txt";

// The email of the user to add, e.g. "developer@company.com"
// const userEmail = "developer@company.com";

// Instantiates a client
const storage = Storage();

// 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');

// The name of the bucket to access, e.g. "my-bucket"
// const bucketName = "my-bucket";

// The email of the user to add, e.g. "developer@company.com"
// const userEmail = "developer@company.com";

// Instantiates a client
const storage = Storage();

// 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');

// The name of the bucket to access, e.g. "my-bucket"
// const bucketName = "my-bucket";

// The email of the user to add, e.g. "developer@company.com"
// const userEmail = "developer@company.com";

// Instantiates a client
const storage = Storage();

// 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.

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).

callback

function()

The callback function.

Values in callback have the following properties:

Parameter

err

error

An error returned while making this request

Value may be null.

apiResponse

object

The full API response.

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');

// The name of the bucket to access, e.g. "my-bucket"
// const bucketName = "my-bucket";

// The email of the user to remove, e.g. "developer@company.com"
// const userEmail = "developer@company.com";

// Instantiates a client
const storage = Storage();

// 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');

// The name of the bucket to access, e.g. "my-bucket"
// const bucketName = "my-bucket";

// The email of the user to remove, e.g. "developer@company.com"
// const userEmail = "developer@company.com";

// Instantiates a client
const storage = Storage();

// 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');

  // The name of the bucket to access, e.g. "my-bucket"
  // const bucketName = "my-bucket";

  // The name of the file to access, e.g. "file.txt"
  // const filename = "file.txt";

  // The email of the user to remove, e.g. "developer@company.com"
  // const userEmail = "developer@company.com";

  // Instantiates a client
  const storage = Storage();

  // 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

Whose permissions will be fetched.

generation

Optional

number

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

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');

// The name of the bucket to access, e.g. "my-bucket"
// const bucketName = "my-bucket";

// The name of the file to access, e.g. "file.txt"
// const filename = "file.txt";

// Instantiates a client
const storage = Storage();

// 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');

// The name of the bucket to access, e.g. "my-bucket"
// const bucketName = "my-bucket";

// The name of the file to access, e.g. "file.txt"
// const filename = "file.txt";

// The email of the user to check, e.g. "developer@company.com"
// const userEmail = "developer@company.com";

// Instantiates a client
const storage = Storage();

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');

// The name of the bucket to access, e.g. "my-bucket"
// const bucketName = "my-bucket";

// Instantiates a client
const storage = Storage();

// 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');

// The name of the bucket to access, e.g. "my-bucket"
// const bucketName = "my-bucket";

// The email of the user to check, e.g. "developer@company.com"
// const userEmail = "developer@company.com";

// Instantiates a client
const storage = Storage();

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.

Values in options have the following properties:

Parameter

entity

string

Whose permissions will be updated.

role

string

Permissions allowed for the defined entity. See Storage.acl.

generation

Optional

number

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

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];
});