Tutorial do Cloud Pub/Sub

Neste simples tutorial, demonstraremos como escrever, implantar e acionar um Background Cloud Function com um gatilho do Cloud 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 Google Cloud Pub/Sub para uma visão geral de como trabalhar com tópicos e assinaturas do Pub/Sub no Cloud Functions.

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

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

• Escreva e implante um Background Cloud Function.
• Acione a função publicando uma mensagem em um tópico Pub/Sub.

Custos

Este tutorial usa componentes do Cloud Platform que podem ser cobrados, incluindo:

• Cloud Functions
• Pub/Sub

Use a calculadora de preços para gerar uma estimativa de custo com base no uso previsto.

Usuários novos do Cloud Platform podem se qualificar para um teste gratuito.

Antes de começar

1. Faça login na sua conta do Google Cloud. Se você começou a usar o Google Cloud agora, 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.

2. No Console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

   Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

   Acessar o seletor de projetos

3. Verifique se o faturamento está ativado para seu projeto na nuvem. Saiba como confirmar se o faturamento está ativado para o projeto.

4. Ative as APIs Cloud Functions and Cloud Pub/Sub.

   Ative as APIs

5. Instale e inicialize o SDK do Cloud..

Se o SDK do Cloud já estiver instalado, atualize-o executando o comando a seguir:

gcloud components update

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

   C#

   Acessar o guia de configuração do .NET

   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.

   C#

   git clone https://github.com/GoogleCloudPlatform/dotnet-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 código de amostra do Cloud Functions 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/

   C#

   cd dotnet-docs-samples/functions/helloworld/HelloPubSub/

   Ruby

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

3. Confira o código de amostra:

   Node.js

   functions/helloworld/index.js

   Ver no GitHub

   /**
    * 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

   functions/helloworld/main.py

   Ver no GitHub

   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 `data` field contains the PubsubMessage message. The
            `attributes` field will contain custom attributes if there are any.
            context (google.cloud.functions.Context): The Cloud Functions event
            metadata. The `event_id` field contains the Pub/Sub message ID. The
            `timestamp` field contains the publish time.
       """
       import base64
   
       print("""This Function was triggered by messageId {} published at {}
       """.format(context.event_id, context.timestamp))
   
       if 'data' in event:
           name = base64.b64decode(event['data']).decode('utf-8')
       else:
           name = 'World'
       print('Hello {}!'.format(name))

   Go

   functions/helloworld/hello_pubsub.go

   Ver no GitHub

   
   // 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

   functions/helloworld/hello-pubsub/src/main/java/functions/HelloPubSub.java

   Ver no GitHub

   
   import com.google.cloud.functions.BackgroundFunction;
   import com.google.cloud.functions.Context;
   import com.google.events.cloud.pubsub.v1.Message;
   import java.nio.charset.StandardCharsets;
   import java.util.Base64;
   import java.util.logging.Level;
   import java.util.logging.Logger;
   
   public class HelloPubSub implements BackgroundFunction<Message> {
     private static final Logger logger = Logger.getLogger(HelloPubSub.class.getName());
   
     @Override
     public void accept(Message 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;
     }
   }

   C#

   functions/helloworld/HelloPubSub/Function.cs

   Ver no GitHub

   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

   functions/helloworld/pubsub/app.rb

   Ver no GitHub

   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 nodejs10 \
--trigger-topic YOUR_TOPIC_NAME

É possível usar os seguintes valores para a sinalização --runtime para especificar sua versão preferida do Node.js:

• nodejs10
• nodejs12
• nodejs14 (visualização pública)

Python

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

É possível usar os seguintes valores da sinalização --runtime para especificar a versão preferencial do Python:

• python37
• python38
• python39 (visualização pública)

Go

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

É possível usar os seguintes valores para a sinalização --runtime para especificar sua versão Go preferencial:

• go111 (uso suspenso)
• go113

Java

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

C#

gcloud functions deploy csharp-pubsub-function \
--entry-point HelloPubSub.Function \
--runtime dotnet3 \
--trigger-topic YOUR_TOPIC_NAME

Ruby

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

Use os seguintes valores da sinalização --runtime para especificar sua versão preferida do Ruby:

• ruby26
• ruby27

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 do Cloud ou o seguinte comando gcloud:

gcloud pubsub topics create YOUR_TOPIC_NAME

Observação: O Cloud Functions cria automaticamente assinaturas de 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.

Limpeza

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados neste tutorial, exclua o projeto que contém os recursos 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 seguir este tutorial, a exclusão dele incluirá quaisquer outras ações feitas no projeto.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um código 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ários tutoriais e guias de início rápido, a reutilização de projetos pode evitar que você exceda os limites da cota do projeto.

1. No Console do 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 do Cloud

A exclusão de Cloud Functions não remove nenhum recurso armazenado no Cloud Storage.

Para excluir o Cloud Function criado 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 

C#

gcloud functions delete csharp-pubsub-function 

Ruby

gcloud functions delete hello_pubsub 

Também é possível excluir o Cloud Functions do Console do Google Cloud.