Google Cloud Pub/Sub Triggers
Cloud Functions uses event-driven functions to handle events from your Cloud infrastructure. For example, Cloud Functions can be triggered by messages published to Pub/Sub topics in the same Cloud project as the function. Pub/Sub is a globally distributed message bus that automatically scales as you need it and provides a foundation for building your own robust, global services.
Event types
There is a single Pub/Sub event used by Cloud Functions, and it
has the trigger type value google.pubsub.topic.publish
.
This event is sent when a message is published to a Pub/Sub topic that is specified when a function is deployed. Every message published to this topic will trigger function execution with message contents passed as input data.
Event structure
Cloud Functions triggered from a Pub/Sub topic will
be sent events conforming to the PubsubMessage
type, with
the caveat that publishTime
and messageId
are not directly available in the
PubsubMessage
. Instead, you can access publishTime
and messageId
via the
event ID and timestamp properties of the event metadata. This metadata is
accessible via the context object
that is passed to your function when it is invoked.
The payload of the PubsubMessage
object, the data published to the topic, is
stored as a base64-encoded string in the data
attribute of the
PubsubMessage
. To extract the payload of the PubsubMessage
object,
you may need to decode the data attribute as shown in the examples below.
Sample code
Node.js
Python
Go
Java
Kotlin
C#
Ruby
PHP
Publishing a message from within a function
You can also publish a message to a Pub/Sub topic from within a function. This lets you trigger subsequent Cloud Function invocations using Cloud Pub/Sub messages. You can use this technique to:
- Chain sequential function calls together.
- Distribute (or "fan out") groups of tasks in parallel across multiple Cloud Function instances.
In the following example, an HTTP publish
function sends a message to a
Pub/Sub topic, and that in turn triggers a subscribe
function.
This snippet shows the publish
function that publishes a message to a Pub/Sub
topic.
Node.js
Python
Go
Java
This snippet shows the subscribe
function that is triggered when the message
is published to the Pub/Sub topic:
Node.js
Python
Java
In production, you might use the cURL command-line utility to invoke the
publish
function, as follows:
curl https://GCF_REGION-GCP_PROJECT_ID.cloudfunctions.net/publish -X POST -d "{\"topic\": \"PUBSUB_TOPIC\", \"message\":\"YOUR_MESSAGE\"}" -H "Content-Type: application/json"
But for testing and debugging, you could instead use the gcloud functions call
command to
call the function directly.
The following steps describe how to run the above example using the
gcloud functions call
command:
Create a Pub/Sub topic, where
MY_TOPIC
is the name of the new topic you are creating:gcloud pubsub topics create MY_TOPIC
Deploy the
publish
function, whereRUNTIME
is the name of the runtime you are using, such asnodejs8
:gcloud functions deploy publish --trigger-http --runtime RUNTIME
Deploy the
subscribe
function:gcloud functions deploy subscribe --trigger-topic MY_TOPIC --runtime RUNTIME
Directly invoke the
publish
function using thegcloud functions call
command, and supply the required data as JSON in the--data
argument:gcloud functions call publish --data '{"topic":"MY_TOPIC","message":"Hello World!"}'
Check the logs for the
subscribe
function. Note that it may take a few minutes for your results to appear in the log:gcloud functions logs read subscribe
You should see output resembling the following:
D ...Function execution started I ...{"data":{"message":"Hello World!"}} D ...Function execution took 753 ms, finished with status: 'ok'
Deploying your function
The following gcloud
command deploys a function that will be triggered when a
message is published to a Pub/Sub topic:
gcloud functions deploy FUNCTION_NAME --entry-point ENTRY_POINT --trigger-topic TOPIC_NAME FLAGS...
Argument | Description |
---|---|
FUNCTION_NAME |
The registered name of the Cloud Function you are deploying.
This can either be the name of a function in your
source code, or an arbitrary string. If FUNCTION_NAME
is an arbitrary string, then you must include the
--entry-point flag.
|
--entry-point ENTRY_POINT |
The name of a function or class in your source code. Optional, unless
you did not use FUNCTION_NAME to specify the
function in your source code to be executed during deployment. In that
case, you must use --entry-point to supply the name of the
executable function.
|
--trigger-topic TOPIC_NAME |
The name of the Pub/Sub topic to which the function is subscribed. If the topic doesn't exist, it is created during deployment. |
FLAGS... |
Additional flags you must specify during deployment, such as
--runtime . For a full reference, see the
gcloud functions deploy
documentation.
|
See the Pub/Sub Tutorial for a complete example of how to use Pub/Sub triggers.
Legacy Cloud Pub/Sub triggers
The gcloud
command below deploys a function that is triggered by legacy
Pub/Sub notifications on a specific topic. These notifications are
supported for legacy functions already consuming these events. However, we
recommend using the --trigger-topic
flag instead, as the legacy notifications
might be removed at a future date.
gcloud functions deploy FUNCTION_NAME \ --trigger-resource TOPIC_NAME \ --trigger-event providers/cloud.pubsub/eventTypes/topic.publish \ FLAGS...
Next steps
See the Pub/Sub Tutorial for an example of how to implement an event-driven function that is triggered by Pub/Sub.