Crie um tópico com SMTs

Este documento explica como criar um tópico do Pub/Sub com transformações de mensagens únicas (SMTs).

As SMTs de tópicos permitem modificações simples aos dados e atributos das mensagens diretamente no Pub/Sub. Esta funcionalidade permite a limpeza, a filtragem ou a conversão de formato de dados antes de as mensagens serem publicadas no tópico.

Para criar um tópico com SMTs, pode usar a Google Cloud consola, a CLI Google Cloud, a biblioteca cliente ou a API Pub/Sub.

Antes de começar

Saiba mais sobre o serviço Pub/Sub e a respetiva terminologia.
Saiba mais sobre os SMTs.

Funções e autorizações necessárias

Para receber as autorizações de que precisa para criar um tópico com SMTs, peça ao seu administrador para lhe conceder a função de IAM Editor do Pub/Sub (roles/pubsub.editor) no seu projeto. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Esta função predefinida contém as autorizações necessárias para criar um tópico com SMTs. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

São necessárias as seguintes autorizações para criar um tópico com SMTs:

Conceda a autorização para criar um tópico no projeto: pubsub.topics.create

Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.

Pode configurar o controlo de acesso ao nível do projeto e ao nível do recurso individual.

Crie um tópico com SMTs

Antes de criar um tópico com SMTs, reveja a documentação sobre as propriedades de um tópico.

Para criar um Pub/Sub com um ou mais SMTs, siga os passos seguintes.

Consola

Na Google Cloud consola, aceda à página Tópicos do Pub/Sub.

Aceder a Tópicos
Clique em Criar tópico.
No campo ID do tópico, introduza um ID para o seu tópico. Para mais informações sobre a atribuição de nomes a tópicos, consulte as diretrizes de nomenclatura.
Em Transformações, clique em Adicionar uma transformação.
Introduza um nome de função. Por exemplo: redactSSN.
Se não quiser que a SMT esteja ativa imediatamente, selecione Desativar transformação. Quando esta opção está selecionada, o SMT é criado com o tópico, mas não é executado em mensagens recebidas. Depois de criar o tópico, pode editá-lo para ativar o SMT.

Na área de texto, introduza o código do SMT. Por exemplo:

function redactSSN(message, metadata) {
  const data = JSON.parse(message.data);
  delete data['ssn'];
  message.data = JSON.stringify(data);
  return message;
}

Opcional. Para validar o SMT, clique em Validar. Se o SMT for válido, é apresentada a mensagem "Validation passed". Caso contrário, é apresentada uma mensagem de erro.
Para adicionar outra transformação, clique em Adicionar uma transformação e repita os passos anteriores.

Para organizar os SMTs numa ordem específica, clique em Mover para cima ou Mover para baixo. Para remover um SMT, clique em Eliminar.
Opcional. Para testar um SMT numa mensagem de exemplo, siga estes passos:
1. Clique em Testar transformações.
2. Na janela Testar transformação, selecione a função que quer testar.
3. Na janela Introduzir mensagem, introduza uma mensagem de exemplo.
4. Para adicionar um atributo à mensagem, clique em Adicionar um atributo e introduza a chave e o valor do atributo. Pode adicionar vários atributos.
5. Clique em Testar. O resultado da aplicação da SMT na mensagem é apresentado em Mensagem de saída.
6. Para fechar a janela Testar transformações, clique em Fechar.
Se criar mais do que um SMT, pode testar toda a sequência de transformações da seguinte forma:
1. Teste o primeiro SMT na sequência, conforme descrito nos passos anteriores.
2. Selecione o SMT seguinte. A mensagem de entrada é pré-preenchida com a mensagem de saída do teste anterior.
3. Continue a testar os SMTs por ordem para se certificar de que toda a sequência funciona como esperado.
Para criar o tópico, clique em Criar.

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

Crie um ficheiro YAML ou JSON que defina um ou mais SMTs. Se tiver mais do que um SMT, estes são executados nas mensagens pela ordem em que os indica.

Segue-se um exemplo de um ficheiro de transformação YAML:

- javascriptUdf:
    code: >
        function redactSSN(message, metadata) {
          const data = JSON.parse(message.data);
          delete data['ssn'];
          message.data = JSON.stringify(data);
          return message;
        }
    functionName: redactSSN

Opcional. Para validar um SMT, execute o comando gcloud pubsub message-transforms validate:
```
gcloud pubsub message-transforms validate \
  --message-transform-file=TRANSFORM_FILE
```
Substitua o seguinte:
- TRANSFORM_FILE: o caminho para um ficheiro YAML ou JSON que define um único SMT. Se estiver a criar vários SMTs, tem de validá-los individualmente.
Opcional. Para testar um ou mais SMTs numa mensagem Pub/Sub de amostra, execute o comando gcloud pubsub message-transforms test:
```
gcloud pubsub message-transforms test \
  --message-transforms-file=TRANSFORMS_FILE \
  --message=MESSAGE \
  --attribute=ATTRIBUTES
```
Substitua o seguinte:
- TRANSFORMS_FILE: o caminho para um ficheiro YAML ou JSON que define um ou mais SMTs.
- MESSAGE: o corpo da mensagem de amostra.
- ATTRIBUTES: opcional. Uma lista de atributos de mensagens separados por vírgulas. Cada atributo é um par de chave-valor formatado como KEY="VALUE".
O comando executa os SMTs por ordem, usando a saída de cada SMT como entrada para o seguinte. O comando produz os resultados de cada passo.
Para criar o tópico, execute o comando gcloud pubsub topics create:
```
gcloud pubsub topics create TOPIC_ID \
  --message-transforms-file=TRANSFORMS_FILE
```
Substitua o seguinte:
- TOPIC_ID: o ID ou o nome do tópico que quer criar. Para ver diretrizes sobre como atribuir um nome a um tópico, consulte o artigo Nomes de recursos. O nome de um tópico é imutável.
- TRANSFORMS_FILE: o caminho para um ficheiro YAML ou JSON que define um ou mais SMTs.

