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.
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
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
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 8+
In the Node.js runtimes version 8 and above, 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. | String |
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 |
Node.js 6 (Deprecated)
In the Node.js 6 runtime, your function is passed the arguments
(event, callback)
:
Property | Description | Type |
---|---|---|
event |
An object representing the event that triggered the function. | Object |
event.data |
The data object for the event. Its type depends on the event. | Object |
event.context |
The context object for the event. | Object |
event.context.eventId |
A unique ID for the event. For example: "70172329041928" . |
String |
event.context.timestamp |
The date/time this event was created. For example:
"2018-04-09T07:56:12.975Z" .
|
String (ISO 8601) |
event.context.eventType |
The type of the event. For example:
"google.pubsub.topic.publish" .
|
String |
event.context.resource |
The resource that emitted the event. | String |
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 |
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
You must signal when background functions have completed. Otherwise, your function can continue to run and be forcibly terminated by the system. You can signal function completion in each runtime as described below:
Node.js 8+
In the Node.js runtimes version 8 and above, signal function completion by either:
- Invoking the
callback
argument, - Returning a Promise,
- Wrapping your function using the
async
keyword (which causes your function to implicitly return a Promise), or - Returning a value.
If invoking the callback
argument or synchronously returning a
value, ensure that all asynchronous processes have completed first. If
returning a Promise, Cloud Functions ensures that the Promise is settled
before terminating.
The following example function returns a Promise:
Node.js 6 (Deprecated)
In the Node.js 6 runtime, signal function completion by either:
- Invoking the
callback
argument, - Returning a Promise, or
- Returning a value.
If invoking the callback
argument or synchronously returning a
value, ensure that all asynchronous processes have completed first. If
returning a Promise, Cloud Functions ensures that the Promise is settled
before terminating.
The following example function returns a Promise:
Python
In the Python runtime, signal function completion by returning a value:
Go
In the Go runtime, signal function completion by returning a value: