Activar funciones desde Pub/Sub mediante Eventarc

En este tutorial se muestra cómo escribir y activar funciones de Cloud Run basadas en eventos con un activador de Pub/Sub.

Puede configurar el enrutamiento de eventos, incluida la fuente y el destino de los eventos, especificando filtros para un activador de Eventarc. En el ejemplo de este tutorial, al publicar un mensaje en un tema de Pub/Sub, se activa el evento y se envía una solicitud a tu función en forma de solicitud HTTP.

Si no conoces Pub/Sub y quieres obtener más información, consulta la documentación de Pub/Sub para ver guías de inicio rápido y referencias clave.

Objetivos

En este tutorial, aprenderás a hacer lo siguiente:

  1. Despliega una función basada en eventos.
  2. Crea un activador de Eventarc.
  3. Activa la función publicando un mensaje en un tema de Pub/Sub.

Costes

En este documento, se utilizan los siguientes componentes facturables de Google Cloud:

Para generar una estimación de costes basada en el uso previsto, utiliza la calculadora de precios.

Los usuarios nuevos Google Cloud pueden disfrutar de una prueba gratuita.

Antes de empezar

Es posible que las restricciones de seguridad definidas por tu organización te impidan completar los siguientes pasos. Para obtener información sobre cómo solucionar problemas, consulta el artículo Desarrollar aplicaciones en un entorno limitado Google Cloud .

  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. Install the Google Cloud CLI.

  3. Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

  4. Para inicializar gcloud CLI, ejecuta el siguiente comando: 

    gcloud init

  5. Create or select a Google Cloud project.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

  6. Verify that billing is enabled for your Google Cloud project.

  7. Install the Google Cloud CLI.

  8. Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

  9. Para inicializar gcloud CLI, ejecuta el siguiente comando: 

    gcloud init

  10. Create or select a Google Cloud project.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

  11. Verify that billing is enabled for your Google Cloud project.

  12. Si no usas Cloud Shell, actualiza los componentes de la CLI de Google Cloud e inicia sesión con tu cuenta: 
    gcloud components update
gcloud auth login
  13. Habilita las APIs: 
    gcloud services enable artifactregistry.googleapis.com \
    cloudbuild.googleapis.com \
    eventarc.googleapis.com \
    run.googleapis.com \
    logging.googleapis.com \
    pubsub.googleapis.com
  14. Defina las variables de configuración que se usan en este tutorial: 
    export REGION=us-central1
gcloud config set run/region ${REGION}
gcloud config set run/platform managed
gcloud config set eventarc/location ${REGION}
  15. Crea una cuenta de servicio: 
    SERVICE_ACCOUNT=eventarc-trigger-sa

