Background Functions

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 Cloud 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 Cloud Pub/Sub and Cloud Storage. For more information about handling events from different sources, see Calling Cloud Functions.

Cloud Pub/Sub example

This example shows a Cloud Function triggered by Cloud Pub/Sub events. Every time a message is published to a Cloud Pub/Sub topic, the function is invoked, and a greeting using data derived from the message is written to the log.

Node.js 8/10

functions/node8/index.js

View on GitHub Feedback

/**
 * Background Cloud Function to be triggered by Pub/Sub.
 * This function is exported by index.js, and executed when
 * the trigger topic receives a message.
 *
 * @param {object} pubSubEvent The event payload.
 * @param {object} context The event metadata.
 */
exports.helloPubSub = (pubSubEvent, context) => {
  const name = pubSubEvent.data
    ? Buffer.from(pubSubEvent.data, 'base64').toString()
    : 'World';

  console.log(`Hello, ${name}!`);
};

Node.js 6 (Deprecated)

functions/helloworld/index.js

View on GitHub Feedback

/**
 * Background Cloud Function to be triggered by Pub/Sub.
 * This function is exported by index.js, and executed when
 * the trigger topic receives a message.
 *
 * @param {object} event The Cloud Functions event.
 * @param {function} callback The callback function.
 */
exports.helloPubSub = (event, callback) => {
  const pubsubMessage = event.data;
  const name = pubsubMessage.data
    ? Buffer.from(pubsubMessage.data, 'base64').toString()
    : 'World';

  console.log(`Hello, ${name}!`);

  callback();
};

Python

functions/helloworld/main.py

View on GitHub Feedback

def hello_pubsub(data, context):
    """Background Cloud Function to be triggered by Pub/Sub.
    Args:
         data (dict): The dictionary with data specific to this type of event.
         context (google.cloud.functions.Context): The Cloud Functions event
         metadata.
    """
    import base64

    if 'data' in data:
        name = base64.b64decode(data['data']).decode('utf-8')
    else:
        name = 'World'
    print('Hello {}!'.format(name))

Go

functions/helloworld/hello_pubsub.go

View on GitHub Feedback

// Package helloworld provides a set of Cloud Functions samples.
package helloworld

import (
	"context"
	"log"
)

// PubSubMessage is the payload of a Pub/Sub event.
type PubSubMessage struct {
	Data []byte `json:"data"`
}

// HelloPubSub consumes a Pub/Sub message.
func HelloPubSub(ctx context.Context, m PubSubMessage) error {
	name := string(m.Data)
	if name == "" {
		name = "World"
	}
	log.Printf("Hello, %s!", name)
	return nil
}

For more information about deploying Cloud Functions triggered by Cloud Pub/Sub events, see Cloud Pub/Sub Triggers and Cloud 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 8/10

functions/node8/index.js

View on GitHub Feedback

/**
 * Background Cloud Function to be triggered by Cloud Storage.
 *
 * @param {object} data The event payload.
 * @param {object} context The event metadata.
 */
exports.helloGCS = (data, context) => {
  const file = data;
  if (file.resourceState === 'not_exists') {
    console.log(`File ${file.name} deleted.`);
  } else if (file.metageneration === '1') {
    // metageneration attribute is updated on metadata changes.
    // on create value is 1
    console.log(`File ${file.name} uploaded.`);
  } else {
    console.log(`File ${file.name} metadata updated.`);
  }
};

Node.js 6 (Deprecated)

functions/helloworld/index.js

View on GitHub Feedback

/**
 * Background Cloud Function to be triggered by Cloud Storage.
 *
 * @param {object} event The Cloud Functions event.
 * @param {function} callback The callback function.
 */
exports.helloGCS = (event, callback) => {
  const file = event.data;

  if (file.resourceState === 'not_exists') {
    console.log(`File ${file.name} deleted.`);
  } else if (file.metageneration === '1') {
    // metageneration attribute is updated on metadata changes.
    // value is 1 if file was newly created or overwritten
    console.log(`File ${file.name} uploaded.`);
  } else {
    console.log(`File ${file.name} metadata updated.`);
  }

  callback();
};

Python

functions/helloworld/main.py

View on GitHub Feedback

def hello_gcs(data, context):
    """Background Cloud Function to be triggered by Cloud Storage.
    Args:
         data (dict): The dictionary with data specific to this type of event.
         context (google.cloud.functions.Context): The Cloud Functions
         event metadata.
    """
    print("File: {}.".format(data['objectId']))

Go

functions/helloworld/hello_cloud_storage.go

View on GitHub Feedback

// Package helloworld provides a set of Cloud Functions samples.
package helloworld

import (
	"context"
	"log"
)

