Crea un tema con SMT

En este documento, se explica cómo crear un tema de Pub/Sub con transformaciones de un solo mensaje (SMT).

Los SMT de temas permiten realizar modificaciones ligeras en los datos y atributos de los mensajes directamente en Pub/Sub. Esta función permite limpiar, filtrar o convertir el formato de los datos antes de que se publiquen los mensajes en el tema.

Para crear un tema con SMT, puedes usar la Trusted Cloud consola, Google Cloud CLI, la biblioteca cliente o la API de Pub/Sub.

Antes de comenzar

Roles y permisos requeridos

Para obtener los permisos que necesitas para crear un tema con SMT, pídele a tu administrador que te otorgue el rol de IAM de editor de Pub/Sub (roles/pubsub.editor) en tu proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para crear un tema con SMT. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para crear un tema con SMT:

  • Otorga el permiso para crear un tema en el proyecto: pubsub.topics.create

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Puedes configurar el control de acceso a nivel de proyecto y a nivel de los recursos individuales.

Crea un tema con SMT

Antes de crear un tema con SMT, revisa la documentación sobre las propiedades de un tema.

En los siguientes ejemplos, se supone que deseas crear un tema con esta SMT de función definida por el usuario (UDF). Para obtener más información sobre las UDF, consulta la descripción general de las UDF.

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

Console

  1. En la consola de Trusted Cloud , ve a la página Temas de Pub/Sub.

    Ir a temas

  2. Haz clic en Crear un tema.

    Se abrirá la página Crear tema.

  3. En el campo ID de tema, ingresa un ID para tu tema. Para obtener más información sobre cómo nombrar temas, consulta los lineamientos para asignar nombres.

  4. En Transformaciones, haz clic en Agregar una transformación.

  5. Ingresa un nombre de función. Por ejemplo: redactSSN.

  6. Si no quieres usar la SMT con tu tema de inmediato, haz clic en la opción Disable transform. Esto guardará el SMT, pero no se ejecutará a medida que los mensajes fluyan por tu tema.

  7. Ingresa una transformación nueva. Por ejemplo:

    function redactSSN(message, metadata) {
      const data = JSON.parse(message.data);
      delete data['ssn'];
      message.data = JSON.stringify(data);
      return message;
    }
  8. Pub/Sub proporciona una función de validación que te permite validar un SMT. Haz clic en Validar para validar la transformación.

  9. Si deseas agregar otra transformación, haz clic en Agregar una transformación.

  10. Para organizar todos los SMT en un orden específico, puedes usar las flechas hacia arriba y hacia abajo. Para quitar un SMT, haz clic en el botón de borrar.
  11. Pub/Sub proporciona una función de prueba que te permite verificar el resultado de ejecutar el SMT en un mensaje de muestra. Para probar las SMT, haz clic en Probar transformación.

  12. En la ventana Test transform, selecciona la función que deseas probar.

  13. En la ventana Input message, ingresa un mensaje de ejemplo.

  14. Si deseas agregar atributos de mensaje, haz clic en Agregar un atributo y, luego, ingresa uno o más pares clave-valor.

  15. Haga clic en Probar. Se muestra el resultado de aplicar las SMT al mensaje.

  16. Cierra la ventana para dejar de probar los SMT en mensajes de muestra.

  17. Haz clic en Crear para crear el tema.

gcloud

  1. In the Trusted Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Trusted 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. Pub/Sub proporciona una función de validación que te permite validar un SMT. Ejecuta el comando gcloud pubsub message-transforms validate:

    gcloud pubsub message-transforms validate --message-transform-file=TRANSFORM_FILE

    Reemplaza lo siguiente:

    • TRANSFORM_FILE: Es la ruta de acceso al archivo YAML o JSON que contiene un solo SMT.

      A continuación, se muestra un ejemplo de un archivo de transformación 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. Pub/Sub proporciona una función de prueba que te permite verificar el resultado de ejecutar uno o más SMT en un mensaje de muestra. Ejecuta el comando gcloud pubsub message-transforms test:

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

    Reemplaza lo siguiente:

    • TRANSFORMS_FILE: Es la ruta de acceso al archivo YAML o JSON que contiene uno o más SMT.

      A continuación, se muestra un ejemplo de un archivo de transformaciones 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: Es el cuerpo del mensaje con el que se probarán los SMT.

    • ATTRIBUTES: Son los atributos del mensaje con los que se probarán los SMT.

  4. Para crear el tema, ejecuta el comando gcloud pubsub topics create:

    gcloud pubsub topics create TOPIC_ID \
     --message-transforms-file=TRANSFORMS_FILE

    Reemplaza lo siguiente:

    • TOPIC_ID: Es el ID o el nombre del tema que deseas crear. Para obtener lineamientos sobre cómo asignar un nombre a un tema, consulta Nombres de recursos. El nombre de un tema es inmutable.

    • TRANSFORMS_FILE: Es la ruta de acceso al archivo YAML o JSON que contiene uno o más SMT.

      A continuación, se muestra un ejemplo de un archivo de transformaciones 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 probar esta muestra, sigue las instrucciones de configuración de Java en la guía de inicio rápido de Pub/Sub sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para Java.

    Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

    Antes de ejecutar muestras de código, configura la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.

    
    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 probar esta muestra, sigue las instrucciones de configuración de Python en la guía de inicio rápido de Pub/Sub sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para Python.

    Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

    Antes de ejecutar muestras de código, configura la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.

    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 probar esta muestra, sigue las instrucciones de configuración de Go en la guía de inicio rápido de Pub/Sub sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para Go.

    Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

    Antes de ejecutar muestras de código, configura la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.

    // 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"
    )
    
    // 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 := pubsub.MessageTransform{
    		Transform: pubsub.JavaScriptUDF{
    			FunctionName: "redactSSN",
    			Code:         code,
    		},
    	}
    	cfg := &pubsub.TopicConfig{
    		MessageTransforms: []pubsub.MessageTransform{transform},
    	}
    	t, err := client.CreateTopicWithConfig(ctx, topicID, cfg)
    	if err != nil {
    		return fmt.Errorf("CreateTopic: %w", err)
    	}
    
    	fmt.Fprintf(w, "Created topic with message transform: %v\n", t)
    	return nil
    }
    
    

¿Qué sigue?