gcloud iam service-accounts create $SERVICE_ACCOUNT

  16. Si tu proyecto está sujeto a una política de organización de restricción de dominio que restringe las invocaciones no autenticadas, tendrás que acceder al servicio desplegado tal como se describe en la sección Probar servicios privados.

    17. Roles obligatorios

    Tú o tu administrador debéis conceder los siguientes roles de gestión de identidades y accesos a la cuenta de implementación, la identidad del activador y, opcionalmente, al agente de servicio de Pub/Sub y al agente de servicio de Cloud Storage.

    Roles necesarios para la cuenta de implementación

    1. Si has creado el proyecto, se te asignará el rol básico Propietario (roles/owner). De forma predeterminada, este rol de gestión de identidades y accesos (IAM) incluye los permisos necesarios para acceder por completo a la mayoría de los recursos Google Cloud, por lo que puedes saltarte este paso.

      Si no eres el creador del proyecto, debes conceder los permisos necesarios al principal correspondiente. Por ejemplo, un principal puede ser una cuenta de Google (para usuarios finales) o una cuenta de servicio (para aplicaciones y cargas de trabajo de computación). Para obtener más información, consulta la página Roles y permisos de tu destino de evento.

      Para obtener los permisos que necesitas para completar este tutorial, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos en tu proyecto:

      Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

      También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

      Ten en cuenta que, de forma predeterminada, los permisos de Cloud Build incluyen permisos para subir y descargar artefactos de Artifact Registry.

    Roles necesarios para la identidad del activador

    1. Anota la cuenta de servicio predeterminada de Compute Engine, ya que la asociarás a un activador de Eventarc para representar la identidad del activador con fines de prueba. Esta cuenta de servicio se crea automáticamente después de habilitar o usar un servicio que utilice Compute Engine y tiene el siguiente formato de correo electrónico: Google Cloud 

      PROJECT_NUMBER-compute@developer.gserviceaccount.com

      Sustituye PROJECT_NUMBER por el número de tu proyecto. Google Cloud Puedes encontrar el número de tu proyecto en la página Bienvenido de la consola Google Cloud o ejecutando el siguiente comando:

      gcloud projects describe PROJECT_ID --format='value(projectNumber)'

      En los entornos de producción, te recomendamos que crees una cuenta de servicio y le asignes uno o varios roles de IAM que contengan los permisos mínimos necesarios y que sigas el principio de privilegio mínimo.

    2. De forma predeterminada, solo los propietarios y editores de proyectos, así como los administradores y los invocadores de Cloud Run, pueden llamar a los servicios de Cloud Run. Puedes controlar el acceso por servicio. Sin embargo, para hacer pruebas, otorga el rol Invocador de Cloud Run (run.invoker) en el proyecto Google Cloud a la cuenta de servicio de Compute Engine. Concede el rol en todos los servicios y trabajos de Cloud Run de un proyecto. 
      gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/run.invoker

      Ten en cuenta que, si creas un activador para un servicio de Cloud Run autenticado sin conceder el rol Invocador de Cloud Run, el activador se creará correctamente y estará activo. Sin embargo, el activador no funcionará como se espera y aparecerá un mensaje similar al siguiente en los registros:

      The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header.
    3. Concede el rol Receptor de eventos de Eventarc (roles/eventarc.eventReceiver) en el proyecto a la cuenta de servicio predeterminada de Compute Engine para que el activador de Eventarc pueda recibir eventos de proveedores de eventos. 
      gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/eventarc.eventReceiver

    Rol opcional del agente de servicio de Cloud Storage

    • Antes de crear un activador para eventos directos de Cloud Storage, concede el rol Publicador de Pub/Sub (roles/pubsub.publisher) al agente de servicio de Cloud Storage:

      SERVICE_ACCOUNT="$(gcloud storage service-agent --project=PROJECT_ID)"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:${SERVICE_ACCOUNT}" \
    --role='roles/pubsub.publisher'

    Rol opcional del agente de servicio de Pub/Sub

    • Si habilitaste el agente de servicio de Cloud Pub/Sub el 8 de abril del 2021 o antes para admitir solicitudes push de Pub/Sub autenticadas, asigna el rol Creador de tokens de cuenta de servicio (roles/iam.serviceAccountTokenCreator) al agente de servicio. De lo contrario, este rol se asigna de forma predeterminada: 
      gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountTokenCreator

    Crear un tema de Pub/Sub

    En Cloud Run, los temas de Pub/Sub no se crean automáticamente al desplegar una función. Antes de implementar la función, publica un mensaje en este tema de Pub/Sub para activarla:

    gcloud pubsub topics create YOUR_TOPIC_NAME

    Preparar la aplicación

    1. Clona el repositorio de aplicaciones de muestra en la máquina local:

      Node.js 

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

      Python 

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

      Go 

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

      Java

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

      .NET

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

      Ruby 

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

      PHP 

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

    2. Cambia al directorio que contiene el código de ejemplo para acceder a Pub/Sub:

      Node.js 

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

      Python 

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

      Go 

      cd golang-samples/functions/functionsv2/hellopubsub/

      Java

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

      .NET

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

      Ruby 

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

      PHP 

      cd php-docs-samples/functions/helloworld_pubsub/

    3. Echa un vistazo al código de ejemplo:

      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() + "!"
    )

      Go

      