// GCSEvent is the payload of a GCS event.
type GCSEvent struct {
	Bucket         string `json:"bucket"`
	Name           string `json:"name"`
	Metageneration string `json:"metageneration"`
	ResourceState  string `json:"resourceState"`
}

// HelloGCS consumes a GCS event.
func HelloGCS(ctx context.Context, e GCSEvent) error {
	if e.ResourceState == "not_exists" {
		log.Printf("File %v deleted.", e.Name)
		return nil
	}
	if e.Metageneration == "1" {
		// The metageneration attribute is updated on metadata changes.
		// The on create value is 1.
		log.Printf("File %v created.", e.Name)
		return nil
	}
	log.Printf("File %v metadata updated.", e.Name)
	return nil
}

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/10

In the Node.js 8 and Node.js 10 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.	Cloud Storage Object or PubsubMessage
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.	Cloud Storage Object or PubsubMessage
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 struct, whose type you define, which the event payload will be unmarshaled into using json.Unmarshal() . The event payload depends on the trigger for which the function was registered. The struct definition that you supply in your code must correspond to the structure of the event type. The structure for each event is documented on the corresponding event's trigger page. Note that your struct is not required to define every field contained in the payload. You might only want to use certain fields in your function, in which case you only need to define those fields in your struct. You can also rename a field (for example, when the JSON field name contains an underscore) using JSON tags on that field.	User-defined struct

The event data depends on the trigger for which the function was registered, for example, Cloud 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.

Note: The event data is not automatically logged, as it might contain confidential information that users don't want written to Stackdriver Logging. If you want to log the event data, you must do so explicitly, as described in Writing, Viewing, and Responding to Logs.

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/10

In the Node.js 8 and Node.js 10 runtimes, 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:

functions/node8/index.js

View on GitHub Feedback

const fetch = require('node-fetch');

/**
 * Background Cloud Function that returns a Promise. Note that we don't pass
 * a "callback" argument to the function.
 *
 * @param {object} data The Cloud Functions event data.
 * @returns {Promise}
 */
exports.helloPromise = data => {
  return fetch(data.endpoint);
};

The following example function does not use asynchronous calls, so it can return a value synchronously:

functions/node8/index.js

View on GitHub Feedback

/**
 * Background Cloud Function that returns synchronously. Note that we don't pass
 * a "callback" argument to the function.
 *
 * @param {object} data The Cloud Functions event data.
 */
exports.helloSynchronous = data => {
  // This function returns synchronously
  if (data.something === true) {
    return 'Something is true!';
  } else {
    throw new Error('Something was not true!');
  }
};

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:

functions/background/index.js

View on GitHub Feedback

const requestPromiseNative = require('request-promise-native');

/**
 * Background Cloud Function that returns a Promise. Note that we don't pass
 * a "callback" argument to the function.
 *
 * @param {object} event The Cloud Functions event.
 * @param {object} event.data The event data.
 * @returns {Promise}
 */
exports.helloPromise = event => {
  return requestPromiseNative({
    uri: event.data.endpoint,
  });
};

The following example function does not use asynchronous calls, so it can return a value synchronously:

functions/background/index.js

View on GitHub Feedback

/**
 * Background Cloud Function that returns synchronously. Note that we don't pass
 * a "callback" argument to the function.
 *
 * @param {object} event The Cloud Functions event.
 * @param {object} event.data The event data.
 */
exports.helloSynchronous = event => {
  // This function returns synchronously
  if (event.data.something === true) {
    return 'Something is true!';
  } else {
    throw new Error('Something was not true!');
  }
};

Python

In the Python runtime, signal function completion by returning a value:

functions/helloworld/main.py

View on GitHub Feedback

def hello_background(data, context):
    """Background Cloud Function.
    Args:
         data (dict): The dictionary with data specific to the given event.
         context (google.cloud.functions.Context): The Cloud Functions event
         metadata.
    """
    if data and 'name' in data:
        name = data['name']
    else:
        name = 'World'
    return 'Hello {}!'.format(name)

Go

In the Go runtime, signal function completion by returning a value:

functions/helloworld/hello_pubsub.go

View on GitHub Feedback

// Package helloworld provides a set of Cloud Functions samples.
package helloworld

import (
	"context"
	"log"
)

// PubSubMessage is the payload of a Pub/Sub event.
type PubSubMessage struct {
	Data []byte `json:"data"`
}

// HelloPubSub consumes a Pub/Sub message.
func HelloPubSub(ctx context.Context, m PubSubMessage) error {
	name := string(m.Data)
	if name == "" {
		name = "World"
	}
	log.Printf("Hello, %s!", name)
	return nil
}

Next steps

• Deploying Cloud Functions.
• Calling Cloud Pub/Sub Trigger Functions.
• Calling Cloud Storage Trigger Functions.
• Cloud Functions with Cloud Pub/Sub Tutorial.
• Cloud Functions with Cloud Storage Tutorial.