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 Google Cloud CLI, a biblioteca cliente ou a API Pub/Sub.

Antes de começar

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

As seguintes autorizações são necessárias 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.

Os exemplos seguintes partem do princípio de que quer criar um tópico com esta função definida pelo utilizador (UDF) SMT. Para mais informações sobre as FDU, consulte a vista geral das FDUs.

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

Consola

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

    Aceda a Tópicos

  2. Clique em Criar tópico.

    É apresentada a página Criar tópico.

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

  4. Em Transformações, clique em Adicionar uma transformação.

  5. Introduza um nome de função. Por exemplo: redactSSN.

  6. Se não quiser usar o SMT com o seu tópico imediatamente, clique na opção Desativar transformação. Esta ação guarda o SMT, mas não o executa à medida que as mensagens fluem através do seu tópico.

  7. Introduza uma nova transformação. Por exemplo:

    function redactSSN(message, metadata) {
      const data = JSON.parse(message.data);
      delete data['ssn'];
      message.data = JSON.stringify(data);
      return message;
    }
  8. O Pub/Sub fornece uma função de validação que lhe permite validar um SMT. Clique em Validar para validar a transformação.

  9. Se quiser adicionar outra transformação, clique em Adicionar uma transformação.

  10. Para organizar todos os SMTs numa ordem específica, pode usar as setas para cima e para baixo. Para remover um SMT, clique no botão de eliminação.
  11. O Pub/Sub oferece uma função de teste que lhe permite verificar o resultado da execução do SMT numa mensagem de exemplo. Para testar as SMTs, clique em Testar transformação.

  12. Na janela Testar transformação, selecione a função que quer testar.

  13. Na janela Introduzir mensagem, introduza uma mensagem de exemplo.

  14. Se quiser adicionar atributos de mensagens, clique em Adicionar um atributo e introduza um ou mais pares de chave-valor.

  15. Clique em Testar. É apresentado o resultado da aplicação das SMTs na mensagem.

  16. Feche a janela para parar os testes de SMTs em mensagens de amostra.

  17. Clique em Criar para criar o tópico.

gcloud

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

  2. O Pub/Sub fornece uma função de validação que lhe permite 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 o ficheiro YAML ou JSON que contém um único SMT.

      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

  3. O Pub/Sub oferece uma função de teste que lhe permite verificar o resultado da execução de um ou mais SMTs numa mensagem de exemplo. Execute o comando gcloud pubsub message-transforms test:

    gcloud pubsub message-transforms test --message-transforms-file=TRANSFORMS_FILE --message=MESSAGE --attributes=ATTRIBUTES

    Substitua o seguinte:

    • TRANSFORMS_FILE: o caminho para o ficheiro YAML ou JSON que contém um ou mais SMTs.

      Segue-se um exemplo de um ficheiro de transformações 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

    • MESSAGE: corpo da mensagem com o qual testar os SMTs.

    • ATTRIBUTES: atributos da mensagem com os quais testar os SMTs.

  4. 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 o ficheiro YAML ou JSON que contém um ou mais SMTs.

      Segue-se um exemplo de um ficheiro de transformações 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

  5. Java

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

    Para se autenticar no Pub/Sub, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

    
    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 Pythoninstruções de configuração no início rápido do Pub/Sub com as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Python Pub/Sub.

    Para se autenticar no Pub/Sub, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

    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

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

    Para se autenticar no Pub/Sub, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

    // Copyright 2025 Google LLC
    //
    // Licensed under the Apache License, Version 2.0 (the "License");
    // you may not use this file except in compliance with the License.
    // You may obtain a copy of the License at
    //
    //     https://www.apache.org/licenses/LICENSE-2.0
    //
    // Unless required by applicable law or agreed to in writing, software
    // distributed under the License is distributed on an "AS IS" BASIS,
    // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    // See the License for the specific language governing permissions and
    // limitations under the License.
    
    package topics
    
    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?