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

---

Este tutorial simples demonstra como escrever, implementar e acionar uma função do Cloud Run baseada em eventos com um acionador do Pub/Sub.

Se está a usar o Pub/Sub pela primeira vez e quer saber mais, consulte a documentação do Pub/Sub, em particular a secção sobre gestão de tópicos e subscrições. Consulte o artigo Acionadores do Pub/Sub para ver uma vista geral do trabalho com tópicos e subscrições do Pub/Sub nas funções do Cloud Run.

Se procura exemplos de código para usar o Pub/Sub em si, visite o navegador de exemplos.

Nota: também pode usar funções acionadas por HTTP para ouvir subscrições push do Pub/Sub. A utilização de uma função HTTP permite que uma única função subscreva vários tópicos do Pub/Sub.

Objetivos

• Escrever e implementar uma função do Cloud Run baseada em eventos.
• Acionar a função publicando uma mensagem num tópico do Pub/Sub.

Custos

Neste documento, usa os seguintes componentes faturáveis do Google Cloud:

• Cloud Run functions
• Pub/Sub

Para gerar uma estimativa de custos com base na sua utilização projetada, use a calculadora de preços.

Os novos Google Cloud utilizadores podem ser elegíveis para uma avaliação gratuita.

Antes de começar

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.

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 (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 Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Install the Google Cloud CLI.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, 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 (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 Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Install the Google Cloud CLI.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

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

gcloud components update

1. Prepare o seu ambiente de desenvolvimento.

   Node.js

   Aceda ao guia de configuração do Node.js

   Python

   Aceda ao guia de configuração do Python

   Go

   Aceda ao guia de configuração do Go

   Java

   Aceda ao guia de configuração do Java

   Ruby

   Aceda ao guia de configuração do Ruby

A preparar a aplicação

1. Clone o repositório da app de exemplo para a sua máquina local:

   Node.js

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

   Em alternativa, pode transferir o exemplo como um ficheiro ZIP e extraí-lo.

   Python

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

   Em alternativa, pode transferir o exemplo como um ficheiro ZIP e extraí-lo.

   Go

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

   Em alternativa, pode transferir o exemplo como um ficheiro ZIP e extraí-lo.

   Java

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

   Em alternativa, pode transferir o exemplo como um ficheiro ZIP e extraí-lo.

   Ruby

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

   Em alternativa, pode transferir o exemplo como um ficheiro ZIP e extraí-lo.

2. Altere para o diretório que contém o código de exemplo das funções do Cloud Run para aceder ao 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. Veja o exemplo de código:

   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

   Nota: os dados da mensagem do Pub/Sub são armazenados como uma string com codificação base64 na propriedade data do objeto PubsubMessage. Para extrair estes dados, pode ter de descodificá-los, conforme mostrado nos exemplos acima. O parâmetro context é descrito aqui.

Implementar a função

Para implementar a função com um acionador do Pub/Sub, execute o seguinte comando no diretório que contém o código de exemplo (ou, no caso do Java, o ficheiro pom.xml):

Node.js

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

Use a flag --runtime para especificar o ID de tempo de execução de uma versão suportada do Node.js para executar a sua função.

Python

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

Use a flag --runtime para especificar o ID de tempo de execução de uma versão do Python suportada para executar a sua função.

Go

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

Use a flag --runtime para especificar o ID de tempo de execução de uma versão do Go suportada para executar a sua 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 de tempo de execução de uma versão Java suportada para executar a sua função.

Ruby

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

Use a flag --runtime para especificar o ID de tempo de execução de uma versão do Ruby suportada para executar a sua função.

onde YOUR_TOPIC_NAME é o nome do tópico do Pub/Sub ao qual a função vai subscrever.

Se YOUR_TOPIC_NAME ainda não existir, este comando cria-o para si. Também pode criar um tópico antes de executar o comando deploy usando a Google Cloud consola ou o seguinte comando gcloud:

gcloud pubsub topics create YOUR_TOPIC_NAME

Nota: as funções do Cloud Run criam automaticamente subscrições push que encaminham mensagens do tópico especificado para a sua função.

Acionar a função

1. Publicar uma mensagem no seu tópico Pub/Sub. Neste exemplo, a mensagem é um nome que a função vai incluir numa 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 registos para se certificar de que as execuções foram concluídas:

   gcloud functions logs read --limit 50

   Nota: os registos podem demorar alguns momentos a aparecer. Se não os vir imediatamente, verifique novamente dentro de um ou dois minutos.

Também pode publicar uma mensagem num tópico do Pub/Sub a partir de uma função.

Limpar

Para evitar incorrer em custos na sua conta do Google Cloud pelos recursos usados neste tutorial, elimine o projeto que contém os recursos ou mantenha o projeto e elimine os recursos individuais.

Eliminar o projeto

A forma mais fácil de eliminar a faturação é eliminar o projeto que criou para o tutorial.

Para eliminar o projeto:

Atenção: a eliminação de um projeto tem os seguintes efeitos:

• Tudo no projeto é eliminado. Se usou um projeto existente para as tarefas neste documento, quando o elimina, também elimina qualquer outro trabalho que tenha feito no projeto.
• Os IDs dos projetos personalizados são perdidos. Quando criou este projeto, pode ter criado um ID do projeto personalizado que quer usar no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, elimine os recursos selecionados no projeto em vez de eliminar o projeto inteiro.

Se planeia explorar várias arquiteturas, tutoriais ou inícios rápidos, a reutilização de projetos pode ajudar a evitar exceder os limites de quota de projetos.

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.

A eliminar a função

A eliminação de funções do Cloud Run não remove recursos armazenados no Cloud Storage.

Para eliminar a função que criou 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 pode eliminar funções do Cloud Run a partir da Google Cloud consola.