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

Neste tutorial básico, demonstraremos como escrever, implantar e acionar uma função do Cloud orientada a eventos 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 a pesquisa de exemplos de código do Google Cloud do Google Cloud.

Objetivos

Custos

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

  • Cloud 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 uma avaliação gratuita.

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.

    Acessar o seletor de projetos

  3. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

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

    Ative as APIs

  5. Instale a CLI do Google Cloud.

  6. Para inicializar a CLI gcloud, execute o seguinte comando: 

    gcloud init
    7.

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

    Acessar o seletor de projetos

  8. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

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

    Ative as APIs

  10. Instale a CLI do Google Cloud.

  11. Para inicializar a CLI gcloud, execute o seguinte comando: 

    gcloud init
    12.

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

    gcloud components update
  12. Prepare seu ambiente de desenvolvimento.

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.

    PHP 

    git clone https://github.com/GoogleCloudPlatform/php-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/

    PHP 

    cd php-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;
  }
}

    C# 

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

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 nodejs20 \
--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.

C# 

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

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

Ruby 

gcloud functions deploy hello_pubsub --runtime ruby32 \
--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.

PHP 

 gcloud functions deploy helloworldPubsub --runtime php82 \
--trigger-topic YOUR_TOPIC_NAME

Use a flag --runtime para especificar o ID do ambiente de execução de uma versão do PHP compatível 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 do Google Cloud ou o seguinte comando gcloud:

gcloud pubsub topics create YOUR_TOPIC_NAME

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

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

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

PHP 

gcloud functions delete helloworldPubsub

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