This simple tutorial demonstrates writing, deploying, and triggering an
[Event-Driven Cloud Run function](https://docs.cloud.google.com/functions/1stgendocs/writing.md.txt#event-driven_functions) with a [Pub/Sub trigger](https://docs.cloud.google.com/functions/1stgendocs/calling/pubsub.md.txt).

If you are new to Pub/Sub and want to learn more, see the Pub/Sub
[documentation](https://docs.cloud.google.com/pubsub/docs.md.txt), particularly
[managing topics and subscriptions](https://docs.cloud.google.com/pubsub/docs/admin). See
[Pub/Sub Triggers](https://docs.cloud.google.com/functions/1stgendocs/calling/pubsub.md.txt) for
an overview of working with Pub/Sub topics and subscriptions in
Cloud Run functions.

If you're looking for code samples for using [Pub/Sub](https://docs.cloud.google.com/pubsub/docs.md.txt)
itself, please visit the [sample browser](https://docs.cloud.google.com/docs/samples.md.txt?p=pubsub).

> [!NOTE]
> **Note:** You can also use [HTTP-triggered functions](https://docs.cloud.google.com/functions/1stgendocs/writing/write-http-functions.md.txt) to listen to [Pub/Sub push subscriptions](https://docs.cloud.google.com/pubsub/docs/subscriber.md.txt#push-subscription). Using an HTTP function enables a single function to subscribe to multiple Pub/Sub topics.

## Objectives

- Write and deploy an [Event-Driven Cloud Run function](https://docs.cloud.google.com/functions/1stgendocs/writing.md.txt#event-driven_functions).
- Trigger the function by publishing a message to a [Pub/Sub](https://docs.cloud.google.com/pubsub) topic.

## Costs


In this document, you use the following billable components of Google Cloud:


- Cloud Run functions
- Pub/Sub


To generate a cost estimate based on your projected usage,
use the [pricing calculator](https://docs.cloud.google.com/products/calculator).
New Google Cloud users might be eligible for a [free trial](https://docs.cloud.google.com/free).

<br />

## Before you begin

1. If you already have the gcloud CLI installed, update it by running the following command:

```sh
gcloud components update
```
2. Prepare your development environment.

   ### Node.js


   [Go to the Node.js setup guide](https://docs.cloud.google.com/nodejs/docs/setup.md.txt)

   ### Python


   [Go to the Python setup guide](https://docs.cloud.google.com/python/docs/setup.md.txt)

   ### Go


   [Go to the Go setup guide](https://docs.cloud.google.com/go/docs/setup.md.txt)

   ### Java


   [Go to the Java setup guide](https://docs.cloud.google.com/java/docs/setup.md.txt)

   ### Ruby


   [Go to the Ruby setup guide](https://docs.cloud.google.com/ruby/docs/setup.md.txt)

## Preparing the application

1. Clone the sample app repository to your local machine:


   ### Node.js

   ```sh
   git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git
   ```


   Alternatively, you can
   [download the sample](https://github.com/GoogleCloudPlatform/nodejs-docs-samples/archive/main.zip)
   as a zip file and extract it.

   ### Python

   ```sh
   git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
   ```


   Alternatively, you can
   [download the sample](https://github.com/GoogleCloudPlatform/python-docs-samples/archive/main.zip)
   as a zip file and extract it.

   ### Go

   ```sh
   git clone https://github.com/GoogleCloudPlatform/golang-samples.git
   ```


   Alternatively, you can
   [download the sample](https://github.com/GoogleCloudPlatform/golang-samples/archive/main.zip)
   as a zip file and extract it.

   ### Java

   ```sh
   git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git
   ```


   Alternatively, you can
   [download the sample](https://github.com/GoogleCloudPlatform/java-docs-samples/archive/main.zip)
   as a zip file and extract it.

   ### Ruby

   ```sh
   git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples.git
   ```


   Alternatively, you can
   [download the sample](https://github.com/GoogleCloudPlatform/ruby-docs-samples/archive/main.zip)
   as a zip file and extract it.

   <br />

2. Change to the directory that contains the Cloud Run functions sample code for accessing Pub/Sub:


   ### Node.js

   ```sh
   cd nodejs-docs-samples/functions/helloworld/
   ```

   ### Python

   ```sh
   cd python-docs-samples/functions/helloworld/
   ```

   ### Go

   ```sh
   cd golang-samples/functions/helloworld/
   ```

   ### Java

   ```sh
   cd java-docs-samples/functions/helloworld/hello-pubsub/
   ```

   ### Ruby

   ```sh
   cd ruby-docs-samples/functions/helloworld/pubsub/
   ```

   <br />

3. Take a look at the sample code:


   ### Node.js

   ```javascript
   /**
    * 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

   ```python
   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 `@type` field maps to
                            `type.googleapis.com/google.pubsub.v1.PubsubMessage`.
                           The `data` field maps to the PubsubMessage data
                           in a base64-encoded string. The `attributes` field maps
                           to the PubsubMessage attributes if any is present.
            context (google.cloud.functions.Context): Metadata of triggering event
                           including `event_id` which maps to the PubsubMessage
                           messageId, `timestamp` which maps to the PubsubMessage
                           publishTime, `event_type` which maps to
                           `google.pubsub.topic.publish`, and `resource` which is
                           a dictionary that describes the service API endpoint
                           pubsub.googleapis.com, the triggering topic's name, and
                           the triggering event type
                           `type.googleapis.com/google.pubsub.v1.PubsubMessage`.
       Returns:
           None. The output is written to Cloud Logging.
       """
       import base64

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

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

   ```

   ### Go

   ```go

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

   import (
   	"context"
   	"log"
   )

   // PubSubMessage is the payload of a Pub/Sub event.
   // See the documentation for more details:
   // https://cloud.google.com/pubsub/docs/reference/rest/v1/PubsubMessage
   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

   ```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;
     }
   }
   ```

   ### Ruby

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

   <br />

   > [!NOTE]
   > **Note:** The Pub/Sub message's data is stored as a `base64`-encoded string in the `data` property of the [`PubsubMessage`](https://docs.cloud.google.com/pubsub/docs/reference/rest/v1/PubsubMessage.md.txt) object. To extract this data, you may need to decode it as shown in the examples above. The `context` parameter is described [here](https://docs.cloud.google.com/functions/1stgendocs/writing/write-event-driven-functions.md.txt#background-functions).

## Deploying the function

To deploy the function with a Pub/Sub trigger, run the following command
in the directory that contains the sample code (or in the case of Java, the
`pom.xml` file):

### Node.js

```sh
gcloud functions deploy helloPubSub \
--runtime nodejs22 \
--trigger-topic YOUR_TOPIC_NAME
```


Use the [`--runtime`](https://docs.cloud.google.com/sdk/gcloud/reference/functions/deploy.md.txt#--runtime)
flag to specify the runtime ID of a
[supported Node.js version](https://docs.cloud.google.com/static/functions/docs/runtime-support#node.js) to run
your function.


### Python

```sh
gcloud functions deploy hello_pubsub \
--runtime python312 \
--trigger-topic YOUR_TOPIC_NAME
```


Use the [`--runtime`](https://docs.cloud.google.com/sdk/gcloud/reference/functions/deploy.md.txt#--runtime)
flag to specify the runtime ID of a
[supported Python version](https://docs.cloud.google.com/functions/docs/runtime-support.md.txt#python) to run
your function.


### Go

```sh
gcloud functions deploy HelloPubSub \
--runtime go121 \
--trigger-topic YOUR_TOPIC_NAME
```


Use the [`--runtime`](https://docs.cloud.google.com/sdk/gcloud/reference/functions/deploy.md.txt#--runtime)
flag to specify the runtime ID of a
[supported Go version](https://docs.cloud.google.com/functions/docs/runtime-support.md.txt#go) to run
your function.


### Java

```sh
gcloud functions deploy java-pubsub-function \
--entry-point functions.HelloPubSub \
--runtime java17 \
--memory 512MB \
--trigger-topic YOUR_TOPIC_NAME
```


Use the [`--runtime`](https://docs.cloud.google.com/sdk/gcloud/reference/functions/deploy.md.txt#--runtime)
flag to specify the runtime ID of a
[supported Java version](https://docs.cloud.google.com/functions/docs/runtime-support.md.txt#java) to run
your function.


### Ruby

```bash
gcloud functions deploy hello_pubsub --runtime ruby33 \
--trigger-topic YOUR_TOPIC_NAME
```


Use the [`--runtime`](https://docs.cloud.google.com/sdk/gcloud/reference/functions/deploy.md.txt#--runtime)
flag to specify the runtime ID of a
[supported Ruby version](https://docs.cloud.google.com/functions/docs/runtime-support.md.txt#ruby) to run
your function.


where `YOUR_TOPIC_NAME` is the name of the Pub/Sub
topic to which the function will be subscribed.

If `YOUR_TOPIC_NAME` doesn't already exist, this command
creates it for you. You can also create a topic before you run the `deploy`
command, using either the
[Google Cloud console](https://docs.cloud.google.com/pubsub/docs/create-topic-console) or the following
`gcloud` command:

<br />

```bash
gcloud pubsub topics create YOUR_TOPIC_NAME
```

<br />

> [!NOTE]
> **Note:** Cloud Run functions automatically creates [push subscriptions](https://docs.cloud.google.com/pubsub/docs/subscriber.md.txt#push-subscription) that forward messages from the specified topic to your function.

## Triggering the function

1. Publish a message to your Pub/Sub topic. In this example, the
   message is a name that the function will include in a greeting:

   ```bash
   gcloud pubsub topics publish YOUR_TOPIC_NAME --message YOUR_NAME
   ```

   Replace `YOUR_TOPIC_NAME` with the name of your
   Pub/Sub topic, and `YOUR_NAME` with an
   arbitrary string.
2. Check the logs to be sure the executions have completed:

   ```bash
   gcloud functions logs read --limit 50
   ```

   > [!NOTE]
   > **Note:** Logs might take a few moments to appear. If you don't see them immediately, check again in a minute or two.

You can also publish a message to a Pub/Sub topic [from within a
function](https://docs.cloud.google.com/functions/1stgendocs/calling/pubsub#publishing_a_message_from_within_a_function).

## Clean up


To avoid incurring charges to your Google Cloud account for the resources used in this
tutorial, either delete the project that contains the resources, or keep the project and
delete the individual resources.

### Deleting the project


The easiest way to eliminate billing is to delete the project that you
created for the tutorial.

To delete the project:

> [!CAUTION]
> **Caution** : Deleting a project has the following effects:
>
> - **Everything in the project is deleted.** If you used an existing project for the tasks in this document, when you delete it, you also delete any other work you've done in the project.
> - **Custom project IDs are lost.** When you created this project, you might have created a custom project ID that you want to use in the future. To preserve the URLs that use the project ID, such as an `appspot.com` URL, delete selected resources inside the project instead of deleting the whole project.
>
>
> If you plan to explore multiple architectures, tutorials, or quickstarts, reusing projects
> can help you avoid exceeding project quota limits.

1. In the Google Cloud console, go to the **Manage resources** page.

   [Go to Manage resources](https://console.cloud.google.com/iam-admin/projects)
2. In the project list, select the project that you want to delete, and then click **Delete**.
3. In the dialog, type the project ID, and then click **Shut down** to delete the project.

<br />

<br />

### Deleting the function

Deleting Cloud Run functions does not remove any resources stored in Cloud Storage.

To delete the function you created in this tutorial,
run the following command:

### Node.js

```sh
gcloud functions delete helloPubSub 
```

### Python

```sh
gcloud functions delete hello_pubsub 
```

### Go

```sh
gcloud functions delete HelloPubSub 
```

### Java

```sh
gcloud functions delete java-pubsub-function 
```

### Ruby

```sh
gcloud functions delete hello_pubsub 
```

You can also delete Cloud Run functions from the [Google Cloud console](https://console.cloud.google.com/functions/list).