Pub/Sub triggers

In Cloud Functions, a Pub/Sub trigger enables a function to be called in response to Pub/Sub messages. When you specify a Pub/Sub trigger for a function, you also specify a Pub/Sub topic. Your function will be called whenever a message is published to the specified topic.

For a function to use a Pub/Sub trigger, it must be implemented as an event-driven function:

• If you use a CloudEvent function, the Pub/Sub event data is passed to your function in the CloudEvents format and the CloudEvent data payload is of type MessagePublishedData.

• If you use a background function, the Pub/Sub event data payload is passed directly to your function in the PubsubMessage format.

The Google Events repository contains additional resources for working with event data.

Note: In Cloud Functions (2nd gen), Pub/Sub triggers are implemented as a particular type of Eventarc trigger.

Deployment

You can specify a Pub/Sub trigger when you deploy a function. See Deploy a Cloud Function for general instructions on how to deploy a function, and see below for additional information specific to configuring Pub/Sub triggers during deployment.

gcloud

If you are deploying using the gcloud CLI, the flags shown below are used to configure Pub/Sub triggers:

gcloud functions deploy YOUR_FUNCTION_NAME \
--trigger-topic=YOUR_PUBSUB_TOPIC \
[--retry] \
...

• The --trigger-topic flag specifies the Pub/Sub topic that the trigger will monitor. Messages published to this topic will trigger calls to your function.
• The --retry flag controls whether failed function calls are automatically retried. See Retrying event-driven functions for more information.

Legacy Pub/Sub events

Legacy functions in Cloud Functions (1st gen) use a different event type for Pub/Sub triggers:

gcloud functions deploy YOUR_FUNCTION_NAME \
--trigger-event=providers/cloud.pubsub/eventTypes/topic.publish \
--trigger-resource=YOUR_PUBSUB_TOPIC \
...

This event type is supported for legacy functions already consuming these events. However, we recommend using the --trigger-topic flag instead, as the legacy event type might be removed at a future date.

Console

If you are deploying using the Google Cloud console, you can configure a Pub/Sub trigger in the Trigger section.

• For Cloud Functions (2nd gen):

  1. Click Add Eventarc trigger to add an event trigger. This opens the Eventarc trigger pane.
  2. In the Event provider field, select Cloud Pub/Sub.
  3. In the Event field, select google.cloud.pubsub.topic.v1.messagePublished.
  4. In the Select a Cloud Pub/Sub topic field, select a topic for the trigger to monitor. Messages published to this topic will trigger calls to your function.
  5. Select or deselect the Retry on failure checkbox to control whether failed function calls are automatically retried. See Retrying event-driven functions for more information.
  6. Click Save trigger.
  Note: In Cloud Functions (2nd gen), you can also configure the location and service account used by the created Eventarc trigger. See Eventarc triggers for more information.

• For Cloud Functions (1st gen):

  1. In the Trigger type field, select Cloud Pub/Sub.
  2. In the Select a Cloud Pub/Sub topic field, select a topic for the trigger to monitor. Messages published to this topic will trigger calls to your function.
  3. Select or deselect the Retry on failure checkbox to control whether failed function calls are automatically retried. See Retrying event-driven functions for more information.

Next steps

• Learn how to write event-driven functions.
• Learn how to deploy a Cloud Function.
• See the Pub/Sub function tutorial for an example of writing, deploying, and calling a function with a Pub/Sub trigger.