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.

Objetivos

Com este tutorial, você vai:

  1. Implantar uma função orientada a eventos.
  2. Criar um gatilho do Eventarc.
  3. Acione a função publicando uma mensagem em um tópico do Pub/Sub.

Custos

Neste documento, você vai usar os seguintes componentes faturáveis do Google Cloud:

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços.

Novos usuários do Google Cloud podem estar qualificados para uma avaliação gratuita.

Antes de começar

As restrições de segurança definidas pela sua organização podem impedir que você conclua as etapas a seguir. Para informações sobre solução de problemas, consulte Desenvolver aplicativos em um ambiente restrito de 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. Se você estiver usando um provedor de identidade externo (IdP), primeiro faça login na CLI gcloud com sua identidade federada.

  4. Para inicializar a CLI gcloud, execute o seguinte 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. Make sure that billing is enabled for your Google Cloud project.

  7. Install the Google Cloud CLI.

  8. Se você estiver usando um provedor de identidade externo (IdP), primeiro faça login na CLI gcloud com sua identidade federada.

  9. Para inicializar a CLI gcloud, execute o seguinte 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. Make sure that billing is enabled for your Google Cloud project.

  12. Se você não estiver usando o Cloud Shell, atualize os componentes da Google Cloud CLI e faça login usando sua conta:
    gcloud components update
    gcloud auth login
  13. Ative as APIs:
    gcloud services enable artifactregistry.googleapis.com \
        cloudbuild.googleapis.com \
        eventarc.googleapis.com \
        run.googleapis.com \
        logging.googleapis.com \
        pubsub.googleapis.com
  14. Defina as variáveis de configuração usadas neste tutorial:
    export REGION=us-central1
    gcloud config set run/region ${REGION}
    gcloud config set run/platform managed
    gcloud config set eventarc/location ${REGION}
  15. Crie uma conta de serviço:
    SERVICE_ACCOUNT=eventarc-trigger-sa
    
    gcloud iam service-accounts create $SERVICE_ACCOUNT
  16. Se você precisa seguir uma política da organização de restrição de domínio que restringe invocações não autenticadas para seu projeto, será necessário acessar o serviço implantado, conforme descrito em Como testar serviços particulares.

  17. 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:

      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 por meio de papéis personalizados ou de 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:

      PROJECT_NUMBER-compute@developer.gserviceaccount.com

      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.

    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:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
          --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:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
          --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:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
          --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);
      }

    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, go123. 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=PROJECT_NUMBER-compute@developer.gserviceaccount.com

      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!".

    Limpar

    Se você criou um novo projeto para este tutorial, exclua o projeto. Se você usou um projeto já existente e quer mantê-lo sem as alterações incluídas com este tutorial, exclua os recursos criados para o tutorial.

    Exclua o projeto

    O jeito mais fácil de evitar cobranças é excluindo o projeto que você criou para o tutorial.

    Para excluir o projeto:

    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.

    Excluir recursos do tutorial

    1. Exclua o serviço do Cloud Run que você implantou neste tutorial:

      gcloud run services delete SERVICE_NAME

      SERVICE_NAME é o nome escolhido do serviço.

      Também é possível excluir os serviços do Cloud Run no consoleGoogle Cloud .

    2. Remova as configurações padrão do gcloud CLI que você adicionou durante a configuração do tutorial.

      Por exemplo:

      gcloud config unset run/region

      ou

      gcloud config unset project

    3. Exclua outros recursos do Google Cloud criados neste tutorial:

      • Exclua o gatilho do Eventarc:
        gcloud eventarc triggers delete TRIGGER_NAME
        
        Substitua TRIGGER_NAME pelo nome do gatilho.

    A seguir