Activa funciones desde Pub/Sub con Eventarc

---

Vista previa — Cloud Run functions

Esta función está sujeta a las "Condiciones de las Ofertas de Fase Previa a la DG" de la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Las funciones de fase previa a la DG están disponibles “tal cual” y podrían tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

En este instructivo, se muestra cómo escribir y activar una función de Cloud Run controlada por eventos con un activador de Pub/Sub.

Si especificas filtros para un activador de Eventarc, puedes configurar el enrutamiento de los eventos, incluidos la fuente y el destino del evento. En el ejemplo de este instructivo, publicar un mensaje en un tema de Pub/Sub activa el evento y se envía una solicitud a tu función en forma de una solicitud HTTP.

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

Nota: También puedes usar las funciones activadas por HTTP para detectar suscripciones de envío de Pub/Sub. El uso de una función de HTTP permite que una sola función se suscriba a varios temas de Pub/Sub.

Objetivos

En este instructivo, podrás:

1. Implementar una función controlada por eventos.
2. Crear un activador de Eventarc.
3. Activa la función mediante la publicación de un mensaje en un tema de Pub/Sub.

Costos

En este documento, usarás los siguientes componentes facturables de Google Cloud:

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

Para generar una estimación de costos en función del uso previsto, usa la calculadora de precios. Es posible que los usuarios nuevos de Google Cloud califiquen para obtener una prueba gratuita.

Antes de comenzar

Es posible que las restricciones de seguridad que define tu organización no te permitan completar los siguientes pasos. Para obtener información sobre la solución de problemas, consulta Desarrolla aplicaciones en un entorno de Google Cloud restringido.

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. To initialize the gcloud CLI, run the following command:

   gcloud init

4. Create or select a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the 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.

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

6. Install the Google Cloud CLI.

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

   gcloud init

8. Create or select a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the 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.

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

10. Si no usas Cloud Shell, actualiza los componentes de Google Cloud CLI y accede con tu cuenta:

    gcloud components update
    gcloud auth login

11. Habilita las APIs:

    gcloud services enable artifactregistry.googleapis.com \
        cloudbuild.googleapis.com \
        eventarc.googleapis.com \
        run.googleapis.com \
        logging.googleapis.com \
        pubsub.googleapis.com

12. Establece las variables de configuración que se usan en este instructivo:

    export REGION=us-central1
    gcloud config set run/region ${REGION}
    gcloud config set run/platform managed
    gcloud config set eventarc/location ${REGION}

13. Crear una cuenta de servicio:

    SERVICE_ACCOUNT=eventarc-trigger-sa
    
    gcloud iam service-accounts create $SERVICE_ACCOUNT

14. Si estás bajo una política de la organización de restricción de dominios que restringe las invocaciones no autenticadas para tu proyecto, deberás acceder al servicio implementado como se describe en Prueba servicios privados.

Roles obligatorios

1. Si eres el creador del proyecto, se te otorga el rol de propietario básico (roles/owner). De forma predeterminada, este rol de Identity and Access Management (IAM) incluye los permisos necesarios para obtener acceso completo a la mayoría de los recursos de Google Cloud, pero puedes omitir este paso.

   Si no eres el creador del proyecto, se deben otorgar los permisos necesarios en el proyecto a la principal correspondiente. Por ejemplo, una principal puede ser una Cuenta de Google (para usuarios finales) o una cuenta de servicio (para aplicaciones y cargas de trabajo de procesamiento). Para obtener más información, consulta la página Roles y permisos para el destino del evento.

   Permisos necesarios

   Si quieres obtener los permisos que necesitas para completar este instructivo, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

   • Desarrollador de origen de Cloud Run (roles/run.sourceDeveloper)
   • Administrador de IAM de proyecto (roles/resourcemanager.projectIamAdmin)
   • Usuario de cuenta de servicio (roles/iam.serviceAccountUser)
   • Administrador de Service Usage (roles/serviceusage.serviceUsageAdmin)
   • Descriptor de acceso de vista de registros (roles/logging.viewAccessor)

   Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

   También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

2. Toma nota del recurso Compute Engine predeterminada, ya que la conectará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 de Google Cloud que use Compute Engine, y con la siguiente formato de correo electrónico:

   [e-mail]

   Reemplaza PROJECT_NUMBER por el número de proyecto de Google Cloud. Para encontrar el número del proyecto, ve a la página de bienvenida de la consola de Google Cloud o ejecuta el siguiente comando:

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

   Para entornos de producción, recomendamos crear una cuenta de servicio nueva y otorgarle una o más funciones de IAM que contengan los permisos mínimos requeridos y seguir el principio de privilegio mínimo.

   Nota:

   La restricción de la política de la organización iam.automaticIamGrantsForDefaultServiceAccounts evita que el rol Editor se otorgue de forma automática a las cuentas de servicio predeterminadas. Si creaste tu organización después del 3 de mayo de 2024, esta restricción se aplica de forma predeterminada.

   Recomendamos que apliques esta restricción para inhabilitar la concesión automática de roles. Si inhabilitas la concesión automática de roles, debes decidir qué roles se deben otorgar a las cuentas de servicio predeterminadas y, luego, otorgar estos roles a ti mismo.

   Si la cuenta de servicio predeterminada ya tiene el rol de editor, te recomendamos que reemplaces el rol de editor por roles menos permisivos. Para modificar de forma segura los roles de la cuenta de servicio, usa Policy Simulator para ver el impacto del cambio y, luego, otorga y revoca los roles adecuados.

