Tutorial su Pub/Sub

Questo semplice tutorial mostra come scrivere, eseguire il deployment e attivare una funzione Cloud Run basata su eventi con un attivatore Pub/Sub.

Se non hai dimestichezza con Pub/Sub e vuoi saperne di più, consulta la documentazione di Pub/Sub, in particolare la sezione sulla gestione di argomenti e iscrizioni. Consulta la sezione Trigger Pub/Sub per una panoramica dell'utilizzo di argomenti e iscrizioni Pub/Sub nelle funzioni Cloud Run.

Se cerchi esempi di codice per l'utilizzo di Pub/Sub, consulta il browser di esempi.

Obiettivi

Costi

In questo documento utilizzi i seguenti componenti fatturabili di Google Cloud:

  • Cloud Run functions
  • Cloud Build
  • Pub/Sub
  • Artifact Registry
  • Eventarc
  • Cloud Logging

For details, see Cloud Run functions pricing.

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il Calcolatore prezzi. I nuovi utenti di Google Cloud potrebbero essere idonei per una prova gratuita.

Prima di iniziare

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the Cloud Functions, Cloud Build, Artifact Registry, Eventarc, Logging, and Pub/Sub APIs.

    Enable the APIs

  5. Install the Google Cloud CLI.

  6. To initialize the gcloud CLI, run the following command: 

    gcloud init

  7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  8. Make sure that billing is enabled for your Google Cloud project.

  9. Enable the Cloud Functions, Cloud Build, Artifact Registry, Eventarc, Logging, and Pub/Sub APIs.

    Enable the APIs

  10. Install the Google Cloud CLI.

  11. To initialize the gcloud CLI, run the following command: 

    gcloud init

    12. Se hai già installato gcloud CLI, aggiornalo eseguendo il seguente comando:

    gcloud components update
  12. Prepara l'ambiente di sviluppo.

Prerequisiti

Crea un argomento Pub/Sub:

gcloud pubsub topics create YOUR_TOPIC_NAME

Questo è un passaggio obbligatorio prima di poter eseguire il deployment della funzione. Nelle funzioni Cloud Run, gli argomenti Pub/Sub non vengono creati automaticamente quando esegui il deployment di una funzione.

Preparazione della richiesta

  1. Clona il repository dell'app di esempio sulla tua macchina locale:

    Node.js 

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

    In alternativa, puoi scaricare l'esempio come file ZIP ed estrarlo.

    Python 

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

    In alternativa, puoi scaricare l'esempio come file ZIP ed estrarlo.

    Vai 

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

    In alternativa, puoi scaricare l'esempio come file ZIP ed estrarlo.

    Java 

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

    In alternativa, puoi scaricare l'esempio come file ZIP ed estrarlo.

    C# 

    git clone https://github.com/GoogleCloudPlatform/dotnet-docs-samples.git

    In alternativa, puoi scaricare l'esempio come file ZIP ed estrarlo.

    Ruby 

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

    In alternativa, puoi scaricare l'esempio come file ZIP ed estrarlo.

    PHP 

    git clone https://github.com/GoogleCloudPlatform/php-docs-samples.git

    In alternativa, puoi scaricare l'esempio come file ZIP ed estrarlo.

  2. Passa alla directory che contiene il codice campione di Cloud Run Functions per accedere a Pub/Sub:

    Node.js 

    cd nodejs-docs-samples/functions/v2/helloPubSub/

    Python 

    cd python-docs-samples/functions/v2/pubsub/

    Vai 

    cd golang-samples/functions/functionsv2/hellopubsub/

    Java 

    cd java-docs-samples/functions/v2/pubsub/

    C# 

    cd dotnet-docs-samples/functions/helloworld/HelloPubSub/

    Ruby 

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

    PHP 

    cd php-docs-samples/functions/helloworld_pubsub/

  3. Dai un'occhiata al codice campione:

    Node.js 

    const functions = require('@google-cloud/functions-framework');

