Crear un tema con SMTs

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

Los SMTs de temas permiten hacer 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 los mensajes se publiquen en el tema.

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

Antes de empezar

Consulta información sobre el servicio Pub/Sub y su terminología.
Consulta información sobre los SMTs.

Roles y permisos necesarios

Para obtener los permisos que necesitas para crear un tema con SMTs, pide a tu administrador que te conceda el rol de gestión de identidades y accesos Editor de Pub/Sub (roles/pubsub.editor) en tu proyecto. Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para crear un tema con SMTs. Para ver los permisos exactos que se necesitan, despliega la sección Permisos necesarios:

Permisos obligatorios

Para crear un tema con SMTs, se necesitan los siguientes permisos:

Concede el permiso para crear temas en el proyecto: pubsub.topics.create

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

Puede configurar el control de acceso a nivel de proyecto y de recurso individual.

Crear un tema con SMTs

Antes de crear un tema con SMTs, consulta la documentación sobre las propiedades de un tema.

Para crear un Pub/Sub con uno o varios SMTs, sigue estos pasos.

Consola

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

Ir a Temas
Haz clic en Crear tema.
En el campo ID de tema, introduce un ID para el tema. Para obtener más información sobre cómo poner nombre a los temas, consulta las directrices de nomenclatura.
En Transformaciones, haga clic en Añadir una transformación.
Escribe un nombre de función. Por ejemplo: redactSSN.
Si no quieres que la SMT se active inmediatamente, selecciona Inhabilitar transformación. Si se selecciona esta opción, se crea el SMT con el tema, pero no se ejecuta en los mensajes entrantes. Una vez creado el tema, puedes editarlo para habilitar el SMT.

En el área de texto, introduce el código de la SMT. Por ejemplo:

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

Opcional. Para validar la SMT, haz clic en Validar. Si el SMT es válido, se mostrará el mensaje "Validation passed". De lo contrario, se mostrará un mensaje de error.
Para añadir otra transformación, haz clic en Añadir una transformación y repite los pasos anteriores.

Para organizar las SMTs en un orden específico, haz clic en Mover hacia arriba o Mover hacia abajo. Para quitar una SMT, haz clic en Eliminar.
Opcional. Para probar una SMT en un mensaje de muestra, sigue estos pasos:
1. Haga clic en Probar transformaciones.
2. En la ventana Probar transformación, selecciona la función que quieras probar.
3. En la ventana Mensaje de entrada, introduce un mensaje de ejemplo.
4. Para añadir un atributo al mensaje, haz clic en Añadir un atributo e introduce la clave y el valor del atributo. Puedes añadir varios atributos.
5. Haz clic en Test (Probar). El resultado de aplicar la SMT al mensaje se muestra en Mensaje de salida.
6. Para cerrar la ventana Probar transformaciones, haz clic en Cerrar.
Si creas más de un SMT, puedes probar toda la secuencia de transformaciones de la siguiente manera:
1. Prueba el primer SMT de la secuencia, tal como se describe en los pasos anteriores.
2. Selecciona la siguiente SMT. El mensaje de entrada se rellena automáticamente con el mensaje de salida de la prueba anterior.
3. Sigue probando las SMTs en orden para asegurarte de que toda la secuencia funciona correctamente.
Para crear el tema, haz clic en Crear.

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.

Crea un archivo YAML o JSON que defina uno o varios SMTs. Si tienes más de un SMT, se ejecutarán en los mensajes en el orden en que los hayas indicado.

A continuación, se muestra un ejemplo de 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

Opcional. Para validar un SMT, ejecuta el comando gcloud pubsub message-transforms validate:
```
gcloud pubsub message-transforms validate \
  --message-transform-file=TRANSFORM_FILE
```
Haz los cambios siguientes:
- TRANSFORM_FILE: ruta a un archivo YAML o JSON que define un solo SMT. Si crea varias SMTs, debe validarlas individualmente.
Opcional. Para probar una o varias SMTs en un mensaje de Pub/Sub de ejemplo, ejecuta el comando gcloud pubsub message-transforms test:
```
gcloud pubsub message-transforms test \
  --message-transforms-file=TRANSFORMS_FILE \
  --message=MESSAGE \
  --attribute=ATTRIBUTES
```
Haz los cambios siguientes:
- TRANSFORMS_FILE: ruta a un archivo YAML o JSON que define una o varias SMTs.
- MESSAGE: el cuerpo del mensaje de ejemplo.
- ATTRIBUTES: opcional. Lista de atributos de mensaje separados por comas. Cada atributo es un par clave-valor con el formato KEY="VALUE".
El comando ejecuta las SMTs en orden, usando la salida de cada SMT como entrada de la siguiente. El comando muestra los resultados de cada paso.
Para crear el tema, ejecuta el comando gcloud pubsub topics create:
```
gcloud pubsub topics create TOPIC_ID \
  --message-transforms-file=TRANSFORMS_FILE
```
Haz los cambios siguientes:
- TOPIC_ID: el ID o el nombre del tema que quieras crear. Para obtener directrices sobre cómo asignar un nombre a un tema, consulta Nombres de recursos. El nombre de un tema es inmutable.
- TRANSFORMS_FILE: ruta a un archivo YAML o JSON que define una o varias SMTs.

Java

Antes de probar este ejemplo, sigue las instrucciones de configuración de Java que se indican en la guía de inicio rápido sobre cómo usar bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API de Java de 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 probar este ejemplo, sigue las instrucciones de configuración de Python que se indican en la guía de inicio rápido sobre cómo usar bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API de Python de 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")

Go

En el siguiente ejemplo se usa la versión principal de la biblioteca de cliente de Go Pub/Sub (v2). Si sigues usando la biblioteca v1, consulta la guía de migración a la versión 2. Para ver una lista de ejemplos de código de la versión 1, consulta los ejemplos de código obsoletos.

Antes de probar este ejemplo, sigue las instrucciones de configuración de Go que se indican en la guía de inicio rápido sobre cómo usar bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Go de 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
}

Crear un tema con SMTs Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Antes de empezar

Roles y permisos necesarios

Permisos obligatorios

Crear un tema con SMTs

Consola

gcloud

Java

Python

Go

Siguientes pasos

Crear un tema con SMTs