Properties

acl

static

object

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.

This object provides constants to refer to the three permission levels that can be granted to an entity:

  • gcs.acl.OWNER_ROLE - ("OWNER")
  • gcs.acl.READER_ROLE - ("READER")
  • gcs.acl.WRITER_ROLE - ("WRITER")

Properties

Parameter

OWNER_ROLE

string

READER_ROLE

string

WRITER_ROLE

string

See also

About Access Control Lists

Example

const {Storage} = require('@google-cloud/storage');
const storage = new Storage();
const albums = storage.bucket('albums');

//-
// Make all of the files currently in a bucket publicly readable.
//-
const options = {
  entity: 'allUsers',
  role: storage.acl.READER_ROLE
};

albums.acl.add(options, function(err, aclObject) {});

//-
// Make any new objects added to a bucket publicly readable.
//-
albums.acl.default.add(options, function(err, aclObject) {});

//-
// Grant a user ownership permissions to a bucket.
//-
albums.acl.add({
  entity: 'user-useremail@example.com',
  role: storage.acl.OWNER_ROLE
}, function(err, aclObject) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
albums.acl.add(options).then(function(data) {
  const aclObject = data[0];
  const apiResponse = data[1];
});

Bucket

static

Constructor

Bucket class.

See also
Bucket

Channel

static

Constructor

Channel class.

See also
Channel

File

static

Constructor

File class.

See also
File

acl

Reference to Storage.acl.

See also
Storage.acl

Methods

bucket

bucket(name, options) returns Bucket

Get a reference to a Cloud Storage bucket.

Parameter

name

string

Name of the bucket.

options

Optional

object

Configuration object.

Values in options have the following properties:

Parameter

kmsKeyName

Optional

string

A Cloud KMS key that will be used to encrypt objects inserted into this bucket, if no encryption method is specified.

userProject

Optional

string

User project to be billed for all requests made from this Bucket object.

See also
Bucket
Returns

Bucket 

Example

const {Storage} = require('@google-cloud/storage');
const storage = new Storage();
const albums = storage.bucket('albums');
const photos = storage.bucket('photos');

channel

channel(id, resourceId) returns Channel

Reference a channel to receive notifications about changes to your bucket.

Parameter

id

string

The ID of the channel.

resourceId

string

The resource ID of the channel.

See also
Channel
Returns

Channel 

Example

const {Storage} = require('@google-cloud/storage');
const storage = new Storage();
const channel = storage.channel('id', 'resource-id');

getBuckets

getBuckets(query, callback) returns Promise containing GetBucketsResponse

Get Bucket objects for all of the buckets in your project.

Parameter

query

Optional

GetBucketsRequest

Query object for listing buckets.

callback

Optional

GetBucketsCallback

Callback function.

See also

Buckets: list API Documentation

Returns

Promise containing GetBucketsResponse 

Example

const {Storage} = require('@google-cloud/storage');
const storage = new Storage();
storage.getBuckets(function(err, buckets) {
  if (!err) {
    // buckets is an array of Bucket objects.
  }
});

//-
// To control how many API requests are made and page through the results
// manually, set `autoPaginate` to `false`.
//-
const callback = function(err, buckets, nextQuery, apiResponse) {
  if (nextQuery) {
    // More results exist.
    storage.getBuckets(nextQuery, callback);
  }

  // The `metadata` property is populated for you with the metadata at the
  // time of fetching.
  buckets[0].metadata;

  // However, in cases where you are concerned the metadata could have
  // changed, use the `getMetadata` method.
  buckets[0].getMetadata(function(err, metadata, apiResponse) {});
};

storage.getBuckets({
  autoPaginate: false
}, callback);

//-
// If the callback is omitted, we'll return a Promise.
//-
storage.getBuckets().then(function(data) {
  const buckets = data[0];
});

Another example:

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

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

// Lists all buckets in the current project
storage
  .getBuckets()
  .then(results => {
    const buckets = results[0];

    console.log('Buckets:');
    buckets.forEach(bucket => {
      console.log(bucket.name);
    });
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

getServiceAccount

getServiceAccount(options, callback) returns Promise containing GetServiceAccountResponse

Get the email address of this project's Google Cloud Storage service account.

Parameter

options

Optional

object

Configuration object.

Values in options have the following properties:

Parameter

userProject

Optional

string

User project to be billed for this request.

callback

Optional

GetServiceAccountCallback

Callback function.

See also

Projects.serviceAccount: get API Documentation

Projects.serviceAccount Resource

Returns

Promise containing GetServiceAccountResponse 

Example

const {Storage} = require('@google-cloud/storage');
const storage = new Storage();

storage.getServiceAccount(function(err, serviceAccount, apiResponse) {
  if (!err) {
    const serviceAccountEmail = serviceAccount.emailAddress;
  }
});

//-
// If the callback is omitted, we'll return a Promise.
//-
storage.getServiceAccount().then(function(data) {
  const serviceAccountEmail = data[0].emailAddress;
  const apiResponse = data[1];
});