3. De forma predeterminada, solo los propietarios y los editores del proyecto, y los administradores y los invocadores de Cloud Run pueden llamar a los servicios de Cloud Run. Puedes controlar el acceso según el servicio. Sin embargo, para fines de prueba, otorga el rol de invocador de Cloud Run (run.invoker) en el proyecto de Google Cloud a la cuenta de servicio de Compute Engine. Esto otorga el rol en todos los servicios y trabajos de Cloud Run en un proyecto.

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:[e-mail] \
       --role=roles/run.invoker

   Ten en cuenta que si creas un activador para un servicio autenticado de Cloud Run sin otorgar la función de invocador de Cloud Run, el activador se crea de forma correcta y está activo. Sin embargo, el activador no funcionará como se espera y aparecerá en el registro un mensaje similar al siguiente:

   The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header.
4. Otorga el rol de 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:[e-mail] \
       --role=roles/eventarc.eventReceiver

5. Antes de crear un activador para eventos directos desde Cloud Storage, otorga el rol de 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'

6. Si habilitaste el agente de servicio de Cloud Pub/Sub el 8 de abril de 2021 o antes de esa fecha, para admitir las solicitudes de envío de Pub/Sub autenticadas, otorga el rol de creador de tokens de cuenta de servicio (roles/iam.serviceAccountTokenCreator) al agente de servicio. De lo contrario, este rol se otorga de forma predeterminada:

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:[e-mail] \
       --role=roles/iam.serviceAccountTokenCreator

Crea un tema de Pub/Sub

En las funciones de Cloud Run, los temas de Pub/Sub no se crean de forma automática cuando implementas 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

Prepara la aplicación

1. Clona el repositorio de la app de muestra en tu 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. Ve al directorio que contiene el código de muestra de funciones de Cloud Run 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. Ve el código de muestra:

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

Nota: Los datos del mensaje de Pub/Sub se almacenan como una cadena codificada en base64 en la propiedad data del objeto PubsubMessage. Para extraer estos datos, es posible que debas decodificarlos como se muestra en el código de ejemplo anterior.

Implementa una función controlada por eventos

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

Node.js

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

Python

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

Go

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

Java

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

.NET

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

Ruby

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

PHP

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

Reemplaza FUNCTION por el nombre de la función que implementarás. Si omites este parámetro, se te solicitará que ingreses un nombre cuando ejecutes el comando.

BASE_IMAGE es el entorno de imagen base de tu función. Para obtener más detalles sobre las imágenes base y los paquetes incluidos en cada una, consulta Imágenes base de los entornos de ejecución.

Si se te solicita que crees un repositorio en la región especificada, presiona y para responder. Cuando se complete la implementación, Google Cloud CLI mostrará una URL en la que se ejecuta el servicio.

Crea un activador de Eventarc

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

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=[e-mail]

   Reemplaza lo siguiente:

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

   Ten en cuenta que, cuando creas un activador de Eventarc por primera vez en un proyecto de Google Cloud, es posible que haya un retraso en el aprovisionamiento del agente de servicio de Eventarc. Por lo general, este problema se puede resolver si intentas crear el activador de nuevo. Para obtener más información, consulta Errores de permiso denegado.

2. Confirma que el activador se haya creado de forma correcta. Ten en cuenta que, si bien tu activador se crea de inmediato, puede tardar hasta dos minutos para que un activador sea por completo funcional.

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

   El resultado debería ser similar al siguiente ejemplo:

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

Activa 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 esto en la sección Registros de tu instancia de Cloud Run:

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

3. Selecciona la pestaña Registros.

   Los registros pueden tardar un poco en aparecer. Si no los ves de inmediato, vuelve a revisar en unos minutos.

4. Busca el mensaje “Hello World!”.

Realiza una limpieza

Si creaste un proyecto nuevo para este instructivo, bórralo. Si usaste un proyecto existente y deseas conservarlo sin los cambios que se agregaron en este instructivo, borra los recursos creados para el instructivo.

Borra el proyecto

La manera más fácil de eliminar la facturación es borrar el proyecto que creaste para el instructivo.

Para borrar el proyecto, haz lo siguiente:

Precaución: Borrar un proyecto tiene las siguientes consecuencias:

• Se borra todo en el proyecto. Si usaste un proyecto existente para las tareas de este documento, cuando lo borres, también se borrará cualquier otro trabajo que hayas realizado en el proyecto.
• Se pierden los ID personalizados de proyectos. Cuando creaste este proyecto, es posible que hayas creado un ID del proyecto personalizado que desees utilizar en el futuro. Para conservar las URL que utilizan el ID del proyecto, como una URL appspot.com, borra los recursos seleccionados dentro del proyecto en lugar de borrar todo el proyecto.

Si planeas explorar varias infraestructuras, instructivos y guías de inicio rápido la reutilización de proyectos puede ayudarte a evitar exceder los límites de las cuotas del proyecto.

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.

Elimina recursos de instructivos

1. Usa este comando para borrar el servicio de Cloud Run que implementaste en este instructivo:

   gcloud run services delete SERVICE_NAME

   En el ejemplo anterior, SERVICE_NAME es el nombre del servicio que elegiste.

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

2. Quita todas las opciones de configuración predeterminadas de gcloud CLI que agregaste durante la configuración del instructivo.

   Por ejemplo:

   gcloud config unset run/region

   o

   gcloud config unset project

3. Borra otros recursos de Google Cloud que creaste en este instructivo:

   • Borrar el activador de Eventarc:

     gcloud eventarc triggers delete TRIGGER_NAME
     

     Reemplaza TRIGGER_NAME por el nombre de tu activador.

¿Qué sigue?

• Crea activadores de Eventarc para otros tipos de eventos
• Administra funciones