Cloud Storage triggers

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.

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:

Important: Distance between the location of a Cloud Storage bucket and the location
of the function can create significant network latency. To optimize performance,
consider specifying the function location where
applicable.

Cloud Storage supports these events:

onArchive Only sent when a bucket has enabled object versioning. This event indicates that the live version of an object has become an archived version, either because it was archived or because it was overwritten by the upload of an object of the same name.

onDelete Sent when an object has been permanently deleted. This includes objects that are overwritten or are deleted as part of the bucket's lifecycle configuration. For buckets with object versioning enabled, this is not sent when an object is archived (see onArchive), even if archival occurs via the storage.objects.delete method.

onFinalize Sent when a new object (or a new generation of an existing object) is successfully created in the bucket. This includes copying or rewriting an existing object. A failed upload does not trigger this event.

onMetadataUpdate Sent when the metadata of an existing object changes.

Set the event within the on event handler as shown above for onFinalize.

Access Storage object attributes

Cloud Functions exposes a number of Storage object attributes such as
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 attribute is incremented whenever there's a change to the
object's metadata. For new objects, the metageneration value is 1.

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

// Exit if this is triggered on a file that is not an image.
if (!contentType.startsWith('image/')) {
return console.log('This is not an image.');
}
// Get the file name.
const fileName = path.basename(filePath);
// Exit if the image is already a thumbnail.
if (fileName.startsWith('thumb_')) {
return console.log('Already a Thumbnail.');
}

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:

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: