Extend Cloud Storage with Cloud Functions

You can trigger a function in response to the uploading, updating, or deleting of files and folders in Cloud Storage.

Examples in this page are based on a sample function that triggers when image files are uploaded to Cloud Storage. This sample function demonstrates how to access event attributes, how to download a file to a Cloud Functions instance, and other fundamentals of handling Cloud Storage events.

For more examples of use cases, see What can I do with Cloud Functions?

Trigger a function on Cloud Storage changes

Use functions.storage to create a function that handles Cloud Storage events. Depending on whether you want to scope your function to a specific Cloud Storage bucket or use the default bucket, use one of the following:

• functions.storage.object() to listen for object changes on the default storage bucket.
• functions.storage.bucket(‘bucketName’).object() to listen for object changes on a specific bucket.

For example, the thumbnail generator sample is scoped to the default bucket for the project:

exports.generateThumbnail = functions.storage.object().onChange(event => {
  // ...
});

Cloud Storage supports the change event. This event is triggered whenever an object within your GCS bucket changes; for example, when an object is created, modified, or deleted. Set the change event within the on event handler as shown above.

Detect resourceState and other event attributes

Cloud Functions exposes a number of event attributes such as a timestamp and resource for the change, and size and contentType for the file updated. The resourceState attribute for an event has the value "exists" (for object creation and updates) or"not_exists" (for object deletion and moves). The resourceState attribute should be paired with the 'metageneration' attribute if you want to know if an object was just created. The metageneration attributed is incremented whenever there's a change to the object's metadata. For new objects, the metageneration value is 1.

const object = event.data; // The Storage object.

const fileBucket = object.bucket; // The Storage bucket that contains the file.
const filePath = object.name; // File path in the bucket.
const contentType = object.contentType; // File content type.
const resourceState = object.resourceState; // The resourceState is 'exists' or 'not_exists' (for file/folder deletions).
const metageneration = object.metageneration; // Number of times metadata has been generated. New objects have a value of 1.
index.js

The thumbnail generation sample uses some of these attributes to detect exit cases in which the function returns, including deletion events:

// Exit if this is triggered on a file that is not an image.
if (!contentType.startsWith('image/')) {
  console.log('This is not an image.');
  return;
}

// Get the file name.
const fileName = filePath.split('/').pop();
// Exit if the image is already a thumbnail.
if (fileName.startsWith('thumb_')) {
  console.log('Already a Thumbnail.');
  return;
}

// Exit if this is a move or deletion event.
if (resourceState === 'not_exists') {
  console.log('This is a deletion event.');
  return;
}

// Exit if file exists but is not new and is only being triggered
// because of a metadata change.
if (resourceState === 'exists' && metageneration > 1) {
  console.log('This is a metadata change event.');
  return;
}
index.js

Download, transform, and upload a file

For some cases, it may not be necessary to download files from Cloud Storage. However, to perform intensive tasks such as generating a thumbnail image from a file stored in Cloud Storage, you need to download files to the functions instance—that is, the virtual machine that runs your code.

To easily download and re-upload objects to Cloud Storage, install the Google Cloud Storage package using npm install --save @google-cloud/storage, and import it. To use JavaScript promises to handle external processes like the thumbnail processing tasks in the sample, also import child-process-promise:

const functions = require('firebase-functions');
const gcs = require('@google-cloud/storage')();
const spawn = require('child-process-promise').spawn;
index.js

Use gcs.bucket.file(filePath).download to download a file to a temporary directory on your Cloud Functions instance. In this location, you can process the file as needed and then upload to Cloud Storage. When performing asynchronous tasks, make sure you return a JavaScript promise in your callback.

Example: image transformation

Cloud Functions provides an image-processing program called ImageMagick that can perform manipulations on graphical image files. The following is an example of how to create a thumbnail image for an uploaded image file:

// Download file from bucket.
const bucket = gcs.bucket(fileBucket);
const tempFilePath = `/tmp/${fileName}`;
return bucket.file(filePath).download({
  destination: tempFilePath
}).then(() => {
  console.log('Image downloaded locally to', tempFilePath);
  // Generate a thumbnail using ImageMagick.
  return spawn('convert', [tempFilePath, '-thumbnail', '200x200>', tempFilePath]).then(() => {
    console.log('Thumbnail created at', tempFilePath);
    // We add a 'thumb_' prefix to thumbnails file name. That's where we'll upload the thumbnail.
    const thumbFilePath = filePath.replace(/(\/)?([^\/]*)$/, '$1thumb_$2');
    // Uploading the thumbnail.
    return bucket.upload(tempFilePath, {
      destination: thumbFilePath
    });
  });
});
index.js

This code executes the ImageMagick command line program convert to create a 200x200 thumbnail for the image saved in a temporary directory, then uploads it back to Cloud Storage.

Explore more examples

More examples of common media transformation functions including transcoding images, moderating content, extracting EXIF metadata. The full list of examples is available on GitHub.

See the full Google Cloud Storage trigger documentation for more information.