Bucket

Bucket

Create a Bucket object to interact with a Cloud Storage bucket.

Constructor

new Bucket(storage, name, optionsopt)

Parameters:
Name Type Attributes Description
storage Storage

A Storage instance.

name string

The name of the bucket.

options object <optional>

Configuration object.

Properties
Name Type Attributes Description
userProject string <optional>

User project.

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

Methods

addLifecycleRule(rule, optionsopt, callbackopt) → {Promise.<SetBucketMetadataResponse>}

Add an object lifecycle management rule to the bucket.

By default, an Object Lifecycle Management rule provided to this method will be included to the existing policy. To replace all existing rules, supply the options argument, setting append to false.

Parameters:
Name Type Attributes Description
rule LifecycleRule

The new lifecycle rule to be added to objects in this bucket.

Properties
Name Type Attributes Description
storageClass string <optional>

When using the setStorageClass action, provide this option to dictate which storage class the object should update to.

options AddLifecycleRuleOptions <optional>

Configuration object.

Properties
Name Type Attributes Default Description
append boolean <optional>
true

Append the new rule to the existing policy.

callback SetBucketMetadataCallback <optional>

Callback function.

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

//-
// Automatically have an object deleted from this bucket once it is 3 years
// of age.
//-
bucket.addLifecycleRule({
  action: 'delete',
  condition: {
    age: 365 * 3 // Specified in days.
  }
}, function(err, apiResponse) {
  if (err) {
    // Error handling omitted.
  }

  const lifecycleRules = bucket.metadata.lifecycle.rule;

  // Iterate over the Object Lifecycle Management rules on this bucket.
  lifecycleRules.forEach(lifecycleRule => {});
});

//-
// By default, the rule you provide will be added to the existing policy.
// Optionally, you can disable this behavior to replace all of the
// pre-existing rules.
//-
const options = {
  append: false
};

bucket.addLifecycleRule({
  action: 'delete',
  condition: {
    age: 365 * 3 // Specified in days.
  }
}, options, function(err, apiResponse) {
  if (err) {
    // Error handling omitted.
  }

  // All rules have been replaced with the new "delete" rule.

  // Iterate over the Object Lifecycle Management rules on this bucket.
  lifecycleRules.forEach(lifecycleRule => {});
});

//-
// For objects created before 2018, "downgrade" the storage class.
//-
bucket.addLifecycleRule({
  action: 'setStorageClass',
  storageClass: 'COLDLINE',
  condition: {
    createdBefore: new Date('2018')
  }
}, function(err, apiResponse) {});

//-
// Delete objects created before 2016 which have the Coldline storage
// class.
//-
bucket.addLifecycleRule({
  action: 'delete',
  condition: {
    matchesStorageClass: [
      'COLDLINE'
    ],
    createdBefore: new Date('2016')
  }
}, function(err, apiResponse) {});

combine(sources, destination, optionsopt, callbackopt) → {Promise.<CombineResponse>}

Combine multiple files into one new file.

Parameters:
Name Type Attributes Description
sources Array.<string> | Array.<File>

The source files that will be combined.

destination string | File

The file you would like the source files combined into.

options CombineOptions <optional>

Configuration options.

callback CombineCallback <optional>

Callback function.

Source:
See:
Throws:
  • if a non-array is provided as sources argument.

    Type
    Error
  • if less than two sources are provided.

    Type
    Error
  • if no destination is provided.

    Type
    Error
Example
const logBucket = storage.bucket('log-bucket');

const sources = [
  logBucket.file('2013-logs.txt'),
  logBucket.file('2014-logs.txt')
];

const allLogs = logBucket.file('all-logs.txt');

logBucket.combine(sources, allLogs, function(err, newFile, apiResponse) {
  // newFile === allLogs
});

//-
// If the callback is omitted, we'll return a Promise.
//-
logBucket.combine(sources, allLogs).then(function(data) {
  const newFile = data[0];
  const apiResponse = data[1];
});

create(metadataopt, callbackopt) → {Promise.<CreateBucketResponse>}

Create a bucket.

