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 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 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 channel = storage.channel('id', 'resource-id');

createBucket

createBucket(name, metadata, callback) returns Promise containing CreateBucketResponse

Create a bucket.

Cloud Storage uses a flat namespace, so you can't create a bucket with a name that is already in use. For more information, see Bucket Naming Guidelines.

Parameter

name

string

Name of the bucket to create.

metadata

Optional

CreateBucketRequest

Metadata to set for the bucket.

callback

Optional

CreateBucketCallback

Callback function.

See also

Buckets: insert API Documentation

Storage Classes

Bucket#create
Throws

Error 

If a name is not provided.

Returns

Promise containing CreateBucketResponse 

Example

const storage = require('@google-cloud/storage')();
const callback = function(err, bucket, apiResponse) {
  // `bucket` is a Bucket object.
};

storage.createBucket('new-bucket', callback);

//-
// Create a bucket in a specific location and region. <em>See the <a
// href="https://cloud.google.com/storage/docs/json_api/v1/buckets/insert">
// Official JSON API docs</a> for complete details on the `location` option.
// </em>
//-
const metadata = {
  location: 'US-CENTRAL1',
  regional: true
};

storage.createBucket('new-bucket', metadata, callback);

//-
// Enable versioning on a new bucket.
//-
const metadata = {
  versioning: {
    enabled: true
  }
};

storage.createBucket('new-bucket', metadata, callback);

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

Another example:

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

// Creates a new bucket
storage
  .createBucket(bucketName, {
    location: 'ASIA',
    storageClass: 'COLDLINE',
  })
  .then(() => {
    console.log(`Bucket ${bucketName} created.`);
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

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

getBucketsStream

getBucketsStream(query) returns ReadableStream

Get Bucket objects for all of the buckets in your project as a readable object stream.

Parameter

query

Optional

GetBucketsRequest

Query object for listing buckets.

Returns

ReadableStream 

A readable stream that emits Bucket instances.

Example

storage.getBucketsStream()
  .on('error', console.error)
  .on('data', function(bucket) {
    // bucket is a Bucket object.
  })
  .on('end', function() {
    // All buckets retrieved.
  });

//-
// If you anticipate many results, you can end a stream early to prevent
// unnecessary processing and API requests.
//-
storage.getBucketsStream()
  .on('data', function(bucket) {
    this.end();
  });