Acionar funções do Pub/Sub usando o Eventarc

Este tutorial demonstra como escrever e acionar uma função do Cloud Run orientada a eventos com um gatilho do Pub/Sub.

Para configurar o roteamento de eventos, incluindo a origem e o destino do evento, especifique filtros para um gatilho do Eventarc. Para o exemplo deste tutorial, a publicação de uma mensagem em um tópico do Pub/Sub aciona o evento, e uma solicitação é enviada para a função na forma de uma solicitação HTTP.

Se você não tem experiência com o Pub/Sub e quer saber mais, consulte a documentação do Pub/Sub para guias de início rápido e referências importantes.

Observação: você também pode usar funções acionadas por HTTP para ouvir as assinaturas push do Pub/Sub. Usar uma função HTTP permite que uma única função se inscreva em vários tópicos Pub/Sub.

Funções exigidas

Você ou seu administrador precisa conceder à conta do implantador, à identidade do gatilho e, opcionalmente, ao agente de serviço do Pub/Sub e ao agente de serviço do Cloud Storage os seguintes papéis do IAM.

Papéis necessários para a conta do implantador

1. Se você for o criador do projeto, vai receber o papel de proprietário básico (roles/owner). Por padrão, esse papel do Identity and Access Management (IAM) inclui as permissões necessárias para acesso total à maioria dos recursos do Google Cloud, e você pode pular esta etapa.

   Se você não é o criador do projeto, as permissões necessárias precisam ser concedidas ao principal apropriado. Por exemplo, um principal pode ser uma Conta do Google (para usuários finais) ou uma conta de serviço (para aplicativos e cargas de trabalho de computação). Para mais informações, consulte a página Papéis e permissões do destino do evento.

   Para conseguir as permissões necessárias para concluir este tutorial, peça ao administrador para conceder a você os seguintes papéis do IAM no seu projeto:

   • Desenvolvedor de origem do Cloud Run (roles/run.sourceDeveloper)
   • Administrador de projetos do IAM (roles/resourcemanager.projectIamAdmin)
   • Usuário da conta de serviço (roles/iam.serviceAccountUser)
   • Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin)
   • Acessador de exibição de registros (roles/logging.viewAccessor)

   Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

   Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

   Por padrão, as permissões do Cloud Build incluem permissões para upload e download de artefatos do Artifact Registry.

Papéis necessários para a identidade do gatilho

1. Anote as propriedades da conta de serviço padrão do Compute Engine, porque você vai anexá-la a um gatilho do Eventarc para representar a identidade do acionador para fins de teste. Essa conta de serviço é criada automaticamente depois de ativar ou usar um serviço do Google Cloud que usa o Compute Engine e com o seguinte formato de e-mail:

   [e-mail]

   Substitua PROJECT_NUMBER pelo número do seu projeto Google Cloud. Encontre o número do projeto na página Boas-vindas do console do Google Cloud ou executando o seguinte comando:

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

   Para ambientes de produção, é altamente recomendável criar uma nova conta de serviço, conceder a ela um ou mais papéis do IAM que contenham as permissões mínimas necessárias, bem como seguir o princípio de privilégio mínimo.

   Observação:

   O iam.automaticIamGrantsForDefaultServiceAccounts restrição de política da organização impede que o papel de editor seja concedido automaticamente a contas de serviço padrão. Se você criou a organização após 3 de maio de 2024, essa restrição será aplicada por padrão.

   É altamente recomendável aplicar essa restrição para desativar a concessão automática de papéis. Se você desativar a concessão automática de papéis, precisará decidir quais papéis conceder às contas de serviço padrão e, em seguida, conceder esses papéis por conta própria.

   Se a conta de serviço padrão já tiver o papel de Editor, recomendamos que você o substitua por papéis menos permissivos.Para modificar com segurança os papéis da conta de serviço, use o Simulador de política para ver o impacto da alteração e, em seguida, conceda e revogue os papéis apropriados.

2. Por padrão, os serviços do Cloud Run só podem ser chamados por proprietários do projeto, editores do projeto e administradores e invocadores do Cloud Run. É possível controlar o acesso por serviço. No entanto, para fins de teste, conceda o papel de chamador do Cloud Run (run.invoker) no projeto Google Cloud à conta de serviço do Compute Engine. Isso concede o papel em todos os serviços e jobs do Cloud Run em um projeto.

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

   Se você criar um gatilho para um serviço autenticado do Cloud Run sem conceder o papel de chamador do Cloud Run, o gatilho será criado com sucesso e estará ativo. No entanto, o acionador não funcionará conforme o esperado e uma mensagem semelhante à seguinte aparecerá nos registros:

   The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header.
3. Conceda o papel de receptor de eventos do Eventarc (roles/eventarc.eventReceiver) no projeto à conta de serviço padrão do Compute Engine para que o gatilho do Eventarc possa receber eventos de provedores de eventos.

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

Papel opcional para o agente de serviço do Cloud Storage

• Antes de criar um gatilho para eventos diretos do Cloud Storage, conceda o papel de publisher do Pub/Sub (roles/pubsub.publisher) ao agente de serviço do 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'

Papel opcional para o agente de serviço do Pub/Sub

• Se você ativou o agente de serviço do Cloud Pub/Sub até 8 de abril de 2021, para oferecer compatibilidade com solicitações push autenticadas do Pub/Sub, conceda o papel de Criador de token da conta de serviço (roles/iam.serviceAccountTokenCreator) ao agente de serviço. Caso contrário, esse papel é concedido por padrão:

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

