Tutorial do Cloud Pub/Sub (1ª geração)

Neste tutorial simples, demonstramos como escrever, implantar e acionar uma função do Cloud Run orientada a eventos com um gatilho do Pub/Sub.

Se você é novo no Pub/Sub e quer saber mais, consulte a documentação do Pub/Sub, especialmente gerenciamento de tópicos e assinaturas. Consulte Acionadores do Pub/Sub para uma visão geral de como trabalhar com tópicos e assinaturas do Pub/Sub nas funções do Cloud Run.

Se você estiver procurando exemplos de código para usar o Pub/Sub em si, acesse o navegador de exemplo.

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.

Objetivos

• Escrever e implantar uma função do Cloud Run orientada a eventos.
• Acione a função publicando uma mensagem em um tópico Pub/Sub.

Custos

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

• Cloud Run functions
• Pub/Sub

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 um teste sem custo financeiro.

Antes de começar

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Functions and Cloud Pub/Sub APIs.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

Instale a CLI do Google Cloud.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

Para inicializar a gcloud CLI, execute o seguinte comando:

gcloud init

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Functions and Cloud Pub/Sub APIs.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

Instale a CLI do Google Cloud.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

Para inicializar a gcloud CLI, execute o seguinte comando:

gcloud init

Se a gcloud CLI já estiver instalada, atualize-a executando o seguinte comando:

gcloud components update

1. Prepare seu ambiente de desenvolvimento.

   Node.js

   Acessar o guia de configuração do Node.js

   Python

   Acessar o guia de configuração do Python

   Go

   Acessar o guia de configuração do Go

   Java

   Acessar o guia de configuração do Java

   Ruby

   Acessar o guia de configuração do Ruby

Como 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

   Outra alternativa é fazer o download da amostra como um arquivo ZIP e extraí-lo.

   Python

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

   Outra alternativa é fazer o download da amostra como um arquivo ZIP e extraí-lo.

   Go

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

   Outra alternativa é fazer o download da amostra como um arquivo ZIP e extraí-lo.

   Java

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

   Outra alternativa é fazer o download da amostra como um arquivo ZIP e extraí-lo.

   Ruby

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

   Outra alternativa é fazer o download da amostra como um arquivo ZIP e extraí-lo.

2. Mude para o diretório que contém o exemplo de código das funções do Cloud Run para acessar o Pub/Sub:

   Node.js

   cd nodejs-docs-samples/functions/helloworld/

   Python

   cd python-docs-samples/functions/helloworld/

   Go

   cd golang-samples/functions/helloworld/

   Java

   cd java-docs-samples/functions/helloworld/hello-pubsub/

   Ruby

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

3. Confira o código de amostra:

   Node.js

   /**
    * Background Cloud Function to be triggered by Pub/Sub.
    * This function is exported by index.js, and executed when
    * the trigger topic receives a message.
    *
    * @param {object} message The Pub/Sub message.
    * @param {object} context The event metadata.
    */
   exports.helloPubSub = (message, context) => {
     const name = message.data
       ? Buffer.from(message.data, 'base64').toString()
       : 'World';
   
     console.log(`Hello, ${name}!`);
   };

   Python

   def hello_pubsub(event, context):
       """Background Cloud Function to be triggered by Pub/Sub.
       Args:
            event (dict):  The dictionary with data specific to this type of
                           event. The `@type` field maps to
                            `type.googleapis.com/google.pubsub.v1.PubsubMessage`.
                           The `data` field maps to the PubsubMessage data
                           in a base64-encoded string. The `attributes` field maps
                           to the PubsubMessage attributes if any is present.
            context (google.cloud.functions.Context): Metadata of triggering event
                           including `event_id` which maps to the PubsubMessage
                           messageId, `timestamp` which maps to the PubsubMessage
                           publishTime, `event_type` which maps to
                           `google.pubsub.topic.publish`, and `resource` which is
                           a dictionary that describes the service API endpoint
                           pubsub.googleapis.com, the triggering topic's name, and
                           the triggering event type
                           `type.googleapis.com/google.pubsub.v1.PubsubMessage`.
       Returns:
           None. The output is written to Cloud Logging.
       """
       import base64
   
       print(
           """This Function was triggered by messageId {} published at {} to {}
       """.format(
               context.event_id, context.timestamp, context.resource["name"]
           )
       )
   
       if "data" in event:
           name = base64.b64decode(event["data"]).decode("utf-8")
       else:
           name = "World"
       print(f"Hello {name}!")
   
   

   Go

   
   // Package helloworld provides a set of Cloud Functions samples.
   package helloworld
   
   import (
   	"context"
   	"log"
   )
   
   // 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 Pub/Sub message.
   func HelloPubSub(ctx context.Context, m PubSubMessage) error {
   	name := string(m.Data) // Automatically decoded from base64.
   	if name == "" {
   		name = "World"
   	}
   	log.Printf("Hello, %s!", name)
   	return nil
   }
   

   Java

   
   import com.google.cloud.functions.BackgroundFunction;
   import com.google.cloud.functions.Context;
   import functions.eventpojos.PubsubMessage;
   import java.nio.charset.StandardCharsets;
   import java.util.Base64;
   import java.util.logging.Level;
   import java.util.logging.Logger;
   
   public class HelloPubSub implements BackgroundFunction<PubsubMessage> {
     private static final Logger logger = Logger.getLogger(HelloPubSub.class.getName());
   
     @Override
     public void accept(PubsubMessage message, Context context) {
       String name = "world";
       if (message != null && message.getData() != null) {
         name = new String(
             Base64.getDecoder().decode(message.getData().getBytes(StandardCharsets.UTF_8)),
             StandardCharsets.UTF_8);
       }
       logger.info(String.format("Hello %s!", name));
       return;
     }
   }

   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

   Observação: os dados da mensagem Pub/Sub são armazenados como uma string de base64 codificada na propriedade de data do objeto PubsubMessage. Para extrair esses dados, poderá ser necessário decodificá-los conforme mostrado nos exemplos acima. O parâmetro context é descrito aqui.