// Register a CloudEvent callback with the Functions Framework that will
// be executed when the Pub/Sub trigger topic receives a message.
functions.cloudEvent('helloPubSub', cloudEvent => {
  // The Pub/Sub message is passed as the CloudEvent's data payload.
  const base64name = cloudEvent.data.message.data;

  const name = base64name
    ? Buffer.from(base64name, 'base64').toString()
    : 'World';

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

    Python 

    import base64

from cloudevents.http import CloudEvent
import functions_framework


# Triggered from a message on a Cloud Pub/Sub topic.
@functions_framework.cloud_event
def subscribe(cloud_event: CloudEvent) -> None:
    # Print out the data from Pub/Sub, to prove that it worked
    print(
        "Hello, " + base64.b64decode(cloud_event.data["message"]["data"]).decode() + "!"
    )

    Vai 

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

import (
	"context"
	"fmt"
	"log"

	"github.com/GoogleCloudPlatform/functions-framework-go/functions"
	"github.com/cloudevents/sdk-go/v2/event"
)

func init() {
	functions.CloudEvent("HelloPubSub", helloPubSub)
}

// MessagePublishedData contains the full Pub/Sub message
// See the documentation for more details:
// https://cloud.google.com/eventarc/docs/cloudevents#pubsub
type MessagePublishedData struct {
	Message PubSubMessage
}

// 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 CloudEvent message and extracts the Pub/Sub message.
func helloPubSub(ctx context.Context, e event.Event) error {
	var msg MessagePublishedData
	if err := e.DataAs(&msg); err != nil {
		return fmt.Errorf("event.DataAs: %w", err)
	}

	name := string(msg.Message.Data) // Automatically decoded from base64.
	if name == "" {
		name = "World"
	}
	log.Printf("Hello, %s!", name)
	return nil
}

    Java 

    import com.google.cloud.functions.CloudEventsFunction;
import com.google.gson.Gson;
import functions.eventpojos.PubSubBody;
import io.cloudevents.CloudEvent;
import java.nio.charset.StandardCharsets;
import java.util.Base64;
import java.util.logging.Logger;

public class SubscribeToTopic implements CloudEventsFunction {
  private static final Logger logger = Logger.getLogger(SubscribeToTopic.class.getName());

  @Override
  public void accept(CloudEvent event) {
    // The Pub/Sub message is passed as the CloudEvent's data payload.
    if (event.getData() != null) {
      // Extract Cloud Event data and convert to PubSubBody
      String cloudEventData = new String(event.getData().toBytes(), StandardCharsets.UTF_8);
      Gson gson = new Gson();
      PubSubBody body = gson.fromJson(cloudEventData, PubSubBody.class);
      // Retrieve and decode PubSub message data
      String encodedData = body.getMessage().getData();
      String decodedData =
          new String(Base64.getDecoder().decode(encodedData), StandardCharsets.UTF_8);
      logger.info("Hello, " + decodedData + "!");
    }
  }
}

    C# 

    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 

    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

    PHP 

    
use CloudEvents\V1\CloudEventInterface;
use Google\CloudFunctions\FunctionsFramework;

// Register the function with Functions Framework.
// This enables omitting the `FUNCTIONS_SIGNATURE_TYPE=cloudevent` environment
// variable when deploying. The `FUNCTION_TARGET` environment variable should
// match the first parameter.
FunctionsFramework::cloudEvent('helloworldPubsub', 'helloworldPubsub');

function helloworldPubsub(CloudEventInterface $event): void
{
    $log = fopen(getenv('LOGGER_OUTPUT') ?: 'php://stderr', 'wb');

    $cloudEventData = $event->getData();
    $pubSubData = base64_decode($cloudEventData['message']['data']);

    $name = $pubSubData ? htmlspecialchars($pubSubData) : 'World';
    fwrite($log, "Hello, $name!" . PHP_EOL);
}

Deployment della funzione

Per il deployment della funzione con un trigger Pub/Sub, esegui il seguente comando nella directory contenente il codice campione (o, nel caso di Java, il pom.xml file):

Node.js 

gcloud functions deploy nodejs-pubsub-function \
--gen2 \
--runtime=nodejs22 \
--region=REGION \
--source=. \
--entry-point=helloPubSub \
--trigger-topic=YOUR_TOPIC_NAME

Utilizza il flag --runtime per specificare l'ID runtime di una versione di Node.js supportata per eseguire la funzione.

Python 

gcloud functions deploy python-pubsub-function \
--gen2 \
--runtime=python312 \
--region=REGION \
--source=. \
--entry-point=subscribe \
--trigger-topic=YOUR_TOPIC_NAME

Utilizza il flag --runtime per specificare l'ID runtime di una versione di Python supportata per eseguire la funzione.

Vai 

gcloud functions deploy go-pubsub-function \
--gen2 \
--runtime=go122 \
--region=REGION \
--source=. \
--entry-point=HelloPubSub \
--trigger-topic=YOUR_TOPIC_NAME

Utilizza il flag --runtime per specificare l'ID runtime di una versione Go supportata per eseguire la funzione.

Java 

gcloud functions deploy java-pubsub-function \
--gen2 \
--runtime=java21 \
--region=REGION \
--source=. \
--entry-point=functions.SubscribeToTopic \
--memory=512MB \
--trigger-topic=YOUR_TOPIC_NAME

Utilizza il flag --runtime per specificare l'ID runtime di una versione Java supportata per eseguire la funzione.

C# 

gcloud functions deploy csharp-pubsub-function \
--gen2 \
--runtime=dotnet8 \
--region=REGION \
--source=. \
--entry-point=HelloPubSub.Function \
--trigger-topic=YOUR_TOPIC_NAME

Utilizza il flag --runtime per specificare l'ID runtime di una versione .NET supportata per eseguire la funzione.

Ruby 

gcloud functions deploy ruby-pubsub-function \
--gen2 \
--runtime=ruby33 \
--region=REGION \
--source=. \
--entry-point=hello_pubsub \
--trigger-topic=YOUR_TOPIC_NAME

Utilizza il flag --runtime per specificare l'ID runtime di una versione di Ruby supportata per eseguire la funzione.

PHP 

gcloud functions deploy php-pubsub-function \
--gen2 \
--runtime=php83 \
--region=REGION \
--source=. \
--entry-point=helloworldPubsub \
--trigger-topic=YOUR_TOPIC_NAME

Utilizza il flag --runtime per specificare l'ID runtime di una versione PHP supportata per eseguire la funzione.

dove YOUR_TOPIC_NAME è il nome dell'argomento Pub/Sub a cui la funzione verrà sottoscritta.

Devi creare un argomento prima di eseguire il comando deploy utilizzando la console Google Cloud o lo strumento a riga di comando gcloud. A differenza delle funzioni Cloud Run (1ª generazione.), nelle funzioni Cloud Run gli argomenti Pub/Sub non vengono creati automaticamente quando esegui il deployment di una funzione con un trigger Pub/Sub.

Attivazione della funzione

Per testare la funzione Pub/Sub:

  1. Pubblica un messaggio nell'argomento:

    gcloud pubsub topics publish my-topic --message="Friend"

  2. Leggi i log della funzione per visualizzare il risultato:

    gcloud functions logs read \
  --gen2 \
  --region=REGION \
  --limit=5 \
  FUNCTION_NAME

    Sostituisci quanto segue:

    • REGION è il nome della regione Google Cloud in cui hai eseguito il deployment della funzione (ad esempio us-west1).
    • FUNCTION_NAME è il nome che hai assegnato alla funzione al momento del deployment (ad esempio, la funzione Node.js in questo tutorial è stata di cui è stato eseguito il deployment con il nome nodejs-pubsub-function).

    Dovresti vedere l'output dei log che include il nuovo messaggio "Amico".

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, elimina il progetto che contiene le risorse oppure mantieni il progetto ed elimina le singole risorse.

Elimina il progetto

Il modo più semplice per eliminare la fatturazione è eliminare il progetto che hai creato per il tutorial.

Per eliminare il progetto:

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

    Go to Manage resources

  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.

Eliminazione della funzione Cloud Run

L'eliminazione delle funzioni Cloud Run non rimuove le risorse archiviate in Cloud Storage.

Per eliminare la funzione Cloud Run creata in questo tutorial, esegui il seguente comando:

Node.js 

gcloud functions delete nodejs-pubsub-function --gen2 --region REGION

Python 

gcloud functions delete python-pubsub-function --gen2 --region REGION

Vai 

gcloud functions delete go-pubsub-function --gen2 --region REGION

Java 

gcloud functions delete java-pubsub-function --gen2 --region REGION

C# 

gcloud functions delete csharp-pubsub-function --gen2 --region REGION

Ruby 

gcloud functions delete ruby-pubsub-function --gen2 --region REGION

PHP 

gcloud functions delete php-pubsub-function --gen2 --region REGION

Puoi anche eliminare le funzioni Cloud Run dalla console Google Cloud.