Criar um tópico do Pub/Sub

No Cloud Run, os tópicos do Pub/Sub não são criados automaticamente quando você implanta uma função. Antes de implantar a função, publique uma mensagem no tópico do Pub/Sub para acioná-la:

gcloud pubsub topics create YOUR_TOPIC_NAME

Preparar o aplicativo

1. Clone o repositório do app de amostra na 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. Mude para o diretório que contém o código de amostra para acessar o 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. Confira o código de amostra:

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

Observação: os dados da mensagem Pub/Sub são armazenados como uma string de base64 codificada na propriedade data do objeto PubsubMessage. Para extrair esses dados, talvez seja necessário decodificá-los conforme mostrado no exemplo de código anterior.

Implantar uma função orientada a eventos

Para implantar a função, execute o seguinte comando no diretório que contém o código de amostra:

Node.js

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

Substitua:

• FUNCTION pelo nome da função que você está implantando. Se você omitir esse parâmetro, será solicitado que você insira um nome ao executar o comando.
• BASE_IMAGE com o ambiente de imagem base da sua função, por exemplo, nodejs22. Para mais detalhes sobre as imagens de base e os pacotes incluídos em cada imagem, consulte Ambientes de execução de linguagem e imagens de base compatíveis.

Python

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

Substitua:

• FUNCTION pelo nome da função que você está implantando. Se você omitir esse parâmetro, será solicitado que você insira um nome ao executar o comando.
• BASE_IMAGE com o ambiente de imagem base da sua função, por exemplo, python313. Para mais detalhes sobre as imagens de base e os pacotes incluídos em cada imagem, consulte Ambientes de execução de linguagem e imagens de base compatíveis.

Go

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

Substitua:

• FUNCTION pelo nome da função que você está implantando. Se você omitir esse parâmetro, será solicitado que você insira um nome ao executar o comando.
• BASE_IMAGE com o ambiente de imagem base da sua função, por exemplo, go125. Para mais detalhes sobre as imagens de base e os pacotes incluídos em cada imagem, consulte Ambientes de execução de linguagem e imagens de base compatíveis.

Java

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

Substitua:

• FUNCTION pelo nome da função que você está implantando. Se você omitir esse parâmetro, será solicitado que você insira um nome ao executar o comando.
• BASE_IMAGE com o ambiente de imagem base da sua função, por exemplo, java21. Para mais detalhes sobre as imagens de base e os pacotes incluídos em cada imagem, consulte Ambientes de execução de linguagem e imagens de base compatíveis.

.NET

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

Substitua:

• FUNCTION pelo nome da função que você está implantando. Se você omitir esse parâmetro, será solicitado que você insira um nome ao executar o comando.
• BASE_IMAGE com o ambiente de imagem base da sua função, por exemplo, dotnet8. Para mais detalhes sobre as imagens de base e os pacotes incluídos em cada imagem, consulte Ambientes de execução de linguagem e imagens de base compatíveis.

Ruby

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

Substitua:

• FUNCTION pelo nome da função que você está implantando. Se você omitir esse parâmetro, será solicitado que você insira um nome ao executar o comando.
• BASE_IMAGE com o ambiente de imagem base da sua função, por exemplo, ruby34. Para mais detalhes sobre as imagens de base e os pacotes incluídos em cada imagem, consulte Ambientes de execução de linguagem e imagens de base compatíveis.

PHP

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

Substitua:

• FUNCTION pelo nome da função que você está implantando. Se você omitir esse parâmetro, será solicitado que você insira um nome ao executar o comando.
• BASE_IMAGE com o ambiente de imagem base da sua função, por exemplo, php84. Para mais detalhes sobre as imagens de base e os pacotes incluídos em cada imagem, consulte Ambientes de execução de linguagem e imagens de base compatíveis.

Se você for solicitado a criar um repositório na região especificada, responda pressionando y. Quando a implantação for concluída, a CLI do Google Cloud vai mostrar um URL em que o serviço está em execução.

Criar um gatilho do Eventarc

Para implantar a função com um gatilho do Pub/Sub, execute o seguinte comando no diretório que contém o código de amostra:

1. Crie um gatilho do Eventarc no Pub/Sub:

   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]

   Substitua:

   • TRIGGER_NAME pelo nome do gatilho.
   • FUNCTION pelo nome da função.
   • PROJECT_NUMBER pelo número do projeto Google Cloud .

   Ao criar um gatilho do Eventarc pela primeira vez em um projeto do Google Cloud , pode haver um atraso no provisionamento do agente de serviço do Eventarc. Esse problema geralmente pode ser resolvido ao tentar criar o acionador novamente. Para mais informações, consulte Erros de permissão negada.

2. Confirme se o gatilho foi criado com êxito. Embora o gatilho seja criado imediatamente, pode levar até dois minutos para que ele seja totalmente funcional.

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

   A saída será semelhante a esta:

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

Acionar a função

Para testar a função do Pub/Sub:

1. Atribua o tópico a uma variável:

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

2. Publique uma mensagem no tópico:

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

O serviço do Cloud Run registra o corpo da mensagem recebida. Você pode ver isso na seção "Registros" da sua instância do Cloud Run:

1. Acesse o console doGoogle Cloud .
2. Clique na função.

3. Selecione a guia Registros.

   Os registros podem demorar alguns instantes para aparecer. Se você não os vir imediatamente, verifique outra vez após alguns instantes.

4. Procure a mensagem "Hello World!".

Sucesso: você criou e acionou uma função do Cloud Run orientada a eventos com um gatilho do Pub/Sub.