Parameters:
Name Type Attributes Description
metadata CreateBucketRequest <optional>

Metadata to set for the bucket.

callback CreateBucketCallback <optional>

Callback function.

Source:
Example
const {Storage} = require('@google-cloud/storage');
const storage = new Storage();
const bucket = storage.bucket('albums');
bucket.create(function(err, bucket, apiResponse) {
  if (!err) {
    // The bucket was created successfully.
  }
});

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

createChannel(id, config, optionsopt, callbackopt) → {Promise.<CreateChannelResponse>}

Create a channel that will be notified when objects in this bucket changes.

Parameters:
Name Type Attributes Description
id string

The ID of the channel to create.

config CreateChannelConfig

Configuration for creating channel.

options CreateChannelOptions <optional>

Configuration options.

callback CreateChannelCallback <optional>

Callback function.

Source:
See:
Throws:
  • If an ID is not provided.

    Type
    Error
  • If an address is not provided.

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

const config = {
  address: 'https://...'
};

bucket.createChannel(id, config, function(err, channel, apiResponse) {
  if (!err) {
    // Channel created successfully.
  }
});

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

createNotification(topic, optionsopt, callbackopt) → {Promise.<CreateNotificationResponse>}

Creates a notification subscription for the bucket.

Parameters:
Name Type Attributes Description
topic Topic | string

The Cloud PubSub topic to which this subscription publishes. If the project ID is omitted, the current project ID will be used.

Acceptable formats are:
- `projects/grape-spaceship-123/topics/my-topic`

- `my-topic`
options CreateNotificationOptions <optional>

Metadata to set for the notification.

callback CreateNotificationCallback <optional>

Callback function.

Source:
See:
Throws:

If a valid topic is not provided.

Type
Error
Examples
const {Storage} = require('@google-cloud/storage');
const storage = new Storage();
const myBucket = storage.bucket('my-bucket');

const callback = function(err, notification, apiResponse) {
  if (!err) {
    // The notification was created successfully.
  }
};

myBucket.createNotification('my-topic', callback);

//-
// Configure the nofiication by providing Notification metadata.
//-
const metadata = {
  objectNamePrefix: 'prefix-'
};

myBucket.createNotification('my-topic', metadata, callback);