// 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 + "!");
    }
  }
}

      .NET

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

    Desplegar una función basada en eventos

    Para desplegar la función, ejecuta el siguiente comando en el directorio que contiene el código de muestra:

    Node.js 

      gcloud run deploy FUNCTION \
        --source . \
        --function helloPubSub \
        --base-image BASE_IMAGE \

    Sustituye:

    • FUNCTION con el nombre de la función que vas a implementar. Si omites este parámetro, se te pedirá que introduzcas un nombre cuando ejecutes el comando.
    • BASE_IMAGE con el entorno de imagen base de tu función, por ejemplo, nodejs22. Para obtener más información sobre las imágenes base y los paquetes incluidos en cada imagen, consulta Runtimes e imágenes base de los idiomas admitidos.

    Python 

      gcloud run deploy FUNCTION \
        --source . \
        --function subscribe \
        --base-image BASE_IMAGE \

    Sustituye:

    • FUNCTION con el nombre de la función que vas a implementar. Si omites este parámetro, se te pedirá que introduzcas un nombre cuando ejecutes el comando.
    • BASE_IMAGE con el entorno de imagen base de tu función, por ejemplo, python313. Para obtener más información sobre las imágenes base y los paquetes incluidos en cada imagen, consulta Runtimes e imágenes base de los idiomas admitidos.

    Go 

      gcloud run deploy FUNCTION \
        --source . \
        --function HelloPubSub \
        --base-image BASE_IMAGE \

    Sustituye:

    • FUNCTION con el nombre de la función que vas a implementar. Si omites este parámetro, se te pedirá que introduzcas un nombre cuando ejecutes el comando.
    • BASE_IMAGE con el entorno de imagen base de tu función, por ejemplo, go124. Para obtener más información sobre las imágenes base y los paquetes incluidos en cada imagen, consulta Runtimes e imágenes base de los idiomas admitidos.

    Java

      gcloud run deploy FUNCTION \
        --source . \
        --function functions.SubscribeToTopic \
        --base-image BASE_IMAGE \

    Sustituye:

    • FUNCTION con el nombre de la función que vas a implementar. Si omites este parámetro, se te pedirá que introduzcas un nombre cuando ejecutes el comando.
    • BASE_IMAGE con el entorno de imagen base de tu función, por ejemplo, java21. Para obtener más información sobre las imágenes base y los paquetes incluidos en cada imagen, consulta Runtimes e imágenes base de los idiomas admitidos.

    .NET

      gcloud run deploy FUNCTION \
        --source . \
        --function HelloPubSub.Function \
        --base-image BASE_IMAGE \

    Sustituye:

    • FUNCTION con el nombre de la función que vas a implementar. Si omites este parámetro, se te pedirá que introduzcas un nombre cuando ejecutes el comando.
    • BASE_IMAGE con el entorno de imagen base de tu función, por ejemplo, dotnet8. Para obtener más información sobre las imágenes base y los paquetes incluidos en cada imagen, consulta Runtimes e imágenes base de los idiomas admitidos.

    Ruby 

      gcloud run deploy FUNCTION \
        --source . \
        --function hello_pubsub \
        --base-image BASE_IMAGE \

    Sustituye:

    • FUNCTION con el nombre de la función que vas a implementar. Si omites este parámetro, se te pedirá que introduzcas un nombre cuando ejecutes el comando.
    • BASE_IMAGE con el entorno de imagen base de tu función, por ejemplo, ruby34. Para obtener más información sobre las imágenes base y los paquetes incluidos en cada imagen, consulta Runtimes e imágenes base de los idiomas admitidos.

    PHP 

      gcloud run deploy FUNCTION \
        --source . \
        --function helloworldPubsub \
        --base-image BASE_IMAGE \

    Sustituye:

    • FUNCTION con el nombre de la función que vas a implementar. Si omites este parámetro, se te pedirá que introduzcas un nombre cuando ejecutes el comando.
    • BASE_IMAGE con el entorno de imagen base de tu función, por ejemplo, php84. Para obtener más información sobre las imágenes base y los paquetes incluidos en cada imagen, consulta Runtimes e imágenes base de los idiomas admitidos.

    Si se te pide que crees un repositorio en la región especificada, responde pulsando y. Cuando se complete el despliegue, la CLI de Google Cloud mostrará una URL en la que se esté ejecutando el servicio.

    Crear un activador de Eventarc

    Para desplegar la función con un activador de Pub/Sub, ejecuta el siguiente comando en el directorio que contiene el código de ejemplo:

    1. Crea un activador de Pub/Sub de Eventarc:

      gcloud eventarc triggers create TRIGGER_NAME  \
    --location=${REGION} \
    --destination-run-service=FUNCTION \
    --destination-run-region=${REGION} \
    --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \
    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

      Sustituye:

      • TRIGGER_NAME con el nombre del activador.
      • FUNCTION por el nombre de tu función.
      • PROJECT_NUMBER con el número de tu proyecto Google Cloud .

      Ten en cuenta que, cuando crees un activador de Eventarc por primera vez en un proyecto de Google Cloud , puede haber un retraso en el aprovisionamiento del agente de servicio de Eventarc. Este problema suele resolverse intentando crear el activador de nuevo. Para obtener más información, consulta Errores de permiso denegado.

    2. Confirma que el activador se ha creado correctamente. Ten en cuenta que, aunque el activador se crea inmediatamente, puede tardar hasta dos minutos en estar totalmente operativo.

      gcloud eventarc triggers list --location=${REGION}

      La salida debería ser similar a la siguiente:

      NAME: helloworld-events
