mixin

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.

Properties

owners

readers

writers

Methods

add(options[, callback])
delete(options, callback)

get([options][, callback])
update(options[, callback])

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

Example

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

//-
// Add a user as an owner of a file.
//-
const myBucket = gcs.bucket('my-bucket');
const 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) {
  const aclObject = data[0];
  const 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

Example

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

Example

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

Methods

add(options[, callback]) → Promise containing AddAclResponse

Add access controls on a Bucket or File.

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

include:samples/acl.js

region_tag:storage_add_file_owner
Example of adding an owner to a file:

include:samples/acl.js

region_tag:storage_add_bucket_owner
Example of adding an owner to a bucket:

include:samples/acl.js

region_tag:storage_add_bucket_default_owner
Example of adding a default owner to a bucket:

Parameters

Name Type Optional Description

options

object

Configuration options.

Values in options have the following properties:

Name	Type	Optional	Description
entity	string		Whose permissions will be added.
role	string		Permissions allowed for the defined entity. See Access Control.
generation	number	Yes	File Objects Only Select a specific revision of this file (as opposed to the latest version, the default).
userProject	string	Yes	The ID of the project which will be billed for the request.

callback

AddAclCallback

Yes

Callback function.

See also: BucketAccessControls: insert API Documentation; ObjectAccessControls: insert API Documentation
Returns: Promise containing AddAclResponse

delete(options, callback) → Promise containing RemoveAclResponse

Delete access controls on a Bucket or File.

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

include:samples/acl.js

region_tag:storage_remove_bucket_owner
Example of removing an owner from a bucket:

include:samples/acl.js

region_tag:storage_remove_bucket_default_owner
Example of removing a default owner from a bucket:

include:samples/acl.js

region_tag:storage_remove_file_owner
Example of removing an owner from a bucket:

Parameters

Name Type Optional Description

options

object

Configuration object.

Values in options have the following properties:

Name	Type	Optional	Description
entity	string		Whose permissions will be revoked.
generation	int	Yes	File Objects Only Select a specific revision of this file (as opposed to the latest version, the default).
userProject	string	Yes	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

get([options][, callback]) → 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.

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

include:samples/acl.js

region_tag:storage_print_file_acl
Example of printing a file's ACL:

include:samples/acl.js

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

include:samples/acl.js

region_tag:storage_print_bucket_acl
Example of printing a bucket's ACL:

include:samples/acl.js

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

Parameters

Name Type Optional Description

options

(object or function())

Yes

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:

Name	Type	Optional	Description
entity	string	Yes	Whose permissions will be fetched.
generation	number	Yes	File Objects Only Select a specific revision of this file (as opposed to the latest version, the default).
userProject	string	Yes	The ID of the project which will be billed for the request.

callback

GetAclCallback

Yes

Callback function.

See also: BucketAccessControls: get API Documentation; ObjectAccessControls: get API Documentation
Returns: Promise containing GetAclResponse

update(options[, callback]) → Promise containing UpdateAclResponse

Update access controls on a Bucket or File.

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

Parameters

Name Type Optional Description

options

object

Configuration options.

Values in options have the following properties:

Name	Type	Optional	Description
entity	string		Whose permissions will be updated.
role	string		Permissions allowed for the defined entity. See Storage.acl.
generation	number	Yes	File Objects Only Select a specific revision of this file (as opposed to the latest version, the default).
userProject	string	Yes	The ID of the project which will be billed for the request.

callback

UpdateAclCallback

Yes

Callback function.

See also: BucketAccessControls: update API Documentation; ObjectAccessControls: update API Documentation
Returns: Promise containing UpdateAclResponse