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

functions/helloworld/index.js 
/**
 * 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} message The Pub/Sub message.
 * @param {object} context The event metadata.
 */
exports.helloPubSub = (message, context) => {
  const name = message.data
    ? Buffer.from(message.data, 'base64').toString()
    : 'World';

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

Python

functions/helloworld/main.py 
def hello_pubsub(event, context):
    """Background Cloud Function to be triggered by Pub/Sub.
    Args:
         event (dict):  The dictionary with data specific to this type of
         event. The `data` field contains the PubsubMessage message. The
         `attributes` field will contain custom attributes if there are any.
         context (google.cloud.functions.Context): The Cloud Functions event
         metadata. The `event_id` field contains the Pub/Sub message ID. The
         `timestamp` field contains the publish time.
    """
    import base64

    print("""This Function was triggered by messageId {} published at {}
    """.format(context.event_id, context.timestamp))

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

Go

functions/helloworld/hello_pubsub.go 

// 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) // Automatically decoded from base64.
	if name == "" {
		name = "World"
	}
	log.Printf("Hello, %s!", name)
	return nil
}

Java

functions/helloworld/hello-pubsub/src/main/java/functions/HelloPubSub.java 

import com.google.cloud.functions.BackgroundFunction;
import com.google.cloud.functions.Context;
import functions.eventpojos.PubSubMessage;
import java.nio.charset.StandardCharsets;
import java.util.Base64;
import java.util.logging.Level;
import java.util.logging.Logger;

public class HelloPubSub implements BackgroundFunction<PubSubMessage> {
  private static final Logger logger = Logger.getLogger(HelloPubSub.class.getName());

  @Override
  public void accept(PubSubMessage message, Context context) {
    String name = "world";
    if (message != null && message.getData() != null) {
      name = new String(
          Base64.getDecoder().decode(message.getData().getBytes(StandardCharsets.UTF_8)),
          StandardCharsets.UTF_8);
    }
    logger.info(String.format("Hello %s!", name));
    return;
  }
}

C#

functions/helloworld/HelloPubSub/Function.cs 
using CloudNative.CloudEvents;
using Google.Cloud.Functions.Framework;
using Google.Events.Protobuf.Cloud.PubSub.V1;
using Microsoft.Extensions.Logging;
using System.Threading;
using System.Threading.Tasks;

namespace HelloPubSub
{
    public class Function : ICloudEventFunction<MessagePublishedData>
    {
        private readonly ILogger _logger;

        public Function(ILogger<Function> logger) =>
            _logger = logger;

        public Task HandleAsync(CloudEvent cloudEvent, MessagePublishedData data, CancellationToken cancellationToken)
        {
            string nameFromMessage = data.Message?.TextData;
            string name = string.IsNullOrEmpty(nameFromMessage) ? "world" : nameFromMessage;
            _logger.LogInformation("Hello {name}", name);
            return Task.CompletedTask;
        }
    }
}

Ruby

functions/helloworld/pubsub/app.rb 
require "functions_framework"
require "base64"

FunctionsFramework.cloud_event "hello_pubsub" do |event|
  # The event parameter is a CloudEvents::Event::V1 object.
  # See https://cloudevents.github.io/sdk-ruby/latest/CloudEvents/Event/V1.html
  name = Base64.decode64 event.data["message"]["data"] rescue "World"

  # A cloud_event function does not return a response, but you can log messages
  # or cause side effects such as sending additional events.
  logger.info "Hello, #{name}!"
end

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

functions/helloworld/index.js 
/**
 * Generic background Cloud Function to be triggered by Cloud Storage.
 *
 * @param {object} file The Cloud Storage file metadata.
 * @param {object} context The event metadata.
 */
exports.helloGCS = (file, context) => {
  console.log(`  Event: ${context.eventId}`);
  console.log(`  Event Type: ${context.eventType}`);
  console.log(`  Bucket: ${file.bucket}`);
  console.log(`  File: ${file.name}`);
  console.log(`  Metageneration: ${file.metageneration}`);
  console.log(`  Created: ${file.timeCreated}`);
  console.log(`  Updated: ${file.updated}`);
};

Python

functions/helloworld/main.py 
def hello_gcs(event, context):
    """Background Cloud Function to be triggered by Cloud Storage.
       This generic function logs relevant data when a file is changed.

    Args:
        event (dict):  The dictionary with data specific to this type of event.
                       The `data` field contains a description of the event in
                       the Cloud Storage `object` format described here:
                       https://cloud.google.com/storage/docs/json_api/v1/objects#resource
        context (google.cloud.functions.Context): Metadata of triggering event.
    Returns:
        None; the output is written to Stackdriver Logging
    """

    print('Event ID: {}'.format(context.event_id))
    print('Event type: {}'.format(context.event_type))
    print('Bucket: {}'.format(event['bucket']))
    print('File: {}'.format(event['name']))
    print('Metageneration: {}'.format(event['metageneration']))
    print('Created: {}'.format(event['timeCreated']))
    print('Updated: {}'.format(event['updated']))

Go

functions/helloworld/hello_cloud_storage.go 

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

import (
	"context"
	"fmt"
	"log"
	"time"

	"cloud.google.com/go/functions/metadata"
)

