You use background functions when you want to have your Cloud Function invoked indirectly in response to an event, such as a message on a Pub/Sub topic, a change in a Cloud Storage bucket, or a Firebase event.
For information on how to retry background functions, see Retrying Background Functions.
Supporting Runtimes
The following runtimes support Background Functions:
Language | Versions |
---|---|
Node.js | All |
Python | All |
Go | All |
Java | All |
Sample usage
The examples below show how to process events from Pub/Sub and Cloud Storage. For more information about handling events from different sources, see Calling Cloud Functions.
Pub/Sub example
This example shows a Cloud Function triggered by Pub/Sub events. Every time a message is published to a Pub/Sub topic, the function is invoked, and a greeting using data derived from the message is written to the log.
Node.js
Python
Go
Java
C#
Ruby
For more information about deploying Cloud Functions triggered by Pub/Sub events, see Pub/Sub Triggers and Pub/Sub Tutorial.
Cloud Storage example
This example shows a Cloud Function triggered by Cloud Storage events. Every time an object is created in a Cloud Storage bucket, the function is invoked, and a message about the change is written to the log.
Node.js
Python
Go
Java
C#
Ruby
For more information about deploying Cloud Functions triggered by Cloud Storage events, see Cloud Storage Triggers and Cloud Storage Tutorial.
Function parameters
Background functions are passed arguments holding data associated with the event that triggered the function's execution. The parameters of background functions are described below:
Node.js
In the Node.js runtimes, your function is passed the
arguments (data, context, callback)
:
Property | Description | Type |
---|---|---|
data |
The data object for the event. Its type depends on the event. | Object |
context |
The context object for the event. | Object |
context.eventId |
A unique ID for the event. For example: "70172329041928" . |
String |
context.timestamp |
The date/time this event was created. For example:
"2018-04-09T07:56:12.975Z" .
|
String (ISO 8601) |
context.eventType |
The type of the event. For example:
"google.pubsub.topic.publish" .
|
String |
context.resource |
The resource that emitted the event. | Object |
callback |
A callback to signal completion of the function's execution. Follows the "errback" convention, which interprets the first argument as an error: callback(); // Success callback(null, 'Success!'); // Success callback(1); // Error callback(new Error('Failed')); // Error |
Function |
Python
In the Python runtime, your function is passed the arguments
(data, context)
:
Property | Description | Type |
---|---|---|
data |
A dictionary containing the data for the event. Its format depends on the event. | Cloud Storage Object or PubsubMessage |
context |
The context object for the event. | Context |
context.event_id |
A unique ID for the event. For example: "70172329041928" . |
String |
context.timestamp |
The date/time this event was created. For example:
"2018-04-09T07:56:12.975Z" .
|
String (ISO 8601) |
context.event_type |
The type of the event. For example:
"google.pubsub.topic.publish" .
|
String |
context.resource |
The resource that emitted the event. | String |
Go
In the Go runtime, your function is passed the arguments
(ctx, Event)
:
Property | Description | Type |
---|---|---|
ctx |
A context.Context value which carries metadata about the
event. You can retrieve the metadata using the
cloud.google.com/go/functions/metadata
package.
|
context.Context
|
Event |
A
The
Note that your |
User-defined struct |
Java
In the Java runtime, your function is passed the parameters (event, context)
. There are two varieties of background functions, BackgroundFunction<T>
and RawBackgroundFunction
:
Property | Description | Type |
---|---|---|
event |
The payload of the event. The contents of the payload depend on the trigger for which the function was registered.
For BackgroundFunction<T> , the type of this parameter is T , which is a user-defined class. The JSON payload of the event is deserialized into an instance of this class using Gson.fromJson .
For RawBackgroundFunction , the type of this parameter is String , and it is the JSON payload of the event.
|
User-defined, or String
|
context |
A read-only Context object which carries metadata about the event.
|
Context
|
C#
In the .NET Core 3.1 runtime, there are two varieties of CloudEvent functions: ICloudEvent<T>
and ICloudEvent
(otherwise known as an untyped CloudEvent function).
If you implement ICloudEvent<T>
, your function is passed
the parameters (cloudEvent, data, cancellationToken)
. If you
implement ICloudEvent
, your function is passed the parameters
(cloudEvent, cancellationToken)
.
Property | Description |
---|---|
cloudEvent |
The CloudEvent that triggered the function, containing metadata about the event as well as the raw data. |
data |
The data extracted from the event, of type T where T is the type argument of your function. This parameter is not part of untyped CloudEvent functions.
|
cancellationToken |
A cancellation token to observe for the request being aborted. |
Ruby
In the Ruby runtime, CloudEvent functions are passed a single parameter, a CloudEvent object of type CloudEvents::Event::V1
. The properties on this object include:
Property | Description | Type |
---|---|---|
id |
A unique ID for the event. For example: 70172329041928 .
|
String
|
time |
The date/time this event was created. | DateTime |
type |
The type of the event. For example: google.cloud.pubsub.topic.v1.messagePublished . |
String |
source |
The resource that emitted the event. For example: //pubsub.googleapis.com/projects/sample-project/topics/gcf-test .
|
URI
|
data |
The data object for the event. It is a hash whose keys depend on the event. | Hash |
The event data depends on the trigger for which the function was registered,
for example, Pub/Sub or Cloud Storage. In the case of
direct-triggered functions, triggered using the gcloud functions call
command, the event data contains the message you sent directly.
Terminating background functions
If a function creates background tasks (such as threads, futures, Promises, callbacks, or system processes), you must terminate or otherwise resolve these tasks before returning from your function. Tasks not terminated prior to returning from a particular execution may not complete, and may also cause undefined behavior.
Node.js runtimes allow your functions to provide references to in-progress tasks and ask Cloud Functions itself to wait for them. It can do this in one of the following ways:
- Return a
Promise
that resolves once the function is complete. - Invoke the
callback
argument in a callback function upon completion.
Next steps
- Deploying Cloud Functions.
- Calling Pub/Sub Trigger Functions.
- Calling Cloud Storage Trigger Functions.
- Cloud Functions with Pub/Sub Tutorial.
- Cloud Functions with Cloud Storage Tutorial.