Como implantar a função

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 (ou, no caso de Java, o arquivo pom.xml):

Node.js

gcloud functions deploy helloPubSub \
--runtime nodejs22 \
--trigger-topic YOUR_TOPIC_NAME

Use a flag --runtime para especificar o ID do ambiente de execução de uma versão do Node.js compatível a fim de executar a função.

Python

gcloud functions deploy hello_pubsub \
--runtime python312 \
--trigger-topic YOUR_TOPIC_NAME

Use a flag --runtime para especificar o ID do ambiente de execução de uma versão compatível do Python a fim de executar a função.

Go

gcloud functions deploy HelloPubSub \
--runtime go121 \
--trigger-topic YOUR_TOPIC_NAME

Use a flag --runtime para especificar o ID do ambiente de execução de uma versão do Go compatível a fim de executar a função.

Java

gcloud functions deploy java-pubsub-function \
--entry-point functions.HelloPubSub \
--runtime java17 \
--memory 512MB \
--trigger-topic YOUR_TOPIC_NAME

Use a flag --runtime para especificar o ID do ambiente de execução de uma versão compatível do Java a fim de executar a função.

Ruby

gcloud functions deploy hello_pubsub --runtime ruby33 \
--trigger-topic YOUR_TOPIC_NAME

Use a flag --runtime para especificar o ID do ambiente de execução de uma versão compatível do Ruby a fim de executar a função.

em que YOUR_TOPIC_NAME é o nome do tópico do Pub/Sub para o qual a função será inscrita.

Se YOUR_TOPIC_NAME ainda não existir, este comando o criará para você. Também é possível criar um tópico antes de executar o comando deploy usando o console doGoogle Cloud ou o seguinte comando gcloud:

gcloud pubsub topics create YOUR_TOPIC_NAME

Observação: o Cloud Functions cria automaticamente assinaturas por push que encaminham mensagens do tópico especificado para a função.

Como acionar a função

1. Publique uma mensagem no seu tópico do Pub/Sub. Neste exemplo, a mensagem é um nome que a função incluirá em uma saudação:

   gcloud pubsub topics publish YOUR_TOPIC_NAME --message YOUR_NAME

   Substitua YOUR_TOPIC_NAME pelo nome do seu tópico do Pub/Sub e YOUR_NAME por uma string arbitrária.

2. Verifique os registros para se certificar de que as execuções foram concluídas:

   gcloud functions logs read --limit 50

   Observação: os registros podem demorar alguns instantes para aparecer. Se eles não aparecerem imediatamente, verifique outra vez em um minuto ou dois.

Você também pode publicar uma mensagem em um tópico Pub/Sub de dentro de uma função.

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.

Excluir o projeto

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

Para excluir o projeto:

Cuidado: excluir um projeto tem os seguintes efeitos:

• Tudo no projeto é excluído. Se você tiver usado um projeto atual para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos nele.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um ID do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, exclua recursos específicos do projeto, em vez de excluir o projeto inteiro.

Se você planeja explorar várias arquiteturas, tutoriais e guias de início rápido, a reutilização de projetos pode evitar que você exceda limites da cota.

1. No console Google Cloud , acesse a página Gerenciar recursos.

   Acessar "Gerenciar recursos"

2. Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir .
3. Na caixa de diálogo, digite o ID do projeto e clique em Encerrar para excluí-lo.

Como excluir a função

A exclusão de funções do Cloud Run não remove nenhum recurso armazenado no Cloud Storage.

Para excluir a função criada neste tutorial, execute o seguinte comando:

Node.js

gcloud functions delete helloPubSub 

Python

gcloud functions delete hello_pubsub 

Go

gcloud functions delete HelloPubSub 

Java

gcloud functions delete java-pubsub-function 

Ruby

gcloud functions delete hello_pubsub 

Também é possível excluir funções do Cloud Run pelo consoleGoogle Cloud .