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 Google Cloud Pub/Sub topic, a change in a Google Cloud Storage bucket, or a Firebase event.

For information on how to retry background functions, see Retrying Background Functions.

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 6

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

Node.js 8 (Beta)

In the Node.js 8 runtime, 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

Python (Beta)

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

The contents of the event's data object depend on the trigger for which the function was registered, for example, Cloud Pub/Sub or Cloud Storage. In the case of direct-triggered functions, those 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 6

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:

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:

/**
 * 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!');
  }
};

Node.js 8 (Beta)

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

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} data The Cloud Functions event data.
 * @returns {Promise}
 */
exports.helloPromise = data => {
  return requestPromiseNative({
    uri: data.endpoint,
  });
};

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

/**
 * 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!');
  }
};

Python (Beta)

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

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)

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 Pub/Sub message is written to the log.

Node.js 6

/**
 * 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();
};

Node.js 8 (Beta)

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

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

Python (Beta)

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

For more information about deploying Cloud Functions triggered by Cloud Pub/Sub events, see Google 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 6

/**
 * 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();
};

Node.js 8 (Beta)

/**
 * 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.`);
  }
};

Python (Beta)

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']))

For more information about deploying Cloud Functions triggered by Cloud Storage events, see Cloud Storage Triggers and Cloud Storage Tutorial.

Migrating background functions from Node.js 6 to Node.js 8

The signature for background functions has changed between the Node.js 6 and the Node.js 8 runtimes. This section explains the change and provides a guide for migrating existing background functions that use the Node.js 6 runtime.

An example Node.js 6 background function might look as follows:

exports.nodeJS6BackgroundFunction = (event, callback) => {
  let data = event.data;
  let context = event.context;
  // ... the rest of your function
};

Note that the event argument contains data and context properties. In the Node.js 8 runtime, the data and context properties have been extracted from the event object and are now included as part of the function signature:

exports.nodeJS8BackgroundFunction = (data, context, callback) => {
  // ... the rest of your function is unchanged
};

This change simplifies references to the data and context objects previously contained within the event argument. For more information, see Background function parameters.

Next steps

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Functions Documentation