// GCSEvent is the payload of a GCS event.
type GCSEvent struct {
	Kind                    string                 `json:"kind"`
	ID                      string                 `json:"id"`
	SelfLink                string                 `json:"selfLink"`
	Name                    string                 `json:"name"`
	Bucket                  string                 `json:"bucket"`
	Generation              string                 `json:"generation"`
	Metageneration          string                 `json:"metageneration"`
	ContentType             string                 `json:"contentType"`
	TimeCreated             time.Time              `json:"timeCreated"`
	Updated                 time.Time              `json:"updated"`
	TemporaryHold           bool                   `json:"temporaryHold"`
	EventBasedHold          bool                   `json:"eventBasedHold"`
	RetentionExpirationTime time.Time              `json:"retentionExpirationTime"`
	StorageClass            string                 `json:"storageClass"`
	TimeStorageClassUpdated time.Time              `json:"timeStorageClassUpdated"`
	Size                    string                 `json:"size"`
	MD5Hash                 string                 `json:"md5Hash"`
	MediaLink               string                 `json:"mediaLink"`
	ContentEncoding         string                 `json:"contentEncoding"`
	ContentDisposition      string                 `json:"contentDisposition"`
	CacheControl            string                 `json:"cacheControl"`
	Metadata                map[string]interface{} `json:"metadata"`
	CRC32C                  string                 `json:"crc32c"`
	ComponentCount          int                    `json:"componentCount"`
	Etag                    string                 `json:"etag"`
	CustomerEncryption      struct {
		EncryptionAlgorithm string `json:"encryptionAlgorithm"`
		KeySha256           string `json:"keySha256"`
	}
	KMSKeyName    string `json:"kmsKeyName"`
	ResourceState string `json:"resourceState"`
}

// HelloGCS consumes a GCS event.
func HelloGCS(ctx context.Context, e GCSEvent) error {
	meta, err := metadata.FromContext(ctx)
	if err != nil {
		return fmt.Errorf("metadata.FromContext: %v", err)
	}
	log.Printf("Event ID: %v\n", meta.EventID)
	log.Printf("Event type: %v\n", meta.EventType)
	log.Printf("Bucket: %v\n", e.Bucket)
	log.Printf("File: %v\n", e.Name)
	log.Printf("Metageneration: %v\n", e.Metageneration)
	log.Printf("Created: %v\n", e.TimeCreated)
	log.Printf("Updated: %v\n", e.Updated)
	return nil
}

Java

functions/helloworld/hello-gcs/src/main/java/functions/HelloGcs.java 
import com.google.cloud.functions.BackgroundFunction;
import com.google.cloud.functions.Context;
import functions.eventpojos.GcsEvent;
import java.util.logging.Logger;

public class HelloGcs implements BackgroundFunction<GcsEvent> {
  private static final Logger logger = Logger.getLogger(HelloGcs.class.getName());

  @Override
  public void accept(GcsEvent event, Context context) {
    logger.info("Event: " + context.eventId());
    logger.info("Event Type: " + context.eventType());
    logger.info("Bucket: " + event.getBucket());
    logger.info("File: " + event.getName());
    logger.info("Metageneration: " + event.getMetageneration());
    logger.info("Created: " + event.getTimeCreated());
    logger.info("Updated: " + event.getUpdated());
  }
}

C#

functions/helloworld/HelloGcs/Function.cs 
using CloudNative.CloudEvents;
using Google.Cloud.Functions.Framework;
using Google.Events.Protobuf.Cloud.Storage.V1;
using Microsoft.Extensions.Logging;
using System.Threading;
using System.Threading.Tasks;

namespace HelloGcs
{
    public class Function : ICloudEventFunction<StorageObjectData>
    {
        private readonly ILogger _logger;

        public Function(ILogger<Function> logger) =>
            _logger = logger;

        public Task HandleAsync(CloudEvent cloudEvent, StorageObjectData data, CancellationToken cancellationToken)
        {
            _logger.LogInformation("Event: {event}", cloudEvent.Id);
            _logger.LogInformation("Event Type: {type}", cloudEvent.Type);
            _logger.LogInformation("Bucket: {bucket}", data.Bucket);
            _logger.LogInformation("File: {file}", data.Name);
            _logger.LogInformation("Metageneration: {metageneration}", data.Metageneration);
            _logger.LogInformation("Created: {created:s}", data.TimeCreated?.ToDateTimeOffset());
            _logger.LogInformation("Updated: {updated:s}", data.Updated?.ToDateTimeOffset());
            return Task.CompletedTask;
        }
    }
}

Ruby

functions/helloworld/storage/app.rb 
require "functions_framework"

FunctionsFramework.cloud_event "hello_gcs" do |event|
  # The event parameter is a CloudEvents::Event::V1 object.
  # See https://cloudevents.github.io/sdk-ruby/latest/CloudEvents/Event/V1.html
  payload = event.data

  logger.info "Event: #{event.id}"
  logger.info "Event Type: #{event.type}"
  logger.info "Bucket: #{payload['bucket']}"
  logger.info "File: #{payload['name']}"
  logger.info "Metageneration: #{payload['metageneration']}"
  logger.info "Created: #{payload['timeCreated']}"
  logger.info "Updated: #{payload['updated']}"
end

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

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