Criar um tópico com SMTs

Este documento explica como criar um tópico do Pub/Sub com transformações de mensagem única (SMTs, na sigla em inglês).

Com as SMTs de tópico, é possível fazer modificações leves nos dados e atributos das mensagens diretamente no Pub/Sub. Esse recurso permite a limpeza, filtragem ou conversão de formato de dados antes que as mensagens sejam publicadas no tópico.

Para criar um tópico com SMTs, use o console Google Cloud , a Google Cloud CLI, a biblioteca de cliente ou a API Pub/Sub.

Antes de começar

Saiba mais sobre o serviço do Pub/Sub e a terminologia dele.
Saiba mais sobre SMTs.

Papéis e permissões necessárias

Para receber as permissões necessárias para criar um tópico com SMTs, peça ao administrador para conceder a você o papel do IAM de Editor do Pub/Sub (roles/pubsub.editor) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para criar um tópico com SMTs. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para criar um tópico com SMTs:

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

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

É possível configurar o controle de acesso no nível do projeto e no nível do recurso individual.

Criar um tópico com SMTs

Antes de criar um tópico com SMTs, revise a documentação sobre Propriedades de um tópico.

Para criar um Pub/Sub com uma ou mais SMTs, siga estas etapas:

Console

No console Google Cloud , acesse a página Tópicos do Pub/Sub.

Acesse Tópicos
Selecione Criar tópico.
No campo ID do tópico, insira um ID para o tópico. Para mais informações sobre como nomear tópicos, consulte as diretrizes de nomenclatura.
Em Transformações, clique em Adicionar uma transformação.
Insira um nome de função. Por exemplo, redactSSN.
Se você não quiser que a SMT seja ativada imediatamente, selecione Desativar transformação. Quando essa opção está selecionada, a SMT é criada com o tópico, mas não é executada em mensagens recebidas. Depois que o tópico for criado, você poderá editar o tópico para ativar o SMT.

Na área de texto, insira o código da SMT. Exemplo:

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

Opcional. Para validar a SMT, clique em Validar. Se o SMT for válido, a mensagem "Validation passed" será exibida. Caso contrário, uma mensagem de erro será mostrada.
Para adicionar outra transformação, clique em Adicionar uma transformação e repita as etapas anteriores.

Para organizar os SMTs em uma ordem específica, clique em Mover para cima ou Mover para baixo. Para remover um SMT, clique em Excluir.
Opcional. Para testar uma SMT em uma mensagem de amostra, siga estas etapas:
1. Clique em Testar transformações.
2. Na janela Transformação de teste, selecione a função que você quer testar.
3. Na janela Mensagem de entrada, digite uma mensagem de exemplo.
4. Para adicionar um atributo à mensagem, clique em Adicionar um atributo e insira a chave e o valor dele. É possível adicionar vários atributos.
5. Clique em Testar. O resultado da aplicação da SMT na mensagem é mostrado em Mensagem de saída.
6. Para fechar a janela Testar transformações, clique em Fechar.
Se você criar mais de uma SMT, poderá testar toda a sequência de transformações da seguinte maneira:
1. Teste o primeiro SMT na sequência, conforme descrito nas etapas anteriores.
2. Selecione o próximo SMT. A mensagem de entrada é preenchida previamente com a mensagem de saída do teste anterior.
3. Continue testando as SMTs em ordem para garantir que toda a sequência funcione conforme o 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 arquivo YAML ou JSON que defina uma ou mais SMTs. Se você tiver mais de uma SMT, elas serão executadas nas mensagens na ordem em que forem listadas.

Confira um exemplo de arquivo 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 uma SMT, execute o comando gcloud pubsub message-transforms validate:
```
gcloud pubsub message-transforms validate \
  --message-transform-file=TRANSFORM_FILE
```
Substitua:
- TRANSFORM_FILE: o caminho para um arquivo YAML ou JSON que define um único SMT. Se você estiver criando várias SMTs, valide cada uma delas individualmente.
Opcional. Para testar um ou mais SMTs em uma mensagem de amostra do Pub/Sub, execute o comando gcloud pubsub message-transforms test:
```
gcloud pubsub message-transforms test \
  --message-transforms-file=TRANSFORMS_FILE \
  --message=MESSAGE \
  --attribute=ATTRIBUTES
```
Substitua:
- TRANSFORMS_FILE: o caminho para um arquivo YAML ou JSON que define um ou mais SMTs.
- MESSAGE: o corpo da mensagem de exemplo.
- ATTRIBUTES: opcional. Uma lista separada por vírgulas de atributos de mensagem. Cada atributo é um par de chave-valor formatado como KEY="VALUE".
O comando executa as SMTs em ordem, usando a saída de cada uma como a entrada para a próxima. O comando gera os resultados de cada etapa.
Para criar o tópico, execute o comando gcloud pubsub topics create:
```
gcloud pubsub topics create TOPIC_ID \
  --message-transforms-file=TRANSFORMS_FILE
```
Substitua:
- TOPIC_ID: o ID ou nome do tema que você quer criar. Para diretrizes sobre como nomear um tópico, consulte Nomes de recursos. O nome de um tópico é imutável.
- TRANSFORMS_FILE: o caminho para um arquivo YAML ou JSON que define um ou mais SMTs.

Java

Antes de tentar essa amostra, siga as instruções de configuração do Java em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Java.


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 tentar esse exemplo, siga as instruções de configuração do Python em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Python.

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")

Go

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

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

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
}

A seguir

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.