This simple tutorial demonstrates writing, deploying, and triggering a Background Cloud Function with a Cloud Storage trigger.
Objectives
- Write and deploy a Background Cloud Function.
- Trigger the function by uploading a file to Cloud Storage.
Costs
This tutorial uses billable components of Cloud Platform, including:
- Google Cloud Functions
- Google Cloud Storage
Use the Pricing Calculator to generate a cost estimate based on your projected usage.
New Cloud Platform users might be eligible for a free trial.Before you begin
-
Sign in to your Google Account.
If you don't already have one, sign up for a new account.
-
In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.
- Enable the Cloud Functions, Cloud Build, and Cloud Storage APIs.
- Install and initialize the Cloud SDK.
- Prepare your development environment:
If you already have the Cloud SDK installed, update it by running the following command:
gcloud components update
Preparing the application
Create a Cloud Storage bucket to upload a test file, where
YOUR_TRIGGER_BUCKET_NAME
is a globally unique bucket name:gsutil mb gs://YOUR_TRIGGER_BUCKET_NAME
Clone the sample app repository to your local machine:
Node.js
git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git
Alternatively, you can download the sample as a zip file and extract it.
Python
git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
Alternatively, you can download the sample as a zip file and extract it.
Go
git clone https://github.com/GoogleCloudPlatform/golang-samples.git
Alternatively, you can download the sample as a zip file and extract it.
Java
git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git
Alternatively, you can download the sample as a zip file and extract it.
C#
git clone https://github.com/GoogleCloudPlatform/dotnet-docs-samples.git
Alternatively, you can download the sample as a zip file and extract it.
Ruby
git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples.git
Alternatively, you can download the sample as a zip file and extract it.
Change to the directory that contains the Cloud Functions sample code:
Node.js
cd nodejs-docs-samples/functions/helloworld/
Python
cd python-docs-samples/functions/helloworld/
Go
cd golang-samples/functions/helloworld/
Java
cd java-docs-samples/functions/helloworld/hello-gcs/
C#
cd dotnet-docs-samples/functions/helloworld/HelloGcs/
Ruby
cd ruby-docs-samples/functions/helloworld/storage/
Deploying and triggering the function
Currently, Cloud Storage functions are based on Pub/Sub notifications from Cloud Storage and support similar event types:
The following sections describe how to deploy and trigger a function for each of these event types.
Object Finalize
Object finalize events trigger when a "write" of a Cloud Storage Object is successfully finalized. In particular, this means that creating a new object or overwriting an existing object triggers this event. Archive and metadata update operations are ignored by this trigger.
Object Finalize: deploying the function
Take a look at the sample function, which handles Cloud Storage events:
Node.js
Python
Go
Java
C#
Ruby
To deploy the function, run the following command in the directory where the sample code is located:
Node.js
gcloud functions deploy helloGCS \ --runtime nodejs10 \You can use the following values for the
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
--runtime
flag to specify your preferred Node.js version:
nodejs10
nodejs12
nodejs14
(public preview)
Python
gcloud functions deploy hello_gcs \ --runtime python37 \You can use the following values for the
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
--runtime
flag to specify your preferred Python version:
python37
python38
python39
(public preview)
Go
gcloud functions deploy HelloGCSInfo \ --runtime go111 \You can use the following values for the
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
--runtime
flag to specify your preferred Go version:
go111
go113
Java
gcloud functions deploy java-gcs-function \ --entry-point functions.HelloGcs \ --runtime java11 \ --memory 512MB \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
C#
gcloud functions deploy csharp-gcs-function \ --entry-point HelloGcs.Function \ --runtime dotnet3 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
Ruby
gcloud functions deploy hello_gcs --runtime ruby26 \You can use the following values for the
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
--runtime
flag to specify your preferred Ruby version:
ruby26
ruby27
where YOUR_TRIGGER_BUCKET_NAME
is the name of the
Cloud Storage bucket that triggers the function.
Object Finalize: triggering the function
To trigger the function:
Create an empty
gcf-test.txt
file in the directory where the sample code is located.Upload the file to Cloud Storage in order to trigger the function:
gsutil cp gcf-test.txt gs://YOUR_TRIGGER_BUCKET_NAME
where
YOUR_TRIGGER_BUCKET_NAME
is the name of your Cloud Storage bucket where you will upload a test file.Check the logs to make sure the executions have completed:
gcloud functions logs read --limit 50
Object Delete
Object delete events are most useful for non-versioning buckets. They are triggered when an old version of an object is deleted. In addition, they are triggered when an object is overwritten. Object delete triggers can also be used with versioning buckets, triggering when a version of an object is permanently deleted.
Object Delete: deploying the function
Using the same sample code as in the finalize example, deploy the function with object delete as the trigger event. Run the following command in the directory where the sample code is located:
Node.js
gcloud functions deploy helloGCS \ --runtime nodejs10 \You can use the following values for the
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete
--runtime
flag to specify your preferred Node.js version:
nodejs10
nodejs12
nodejs14
(public preview)
Python
gcloud functions deploy hello_gcs \ --runtime python37 \You can use the following values for the
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete
--runtime
flag to specify your preferred Python version:
python37
python38
python39
(public preview)
Go
gcloud functions deploy HelloGCSInfo \ --runtime go111 \You can use the following values for the
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete
--runtime
flag to specify your preferred Go version:
go111
go113
Java
gcloud functions deploy java-gcs-function \ --entry-point functions.HelloGcs \ --runtime java11 \ --memory 512MB \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete
C#
gcloud functions deploy csharp-gcs-function \ --entry-point HelloGcs.Function \ --runtime dotnet3 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete
Ruby
gcloud functions deploy hello_gcs --runtime ruby26 \You can use the following values for the
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete
--runtime
flag to specify your preferred Ruby version:
ruby26
ruby27
where YOUR_TRIGGER_BUCKET_NAME
is the name of the
Cloud Storage bucket that triggers the function.
Object Delete: triggering the function
To trigger the function:
Create an empty
gcf-test.txt
file in the directory where the sample code is located.Make sure that your bucket is non-versioning:
gsutil versioning set off gs://YOUR_TRIGGER_BUCKET_NAME
Upload the file to Cloud Storage:
gsutil cp gcf-test.txt gs://YOUR_TRIGGER_BUCKET_NAME
where
YOUR_TRIGGER_BUCKET_NAME
is the name of your Cloud Storage bucket where you will upload a test file. At this point the function should not execute yet.Delete the file to trigger the function:
gsutil rm gs://YOUR_TRIGGER_BUCKET_NAME/gcf-test.txt
Check the logs to make sure the executions have completed:
gcloud functions logs read --limit 50
Note that the function may take some time to finish executing.
Object Archive
Object archive events can be used only with versioning buckets. They are triggered when an old version of an object is archived. In particular, this means that when an object is overwritten or deleted, an archive event is triggered.
Object Archive: deploying the function
Using the same sample code as in the finalize example, deploy the function with object archive as the trigger event. Run the following command in the directory where the sample code is located:
Node.js
gcloud functions deploy helloGCS \ --runtime nodejs10 \You can use the following values for the
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive
--runtime
flag to specify your preferred Node.js version:
nodejs10
nodejs12
nodejs14
(public preview)
Python
gcloud functions deploy hello_gcs \ --runtime python37 \You can use the following values for the
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive
--runtime
flag to specify your preferred Python version:
python37
python38
python39
(public preview)
Go
gcloud functions deploy HelloGCSInfo \ --runtime go111 \You can use the following values for the
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive
--runtime
flag to specify your preferred Go version:
go111
go113
Java
gcloud functions deploy java-gcs-function \ --entry-point functions.HelloGcs \ --runtime java11 \ --memory 512MB \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive
C#
gcloud functions deploy csharp-gcs-function \ --entry-point HelloGcs.Function \ --runtime dotnet3 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive
Ruby
gcloud functions deploy hello_gcs --runtime ruby26 \You can use the following values for the
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive
--runtime
flag to specify your preferred Ruby version:
ruby26
ruby27
where YOUR_TRIGGER_BUCKET_NAME
is the name of the
Cloud Storage bucket that triggers the function.
Object Archive: triggering the function
To trigger the function:
Create an empty
gcf-test.txt
file in the directory where the sample code is located.Make sure that your bucket has versioning enabled:
gsutil versioning set on gs://YOUR_TRIGGER_BUCKET_NAME
Upload the file to Cloud Storage:
gsutil cp gcf-test.txt gs://YOUR_TRIGGER_BUCKET_NAME
where
YOUR_TRIGGER_BUCKET_NAME
is the name of your Cloud Storage bucket where you will upload a test file. At this point the function should not execute yet.Archive the file to trigger the function:
gsutil rm gs://YOUR_TRIGGER_BUCKET_NAME/gcf-test.txt
Watch the logs to make sure the executions have completed:
gcloud functions logs read --limit 50
Object Metadata Update
Metadata update events are triggered when the metadata of existing object is updated.
Object Metadata Update: deploying the function
Using the same sample code as in the finalize example, deploy the function with metadata update as the trigger event. Run the following command in the directory where the sample code is located:
Node.js
gcloud functions deploy helloGCS \ --runtime nodejs10 \You can use the following values for the
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate
--runtime
flag to specify your preferred Node.js version:
nodejs10
nodejs12
nodejs14
(public preview)
Python
gcloud functions deploy hello_gcs \ --runtime python37 \You can use the following values for the
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate
--runtime
flag to specify your preferred Python version:
python37
python38
python39
(public preview)
Go
gcloud functions deploy HelloGCSInfo \ --runtime go111 \You can use the following values for the
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate
--runtime
flag to specify your preferred Go version:
go111
go113
Java
gcloud functions deploy java-gcs-function \ --entry-point functions.HelloGcs \ --runtime java11 \ --memory 512MB \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate
C#
gcloud functions deploy csharp-gcs-function \ --entry-point HelloGcs.Function \ --runtime dotnet3 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate
Ruby
gcloud functions deploy hello_gcs --runtime ruby26 \You can use the following values for the
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate
--runtime
flag to specify your preferred Ruby version:
ruby26
ruby27
where YOUR_TRIGGER_BUCKET_NAME
is the name of the
Cloud Storage bucket that triggers the function.
Object Metadata Update: triggering the function
To trigger the function:
Create an empty
gcf-test.txt
file in the directory where the sample code is located.Make sure that your bucket is non-versioning:
gsutil versioning set off gs://YOUR_TRIGGER_BUCKET_NAME
Upload the file to Cloud Storage:
gsutil cp gcf-test.txt gs://YOUR_TRIGGER_BUCKET_NAME
where
YOUR_TRIGGER_BUCKET_NAME
is the name of your Cloud Storage bucket where you will upload a test file. At this point the function should not execute yet.Update the metadata of the file:
gsutil -m setmeta -h "Content-Type:text/plain" gs://YOUR_TRIGGER_BUCKET_NAME/gcf-test.txt
Watch the logs to make sure the executions have completed:
gcloud functions logs read --limit 50
Cleaning up
To avoid incurring charges to your Google Cloud account for the resources used in this tutorial, either delete the project that contains the resources, or keep the project and delete the individual resources.
Deleting the project
The easiest way to eliminate billing is to delete the project that you created for the tutorial.
To delete the project:
- In the Cloud Console, go to the Manage resources page.
- In the project list, select the project that you want to delete, and then click Delete.
- In the dialog, type the project ID, and then click Shut down to delete the project.
Deleting the Cloud Function
Deleting Cloud Functions does not remove any resources stored in Cloud Storage.
To delete the Cloud Function you created in this tutorial, run the following command:
Node.js
gcloud functions delete helloGCS
Python
gcloud functions delete hello_gcs
Go
gcloud functions delete HelloGCSInfo
Java
gcloud functions delete java-gcs-function
C#
gcloud functions delete csharp-gcs-function
Ruby
gcloud functions delete hello_gcs
You can also delete Cloud Functions from the Google Cloud Console.