Acl

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.

Members

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, callbackopt) → {Promise.<AddAclResponse>}

Add access controls on a Bucket or File.

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

Parameters:
Name Type Attributes Description
options object

Configuration options.

Properties
Name Type Attributes Description
entity string

Whose permissions will be added.
role string

Permissions allowed for the defined entity. See Access Control.
generation number <optional>

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

The ID of the project which will be billed for the request.
callback AddAclCallback <optional>

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

```

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:

delete(options, callback) → {Promise.<RemoveAclResponse>}

Delete access controls on a Bucket or File.

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

Parameters:
Name Type Description
options object

Configuration object.

Properties
Name Type Attributes Description
entity string

Whose permissions will be revoked.
generation int <optional>

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

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

The callback function.
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];
});

```

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:

get(optionsopt, callbackopt) → {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

Parameters:
Name Type Attributes Description
options object | function <optional>

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

Properties
Name Type Attributes Description
entity string

Whose permissions will be fetched.
generation number <optional>

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

The ID of the project which will be billed for the request.
callback GetAclCallback <optional>

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

```

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:

update(options, callbackopt) → {Promise.<UpdateAclResponse>}

Update access controls on a Bucket or File.

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

Parameters:
Name Type Attributes Description
options object

Configuration options.

Properties
Name Type Attributes Description
entity string

Whose permissions will be updated.
role string

Permissions allowed for the defined entity. See Storage.acl.
generation number <optional>

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

The ID of the project which will be billed for the request.
callback UpdateAclCallback <optional>

Callback function.
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];
});
```