TYPE: google.cloud.pubsub.topic.v1.messagePublished
DESTINATION: Cloud Run service: helloworld-events
ACTIVE: Yes
LOCATION: us-central1

    Activar la función

    Para probar la función de Pub/Sub, sigue estos pasos:

    1. Asigna el tema a una variable:

      TOPIC_ID=$(gcloud eventarc triggers describe TRIGGER_NAME --location $REGION --format='value(transport.pubsub.topic)')

    2. Publica un mensaje en el tema:

      gcloud pubsub topics publish $TOPIC_ID --message="Hello World"

    El servicio de Cloud Run registra el cuerpo del mensaje entrante. Puedes ver esta información en la sección Registros de tu instancia de Cloud Run:

    1. Ve a la Google Cloud consola.
    2. Haz clic en la función.

    3. Selecciona la pestaña Registros.

      Los registros pueden tardar unos instantes en aparecer. Si no los ves inmediatamente, vuelve a comprobarlo al cabo de unos instantes.

    4. Busca el mensaje "Hello World!".

    Limpieza

    Si has creado un proyecto para este tutorial, elimínalo. Si has usado un proyecto y quieres conservarlo sin los cambios añadidos en este tutorial, elimina los recursos creados para el tutorial.

    Eliminar el proyecto

    La forma más fácil de evitar que te cobren es eliminar el proyecto que has creado para el tutorial.

    Para ello, sigue las instrucciones que aparecen a continuación:

    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.

    Eliminar recursos del tutorial

    1. Elimina el servicio de Cloud Run que has desplegado en este tutorial:

      gcloud run services delete SERVICE_NAME

      Donde SERVICE_NAME es el nombre del servicio que has elegido.

      También puedes eliminar servicios de Cloud Run desde la Google Cloud consola.

    2. Elimina las configuraciones predeterminadas de la CLI de gcloud que hayas añadido durante la configuración del tutorial.

      Por ejemplo:

      gcloud config unset run/region

      o

      gcloud config unset project

    3. Elimina otros recursos de Google Cloud que hayas creado en este tutorial:

      • Elimina el activador de Eventarc: 
        gcloud eventarc triggers delete TRIGGER_NAME
        Sustituye TRIGGER_NAME por el nombre de tu activador.

    Siguientes pasos