Activa funciones desde Pub/Sub con Eventarc

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, la publicación de 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 recién comienzas a usar 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.

Roles requeridos

Tú o tu administrador deben otorgar a la cuenta del implementador, la identidad del activador y, de forma opcional, al agente de servicio de Pub/Sub y al agente de servicio de Cloud Storage los siguientes roles de IAM.

Roles necesarios para la cuenta del implementador

  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 y 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.

    Para 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:

    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 a través de roles personalizados o cualquier otro rol predefinido.

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

Roles obligatorios para la identidad del activador

  1. 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 usa Compute Engine, y con el siguiente formato de correo electrónico:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Reemplaza PROJECT_NUMBER por el número de tu proyecto 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.

  2. 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 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:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --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.
  3. 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:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/eventarc.eventReceiver

Rol opcional para el agente de servicio de Cloud Storage

  • 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'

Rol opcional para el agente de servicio de Pub/Sub

  • 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:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountTokenCreator

Crea un tema de Pub/Sub

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

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 run deploy FUNCTION \
        --source . \
        --function helloPubSub \
        --base-image BASE_IMAGE \

Reemplaza lo siguiente:

  • Reemplaza FUNCTION por el nombre de la función que implementas. Si omites este parámetro, se te solicitará que ingreses un nombre cuando ejecutes el comando.
  • BASE_IMAGE por el entorno de la imagen base de tu función, por ejemplo, nodejs22. Para obtener más detalles sobre las imágenes base y los paquetes incluidos en cada imagen, consulta Imágenes base y tiempos de ejecución de lenguajes compatibles.

Python 

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

Reemplaza lo siguiente:

  • Reemplaza FUNCTION por el nombre de la función que implementas. Si omites este parámetro, se te solicitará que ingreses un nombre cuando ejecutes el comando.
  • BASE_IMAGE por el entorno de la imagen base de tu función, por ejemplo, python313. Para obtener más detalles sobre las imágenes base y los paquetes incluidos en cada imagen, consulta Imágenes base y tiempos de ejecución de lenguajes compatibles.

Go

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

Reemplaza lo siguiente:

  • Reemplaza FUNCTION por el nombre de la función que implementas. Si omites este parámetro, se te solicitará que ingreses un nombre cuando ejecutes el comando.
  • BASE_IMAGE por el entorno de la imagen base de tu función, por ejemplo, go125. Para obtener más detalles sobre las imágenes base y los paquetes incluidos en cada imagen, consulta Imágenes base y tiempos de ejecución de lenguajes compatibles.

Java

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

Reemplaza lo siguiente:

  • Reemplaza FUNCTION por el nombre de la función que implementas. Si omites este parámetro, se te solicitará que ingreses un nombre cuando ejecutes el comando.
  • BASE_IMAGE por el entorno de la imagen base de tu función, por ejemplo, java21. Para obtener más detalles sobre las imágenes base y los paquetes incluidos en cada imagen, consulta Imágenes base y tiempos de ejecución de lenguajes compatibles.

.NET

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

Reemplaza lo siguiente:

  • Reemplaza FUNCTION por el nombre de la función que implementas. Si omites este parámetro, se te solicitará que ingreses un nombre cuando ejecutes el comando.
  • BASE_IMAGE por el entorno de la imagen base de tu función, por ejemplo, dotnet8. Para obtener más detalles sobre las imágenes base y los paquetes incluidos en cada imagen, consulta Imágenes base y tiempos de ejecución de lenguajes compatibles.

Ruby

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

Reemplaza lo siguiente:

  • Reemplaza FUNCTION por el nombre de la función que implementas. Si omites este parámetro, se te solicitará que ingreses un nombre cuando ejecutes el comando.
  • BASE_IMAGE por el entorno de la imagen base de tu función, por ejemplo, ruby34. Para obtener más detalles sobre las imágenes base y los paquetes incluidos en cada imagen, consulta Imágenes base y tiempos de ejecución de lenguajes compatibles.

PHP

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

Reemplaza lo siguiente:

  • Reemplaza FUNCTION por el nombre de la función que implementas. Si omites este parámetro, se te solicitará que ingreses un nombre cuando ejecutes el comando.
  • BASE_IMAGE por el entorno de la imagen base de tu función, por ejemplo, php84. Para obtener más detalles sobre las imágenes base y los paquetes incluidos en cada imagen, consulta Imágenes base y tiempos de ejecución de lenguajes compatibles.

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. Sigue estos pasos para crear 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

    Reemplaza lo siguiente:

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

    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 permisos denegados.

  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 deGoogle 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!”.