Java

Antes de experimentar este exemplo, siga as instruções de configuração do Java no artigo Início rápido: usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Java do Pub/Sub.


import com.google.api.gax.rpc.AlreadyExistsException;
import com.google.cloud.pubsub.v1.TopicAdminClient;
import com.google.pubsub.v1.JavaScriptUDF;
import com.google.pubsub.v1.MessageTransform;
import com.google.pubsub.v1.Topic;
import com.google.pubsub.v1.TopicName;
import java.io.IOException;

public class CreateTopicWithSmtExample {

  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String topicId = "your-topic-id";

    createTopicWithSmtExample(projectId, topicId);
  }

  public static void createTopicWithSmtExample(String projectId, String topicId)
      throws IOException {
    TopicName topicName = TopicName.of(projectId, topicId);

    // UDF that removes the 'ssn' field, if present
    String code =
        "function redactSSN(message, metadata) {"
            + "  const data = JSON.parse(message.data);"
            + "  delete data['ssn'];"
            + "  message.data = JSON.stringify(data);"
            + "  return message;"
            + "}";
    String functionName = "redactSSN";

    JavaScriptUDF udf =
        JavaScriptUDF.newBuilder().setCode(code).setFunctionName(functionName).build();
    MessageTransform transform = MessageTransform.newBuilder().setJavascriptUdf(udf).build();
    try (TopicAdminClient topicAdminClient = TopicAdminClient.create()) {

      Topic topic =
          topicAdminClient.createTopic(
              Topic.newBuilder()
                  .setName(topicName.toString())
                  // Add the UDF message transform
                  .addMessageTransforms(transform)
                  .build());

      System.out.println("Created topic with SMT: " + topic.getName());
    } catch (AlreadyExistsException e) {
      System.out.println(topicName + "already exists.");
    }
  }
}

Python

Antes de experimentar este exemplo, siga as instruções de configuração do Python no artigo Início rápido: usar bibliotecas cliente. Para mais informações, consulte a documentação de referência da API Python Pub/Sub.

from google.cloud import pubsub_v1
from google.pubsub_v1.types import JavaScriptUDF, MessageTransform, Topic

# TODO(developer)
# project_id = "your-project-id"
# topic_id = "your-topic-id"

code = """function redactSSN(message, metadata) {
            const data = JSON.parse(message.data);
            delete data['ssn'];
            message.data = JSON.stringify(data);
            return message;
            }"""
udf = JavaScriptUDF(code=code, function_name="redactSSN")
transforms = [MessageTransform(javascript_udf=udf)]

publisher = pubsub_v1.PublisherClient()
topic_path = publisher.topic_path(project_id, topic_id)

request = Topic(name=topic_path, message_transforms=transforms)

topic = publisher.create_topic(request=request)

print(f"Created topic: {topic.name} with SMT")

Ir

O exemplo seguinte usa a versão principal da biblioteca de cliente Go Pub/Sub (v2). Se ainda estiver a usar a biblioteca v1, consulte o guia de migração para a v2. Para ver uma lista de exemplos de código da v1, consulte os exemplos de código descontinuados.

Antes de experimentar este exemplo, siga as instruções de configuração do Go em Início rápido: usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Go do Pub/Sub.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub/v2"
	"cloud.google.com/go/pubsub/v2/apiv1/pubsubpb"
)

// createTopicWithSMT creates a topic with a single message transform function applied.
func createTopicWithSMT(w io.Writer, projectID, topicID string) error {
	// projectID := "my-project-id"
	// topicID := "my-topic"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %w", err)
	}
	defer client.Close()

	code := `function redactSSN(message, metadata) {
			const data = JSON.parse(message.data);
			delete data['ssn'];
			message.data = JSON.stringify(data);
			return message;
		}`
	transform := &pubsubpb.MessageTransform{
		Transform: &pubsubpb.MessageTransform_JavascriptUdf{
			JavascriptUdf: &pubsubpb.JavaScriptUDF{
				FunctionName: "redactSSN",
				Code:         code,
			},
		},
	}

	topic := &pubsubpb.Topic{
		Name:              fmt.Sprintf("projects/%s/topics/%s", projectID, topicID),
		MessageTransforms: []*pubsubpb.MessageTransform{transform},
	}

	topic, err = client.TopicAdminClient.CreateTopic(ctx, topic)
	if err != nil {
		return fmt.Errorf("CreateTopic: %w", err)
	}

	fmt.Fprintf(w, "Created topic with message transform: %v\n", topic)
	return nil
}

O que se segue?

Exceto em caso de indicação contrária, o conteúdo desta página é licenciado de acordo com a Licença de atribuição 4.0 do Creative Commons, e as amostras de código são licenciadas de acordo com a Licença Apache 2.0. Para mais detalhes, consulte as políticas do site do Google Developers. Java é uma marca registrada da Oracle e/ou afiliadas.

Última atualização 2026-01-14 UTC.