//-
// If the callback is omitted, we'll return a Promise.
//-
myBucket.createNotification('my-topic').then(function(data) {
  const notification = 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 lines before running the sample.
   */
  // const bucketName = 'Name of a bucket, e.g. my-bucket';
  // const topic = 'Name of a topic, e.g. my-topic';

  // Creates a notification
  await storage.bucket(bucketName).createNotification(topic);

  console.log('Notification subscription created.');

delete(optionsopt, callbackopt) → {Promise.<DeleteBucketResponse>}

Delete the bucket.

Parameters:
Name Type Attributes Description
options DeleteBucketOptions <optional>

Configuration options.

callback DeleteBucketCallback <optional>

Callback function.

Source:
See:
Examples
const {Storage} = require('@google-cloud/storage');
const storage = new Storage();
const bucket = storage.bucket('albums');
bucket.delete(function(err, apiResponse) {});

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

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

  // Deletes the bucket
  await storage.bucket(bucketName).delete();

  console.log(`Bucket ${bucketName} deleted.`);

deleteFiles(queryopt, callbackopt) → {Promise}

Iterate over the bucket's files, calling file.delete() on each.

This is not an atomic request. A delete attempt will be made for each file individually. Any one can fail, in which case only a portion of the files you intended to be deleted would have.

Operations are performed in parallel, up to 10 at once. The first error breaks the loop and will execute the provided callback with it. Specify { force: true } to suppress the errors until all files have had a chance to be processed.

The query object passed as the first argument will also be passed to Bucket#getFiles.

Parameters:
Name Type Attributes Description
query DeleteFilesOptions <optional>

Query object. See Bucket#getFiles

callback DeleteFilesCallback <optional>

Callback function.

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

//-
// Delete all of the files in the bucket.
//-
bucket.deleteFiles(function(err) {});

//-
// By default, if a file cannot be deleted, this method will stop deleting
// files from your bucket. You can override this setting with `force:
// true`.
//-
bucket.deleteFiles({
  force: true
}, function(errors) {
  // `errors`:
  //    Array of errors if any occurred, otherwise null.
});

//-
// The first argument to this method acts as a query to
// Bucket#getFiles. As an example, you can delete files
// which match a prefix.
//-
bucket.deleteFiles({
  prefix: 'images/'
}, function(err) {
  if (!err) {
    // All files in the `images` directory have been deleted.
  }
});

//-
// If the callback is omitted, we'll return a Promise.
//-
bucket.deleteFiles().then(function() {});

deleteLabels(labels, callbackopt) → {Promise.<DeleteLabelsResponse>}

Delete one or more labels from this bucket.

Parameters:
Name Type Attributes Description
labels string | Array.<string>

The labels to delete. If no labels are provided, all of the labels are removed.

callback DeleteLabelsCallback <optional>

Callback function.

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

//-
// Delete all of the labels from this bucket.
//-
bucket.deleteLabels(function(err, apiResponse) {});

//-
// Delete a single label.
//-
bucket.deleteLabels('labelone', function(err, apiResponse) {});

//-
// Delete a specific set of labels.
//-
bucket.deleteLabels([
  'labelone',
  'labeltwo'
], function(err, apiResponse) {});

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

disableRequesterPays(callbackopt) → {Promise.<DisableRequesterPaysCallback>}

Early Access Testers Only

This feature is not yet widely-available.

Disable requesterPays functionality from this bucket.

Parameters:
Name Type Attributes Description
callback DisableRequesterPaysCallback <optional>

Callback function.

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

bucket.disableRequesterPays(function(err, apiResponse) {
  if (!err) {
    // requesterPays functionality disabled successfully.
  }
});

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

Example of disabling requester pays:

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

  // Disables requester-pays requests
  await storage.bucket(bucketName).disableRequesterPays();

  console.log(
    `Requester-pays requests have been disabled for bucket ${bucketName}.`
  );

enableLogging(config, callbackopt) → {Promise.<SetBucketMetadataResponse>}

Enable logging functionality for this bucket. This will make two API requests, first to grant Cloud Storage WRITE permission to the bucket, then to set the appropriate configuration on the Bucket's metadata.

Parameters:
Name Type Attributes Description
config EnableLoggingOptions

Configuration options.

callback SetBucketMetadataCallback <optional>

Callback function.

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

const config = {
  prefix: 'log'
};

bucket.enableLogging(config, function(err, apiResponse) {
  if (!err) {
    // Logging functionality enabled successfully.
  }
});

Optionally, provide a destination bucket.

const config = {
  prefix: 'log',
  bucket: 'destination-bucket'
};

bucket.enableLogging(config, function(err, apiResponse) {});

If the callback is omitted, we'll return a Promise.

bucket.enableLogging(config).then(function(data) {
  const apiResponse = data[0];
});

enableRequesterPays(callbackopt) → {Promise.<EnableRequesterPaysResponse>}

Early Access Testers Only

This feature is not yet widely-available.

Enable requesterPays functionality for this bucket. This enables you, the bucket owner, to have the requesting user assume the charges for the access to your bucket and its contents.

Parameters:
Name Type Attributes Description
callback EnableRequesterPaysCallback <optional>

Callback function.

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

bucket.enableRequesterPays(function(err, apiResponse) {
  if (!err) {
    // requesterPays functionality enabled successfully.
  }
});

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

Example of enabling requester pays:

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

  // Enables requester-pays requests
  await storage.bucket(bucketName).enableRequesterPays();

  console.log(
    `Requester-pays requests have been enabled for bucket ${bucketName}.`
  );

exists(optionsopt, callbackopt) → {Promise.<BucketExistsResponse>}

Check if the bucket exists.

Parameters:
Name Type Attributes Description
options BucketExistsOptions <optional>

Configuration options.

callback BucketExistsCallback <optional>

Callback function.

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

bucket.exists(function(err, exists) {});

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

file(name, optionsopt) → {File}

Create a File object. See File to see how to handle the different use cases you may have.

Parameters:
Name Type Attributes Description
name string

The name of the file in this bucket.

options object <optional>

Configuration options.

Properties
Name Type Attributes Description
generation string | number <optional>

Only use a specific revision of this file.

encryptionKey string <optional>

A custom encryption key. See Customer-supplied Encryption Keys.

kmsKeyName string <optional>

The name of the Cloud KMS key that will be used to encrypt the object. Must be in the format: projects/my-project/locations/location/keyRings/my-kr/cryptoKeys/my-key. KMS key ring must use the same location as the bucket.

Source:
Example
const {Storage} = require('@google-cloud/storage');
const storage = new Storage();
const bucket = storage.bucket('albums');
const file = bucket.file('my-existing-file.png');

get(optionsopt, callbackopt) → {Promise.<GetBucketResponse>}

Get a bucket if it exists.

You may optionally use this to "get or create" an object by providing an object with autoCreate set to true. Any extra configuration that is normally required for the create method must be contained within this object as well.

Parameters:
Name Type Attributes Description
options GetBucketOptions <optional>

Configuration options.

callback GetBucketCallback <optional>

Callback function.

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

bucket.get(function(err, bucket, apiResponse) {
  // `bucket.metadata` has been populated.
});

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

getFiles(queryopt, callbackopt) → {Promise.<GetFilesResponse>}

Get File objects for the files currently in the bucket.

Parameters:
Name Type Attributes Description
query GetFilesOptions <optional>

Query object for listing files.

callback GetFilesCallback <optional>

Callback function.

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

bucket.getFiles(function(err, files) {
  if (!err) {
    // files is an array of File objects.
  }
});

//-
// If your bucket has versioning enabled, you can get all of your files
// scoped to their generation.
//-
bucket.getFiles({
  versions: true
}, function(err, files) {
  // Each file is scoped to its generation.
});

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

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

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

bucket.getFiles({
  autoPaginate: false
}, callback);

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

Simulating a File System

With `autoPaginate: false`, it's possible to iterate over files which incorporate a common structure using a delimiter.

Consider the following remote objects:

  1. "a"
  2. "a/b/c/d"
  3. "b/d/e"

Using a delimiter of `/` will return a single file, "a".

`apiResponse.prefixes` will return the "sub-directories" that were found:

  1. "a/"
  2. "b/"

bucket.getFiles({
  autoPaginate: false,
  delimiter: '/'
}, function(err, files, nextQuery, apiResponse) {
  // files = [
  //   {File} // File object for file "a"
  // ]

  // apiResponse.prefixes = [
  //   'a/',
  //   'b/'
  // ]
});

Using prefixes, it's now possible to simulate a file system with follow-up requests.

bucket.getFiles({
  autoPaginate: false,
  delimiter: '/',
  prefix: 'a/'
}, function(err, files, nextQuery, apiResponse) {
  // No files found within "directory" a.
  // files = []

  // However, a "sub-directory" was found.
  // This prefix can be used to continue traversing the "file system".
  // apiResponse.prefixes = [
  //   'a/b/'
  // ]
});

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

  // Lists files in the bucket
  const [files] = await storage.bucket(bucketName).getFiles();

  console.log('Files:');
  files.forEach(file => {
    console.log(file.name);
  });

Example of listing files, filtered by a prefix:

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

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

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const bucketName = 'Name of a bucket, e.g. my-bucket';
  // const prefix = 'Prefix by which to filter, e.g. public/';
  // const delimiter = 'Delimiter to use, e.g. /';

  /**
   * This can be used to list all blobs in a "folder", e.g. "public/".
   *
   * The delimiter argument can be used to restrict the results to only the
   * "files" in the given "folder". Without the delimiter, the entire tree under
   * the prefix is returned. For example, given these blobs:
   *
   *   /a/1.txt
   *   /a/b/2.txt
   *
   * If you just specify prefix = '/a', you'll get back:
   *
   *   /a/1.txt
   *   /a/b/2.txt
   *
   * However, if you specify prefix='/a' and delimiter='/', you'll get back:
   *
   *   /a/1.txt
   */
  const options = {
    prefix: prefix,
  };

  if (delimiter) {
    options.delimiter = delimiter;
  }

  // Lists files in the bucket, filtered by a prefix
  const [files] = await storage.bucket(bucketName).getFiles(options);

  console.log('Files:');
  files.forEach(file => {
    console.log(file.name);
  });

getLabels(optionsopt, callbackopt) → {Promise.<GetLabelsCallback>}

Get the labels currently set on this bucket.

Parameters:
Name Type Attributes Description
options object <optional>

Configuration options.

Properties
Name Type Attributes Description
userProject string <optional>

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

callback GetLabelsCallback <optional>

Callback function.

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

bucket.getLabels(function(err, labels) {
  if (err) {
    // Error handling omitted.
  }

  // labels = {
  //   label: 'labelValue',
  //   ...
  // }
});

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

getMetadata(optionsopt, callbackopt) → {Promise.<GetBucketMetadataResponse>}

Get the bucket's metadata.

To set metadata, see Bucket#setMetadata.

Parameters:
Name Type Attributes Description
options GetBucketMetadataOptions <optional>

Configuration options.

callback GetBucketMetadataCallback <optional>

Callback function.

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

bucket.getMetadata(function(err, metadata, apiResponse) {});

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

Example of retrieving the requester pays status of a bucket:

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

  // Gets the requester-pays status of a bucket
  const [metadata] = await storage.bucket(bucketName).getMetadata();

  let status;
  if (metadata && metadata.billing && metadata.billing.requesterPays) {
    status = `enabled`;
  } else {
    status = `disabled`;
  }
  console.log(
    `Requester-pays requests are ${status} for bucket ${bucketName}.`
  );

getNotifications(optionsopt, callbackopt) → {Promise.<GetNotificationsResponse>}

Retrieves a list of notification subscriptions for a given bucket.

Parameters:
Name Type Attributes Description
options GetNotificationsOptions <optional>

Configuration options.

callback GetNotificationsCallback <optional>

Callback function.

Source:
See:
Examples
const {Storage} = require('@google-cloud/storage');
const storage = new Storage();
const bucket = storage.bucket('my-bucket');

bucket.getNotifications(function(err, notifications, apiResponse) {
  if (!err) {
    // notifications is an array of Notification objects.
  }
});

//-
// If the callback is omitted, we'll return a Promise.
//-
bucket.getNotifications().then(function(data) {
  const notifications = 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';

  // Lists notifications in the bucket
  const [notifications] = await storage.bucket(bucketName).getNotifications();

  console.log('Notifications:');
  notifications.forEach(notification => {
    console.log(notification.id);
  });

lock(metageneration, callbackopt) → {Promise.<BucketLockResponse>}

Lock a previously-defined retention policy. This will prevent changes to the policy.

Parameters:
Name Type Attributes Description
metageneration Number | String

The bucket's metageneration. This is accesssible from calling File#getMetadata.

callback BucketLockCallback <optional>

Callback function.

Source:
Throws:

if a metageneration is not provided.

Type
Error
Example
const storage = require('@google-cloud/storage')();
const bucket = storage.bucket('albums');

const metageneration = 2;

bucket.lock(metageneration, function(err, apiResponse) {});

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

makePrivate(optionsopt, callbackopt) → {Promise.<MakeBucketPrivateResponse>}

Make the bucket listing private.

You may also choose to make the contents of the bucket private by specifying includeFiles: true. This will automatically run File#makePrivate for every file in the bucket.

When specifying includeFiles: true, use force: true to delay execution of your callback until all files have been processed. By default, the callback is executed after the first error. Use force to queue such errors until all files have been processed, after which they will be returned as an array as the first argument to your callback.

NOTE: This may cause the process to be long-running and use a high number of requests. Use with caution.

Parameters:
Name Type Attributes Description
options MakeBucketPrivateOptions <optional>

Configuration options.

callback MakeBucketPrivateCallback <optional>

Callback function.

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

//-
// Make the bucket private.
//-
bucket.makePrivate(function(err) {});

//-
// Make the bucket and its contents private.
//-
const opts = {
  includeFiles: true
};

bucket.makePrivate(opts, function(err, files) {
  // `err`:
  //    The first error to occur, otherwise null.
  //
  // `files`:
  //    Array of files successfully made private in the bucket.
});

//-
// Make the bucket and its contents private, using force to suppress errors
// until all files have been processed.
//-
const opts = {
  includeFiles: true,
  force: true
};

bucket.makePrivate(opts, function(errors, files) {
  // `errors`:
  //    Array of errors if any occurred, otherwise null.
  //
  // `files`:
  //    Array of files successfully made private in the bucket.
});

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

makePublic(optionsopt, callbackopt) → {Promise.<MakeBucketPublicResponse>}

Make the bucket publicly readable.

You may also choose to make the contents of the bucket publicly readable by specifying includeFiles: true. This will automatically run File#makePublic for every file in the bucket.

When specifying includeFiles: true, use force: true to delay execution of your callback until all files have been processed. By default, the callback is executed after the first error. Use force to queue such errors until all files have been processed, after which they will be returned as an array as the first argument to your callback.

NOTE: This may cause the process to be long-running and use a high number of requests. Use with caution.

Parameters:
Name Type Attributes Description
options MakeBucketPublicOptions <optional>

Configuration options.

callback MakeBucketPublicCallback <optional>

Callback function.

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

//-
// Make the bucket publicly readable.
//-
bucket.makePublic(function(err) {});

//-
// Make the bucket and its contents publicly readable.
//-
const opts = {
  includeFiles: true
};

bucket.makePublic(opts, function(err, files) {
  // `err`:
  //    The first error to occur, otherwise null.
  //
  // `files`:
  //    Array of files successfully made public in the bucket.
});

//-
// Make the bucket and its contents publicly readable, using force to
// suppress errors until all files have been processed.
//-
const opts = {
  includeFiles: true,
  force: true
};

bucket.makePublic(opts, function(errors, files) {
  // `errors`:
  //    Array of errors if any occurred, otherwise null.
  //
  // `files`:
  //    Array of files successfully made public in the bucket.
});

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

notification(id) → {Notification}

Get a reference to a Cloud Pub/Sub Notification.

Parameters:
Name Type Description
id string

ID of notification.

Source:
See:
Example
const {Storage} = require('@google-cloud/storage');
const storage = new Storage();
const bucket = storage.bucket('my-bucket');
const notification = bucket.notification('1');

removeRetentionPeriod(callbackopt) → {Promise.<SetBucketMetadataResponse>}

Remove an already-existing retention policy from this bucket, if it is not locked.

Parameters:
Name Type Attributes Description
callback SetBucketMetadataCallback <optional>

Callback function.

Source:
Example
const storage = require('@google-cloud/storage')();
const bucket = storage.bucket('albums');

bucket.removeRetentionPeriod(function(err, apiResponse) {});

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

setLabels(labels, optionsopt, callbackopt) → {Promise.<SetLabelsResponse>}

Set labels on the bucket.

This makes an underlying call to Bucket#setMetadata, which is a PATCH request. This means an individual label can be overwritten, but unmentioned labels will not be touched.

Parameters:
Name Type Attributes Description
labels object.<string, string>

Labels to set on the bucket.

options object <optional>

Configuration options.

callback SetLabelsCallback <optional>

Callback function.

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

const labels = {
  labelone: 'labelonevalue',
  labeltwo: 'labeltwovalue'
};

bucket.setLabels(labels, function(err, metadata) {
  if (!err) {
    // Labels set successfully.
  }
});

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

setMetadata(metadata, optionsopt, callbackopt) → {Promise.<SetBucketMetadataResponse>}

Set the bucket's metadata.

Parameters:
Name Type Attributes Description
metadata object.<string, *>

The metadata you wish to set.

options SetBucketMetadataOptions <optional>

Configuration options.

callback SetBucketMetadataCallback <optional>

Callback function.

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

//-
// Set website metadata field on the bucket.
//-
const metadata = {
  website: {
    mainPageSuffix: 'http://example.com',
    notFoundPage: 'http://example.com/404.html'
  }
};

bucket.setMetadata(metadata, function(err, apiResponse) {});

//-
// Enable versioning for your bucket.
//-
bucket.setMetadata({
  versioning: {
    enabled: true
  }
}, function(err, apiResponse) {});

//-
// Enable KMS encryption for objects within this bucket.
//-
bucket.setMetadata({
  encryption: {
    defaultKmsKeyName: 'projects/grape-spaceship-123/...'
  }
}, function(err, apiResponse) {});

//-
// Set the default event-based hold value for new objects in this
// bucket.
//-
bucket.setMetadata({
  defaultEventBasedHold: true
}, function(err, apiResponse) {});

//-
// Remove object lifecycle rules.
//-
bucket.setMetadata({
  lifecycle: null
}, function(err, apiResponse) {});

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

setRetentionPeriod(duration, callbackopt) → {Promise.<SetBucketMetadataResponse>}

Lock all objects contained in the bucket, based on their creation time. Any attempt to overwrite or delete objects younger than the retention period will result in a PERMISSION_DENIED error.

An unlocked retention policy can be modified or removed from the bucket via File#removeRetentionPeriod and File#setRetentionPeriod. A locked retention policy cannot be removed or shortened in duration for the lifetime of the bucket. Attempting to remove or decrease period of a locked retention policy will result in a PERMISSION_DENIED error. You can still increase the policy.

Parameters:
Name Type Attributes Description
duration *

In seconds, the minimum retention time for all objects contained in this bucket.

callback SetBucketMetadataCallback <optional>

Callback function.

Source:
Example
const storage = require('@google-cloud/storage')();
const bucket = storage.bucket('albums');

const DURATION_SECONDS = 15780000; // 6 months.

//-
// Lock the objects in this bucket for 6 months.
//-
bucket.setRetentionPeriod(DURATION_SECONDS, function(err, apiResponse) {});

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

setStorageClass(storageClass, optionsopt, callbackopt) → {Promise}

Set the default storage class for new files in this bucket.

Parameters:
Name Type Attributes Description
storageClass string

The new storage class. (standard, nearline, coldline, or durable_reduced_availability). Note: The storage classes multi_regional and regional are now legacy and will be deprecated in the future.

options object <optional>

Configuration options.

Properties
Name Type Attributes Description
userProject string <optional>

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

callback SetStorageClassCallback <optional>

Callback function.

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

bucket.setStorageClass('nearline', function(err, apiResponse) {
  if (err) {
    // Error handling omitted.
  }

  // The storage class was updated successfully.
});

//-
// If the callback is omitted, we'll return a Promise.
//-
bucket.setStorageClass('nearline').then(function() {});

setUserProject(userProject)

Set a user project to be billed for all requests made from this Bucket object and any files referenced from this Bucket object.

Parameters:
Name Type Description
userProject string

The user project.

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

bucket.setUserProject('grape-spaceship-123');

upload(pathString, optionsopt, callbackopt) → {Promise.<UploadResponse>}

Upload a file to the bucket. This is a convenience method that wraps File#createWriteStream.

You can specify whether or not an upload is resumable by setting options.resumable. Resumable uploads are enabled by default if your input file is larger than 5 MB.

For faster crc32c computation, you must manually install fast-crc32c:

$ npm install --save fast-crc32c
Parameters:
Name Type Attributes Description
pathString string

The fully qualified path to the file you wish to upload to your bucket.

options UploadOptions <optional>

Configuration options.

callback UploadCallback <optional>

Callback function.

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

//-
// Upload a file from a local path.
//-
bucket.upload('/local/path/image.png', function(err, file, apiResponse) {
  // Your bucket now contains:
  // - "image.png" (with the contents of `/local/path/image.png')

  // `file` is an instance of a File object that refers to your new file.
});


//-
// It's not always that easy. You will likely want to specify the filename
// used when your new file lands in your bucket.
//
// You may also want to set metadata or customize other options.
//-
const options = {
  destination: 'new-image.png',
  resumable: true,
  validation: 'crc32c',
  metadata: {
    metadata: {
      event: 'Fall trip to the zoo'
    }
  }
};

bucket.upload('local-image.png', options, function(err, file) {
  // Your bucket now contains:
  // - "new-image.png" (with the contents of `local-image.png')

  // `file` is an instance of a File object that refers to your new file.
});

//-
// You can also have a file gzip'd on the fly.
//-
bucket.upload('index.html', { gzip: true }, function(err, file) {
  // Your bucket now contains:
  // - "index.html" (automatically compressed with gzip)

  // Downloading the file with `file.download` will automatically decode
the
  // file.
});

//-
// You may also re-use a File object, {File}, that references
// the file you wish to create or overwrite.
//-
const options = {
  destination: bucket.file('existing-file.png'),
  resumable: false
};

bucket.upload('local-img.png', options, function(err, newFile) {
  // Your bucket now contains:
  // - "existing-file.png" (with the contents of `local-img.png')

  // Note:
  // The `newFile` parameter is equal to `file`.
});

//-
// To use
// <a
href="https://cloud.google.com/storage/docs/encryption#customer-supplied">
// Customer-supplied Encryption Keys</a>, provide the `encryptionKey`
option.
//-
const crypto = require('crypto');
const encryptionKey = crypto.randomBytes(32);

bucket.upload('img.png', {
  encryptionKey: encryptionKey
}, function(err, newFile) {
  // `img.png` was uploaded with your custom encryption key.

  // `newFile` is already configured to use the encryption key when making
  // operations on the remote object.

  // However, to use your encryption key later, you must create a `File`
  // instance with the `key` supplied:
  const file = bucket.file('img.png', {
    encryptionKey: encryptionKey
  });

  // Or with `file#setEncryptionKey`:
  const file = bucket.file('img.png');
  file.setEncryptionKey(encryptionKey);
});

//-
// If the callback is omitted, we'll return a Promise.
//-
bucket.upload('local-image.png').then(function(data) {
  const file = data[0];
});

To upload a file from a URL, use File#createWriteStream.

Another example:

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const bucketName = 'Name of a bucket, e.g. my-bucket';
  // const filename = 'Local file to upload, e.g. ./local/path/to/file.txt';

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

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

  async function uploadFile() {
    // Uploads a local file to the bucket
    await storage.bucket(bucketName).upload(filename, {
      // Support for HTTP requests made with `Accept-Encoding: gzip`
      gzip: true,
      // By setting the option `destination`, you can change the name of the
      // object you are uploading to a bucket.
      metadata: {
        // Enable long-lived HTTP caching headers
        // Use only if the contents of the file will never change
        // (If the contents will change, use cacheControl: 'no-cache')
        cacheControl: 'public, max-age=31536000',
      },
    });

    console.log(`${filename} uploaded to ${bucketName}.`);
  }

  uploadFile();

Example of uploading an encrypted file:

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

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

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const bucketName = 'Name of a bucket, e.g. my-bucket';
  // const srcFilename = 'Local file to upload, e.g. ./local/path/to/file.txt';
  // const destFilename = 'Remote destination for file, e.g. file_encrypted.txt';

  // See the "Generating your own encryption key" section above.
  // const key = 'A base64 encoded customer-supplied key';

  const options = {
    // The path to which the file should be uploaded, e.g. "file_encrypted.txt"
    destination: destFilename,
    // Encrypt the file with a customer-supplied key.
    // See the "Generating your own encryption key" section above.
    encryptionKey: Buffer.from(key, 'base64'),
  };

  // Encrypts and uploads a local file, e.g. "./local/path/to/file.txt".
  // The file will only be retrievable using the key used to upload it.
  await storage.bucket(bucketName).upload(srcFilename, options);

  console.log(
    `File ${srcFilename} uploaded to gs://${bucketName}/${destFilename}.`
  );