Esta página se ha traducido con Cloud Translation API.

Crear una suscripción con SMTs

En este documento se explica cómo crear una suscripción de Pub/Sub con transformaciones de mensajes únicos (SMTs).

Los SMTs de suscripción 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 se envíen los mensajes a un cliente suscriptor.

Para crear una suscripción 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 una suscripción 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 el acceso a proyectos, carpetas y organizaciones.

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

Permisos obligatorios

Para crear una suscripción con SMTs, se necesitan los siguientes permisos:

Concede el permiso para crear una suscripción en el proyecto: pubsub.subscriptions.create

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

En función del tipo de suscripción, es posible que necesites permisos adicionales. Para consultar la lista exacta de permisos, consulta el documento en el que se explica cómo crear la suscripción específica. Por ejemplo, si vas a crear una suscripción a BigQuery con SMTs, consulta la página Crear suscripciones a BigQuery.

Si creas una suscripción en un proyecto distinto al del tema, debes asignar el rol roles/pubsub.subscriber al principal del proyecto que contiene la suscripción en el proyecto que contiene el tema.

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

Crear una suscripción con SMTs

Antes de crear una suscripción con SMTs, consulta la documentación sobre las propiedades de una suscripción.

En los siguientes ejemplos se da por hecho que quieres crear una suscripción con esta función definida por el usuario (UDF) SMT. Para obtener más información sobre las UDFs, consulta la descripción general de las UDFs.

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

Consola

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

Ir a Suscripciones
Haz clic en Crear suscripción.

Se abrirá la página Crear suscripción.
En el campo ID de suscripción, introduce un ID para tu suscripción. Para obtener más información sobre cómo asignar nombres a las suscripciones, 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 usar la SMT con tu suscripción inmediatamente, haz clic en la opción Inhabilitar transformación. De esta forma, se guardará el SMT, pero no se ejecutará a medida que los mensajes fluyan a través de tu suscripción.

Introduce una nueva transformación. Por ejemplo:

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

Pub/Sub proporciona una función de validación que te permite validar un SMT. Haz clic en Validar para validar la transformación.
Si quiere añadir otra transformación, haga clic en Añadir una transformación.
Para organizar todos los SMTs en un orden específico, puede usar las flechas hacia arriba y hacia abajo. Para eliminar una SMT, haz clic en el botón de eliminar.
Pub/Sub proporciona una función de prueba que te permite comprobar el resultado de ejecutar la SMT en un mensaje de muestra. Para probar las SMTs, haz clic en Probar transformación.
En la ventana Probar transformación, selecciona la función que quieras probar.
En la ventana Mensaje de entrada, introduce un mensaje de ejemplo.
Si quieres añadir atributos de mensaje, haz clic en Añadir un atributo e introduce uno o varios pares clave-valor.
Haz clic en Test (Probar). Se muestra el resultado de aplicar las SMTs al mensaje.
Cierra la ventana para dejar de probar las respuestas predefinidas en mensajes de muestra.
Haz clic en Crear para crear la suscripción.

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.

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

Haz los cambios siguientes:

TRANSFORM_FILE: ruta al archivo YAML o JSON que contiene un solo SMT.

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

Pub/Sub proporciona una función de prueba que te permite comprobar el resultado de ejecutar una o varias SMTs 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
```
Haz los cambios siguientes:
- TRANSFORMS_FILE: ruta al archivo YAML o JSON que contiene una o varias SMTs.
  
  A continuación se muestra un ejemplo de 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: cuerpo del mensaje con el que probar las SMTs.
- ATTRIBUTES: atributos del mensaje con los que probar los SMTs.
Para crear la suscripción, ejecuta el comando gcloud pubsub subscriptions create:
```
gcloud pubsub subscriptions create SUBSCRIPTION_ID \
    --topic=TOPIC_NAME \
    --message-transforms-file=TRANSFORMS_FILE
```
Haz los cambios siguientes:
- SUBSCRIPTION_ID: ID o nombre de la suscripción que quieras crear. Para obtener directrices sobre cómo asignar un nombre a una suscripción, consulta Nombres de recursos. El nombre de una suscripción es inmutable.
- TOPIC_NAME: el nombre del tema al que suscribirse, en el formato projects/PROJECT_ID/topics/TOPIC_ID.
- TRANSFORMS_FILE: la ruta al archivo YAML o JSON que contiene una o varias SMTs.
  
  A continuación se muestra un ejemplo de 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
```

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 de Pub/Sub con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Java Pub/Sub.

Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local.

import com.google.cloud.pubsub.v1.SubscriptionAdminClient;
import com.google.pubsub.v1.JavaScriptUDF;
import com.google.pubsub.v1.MessageTransform;
import com.google.pubsub.v1.ProjectSubscriptionName;
import com.google.pubsub.v1.ProjectTopicName;
import com.google.pubsub.v1.Subscription;
import java.io.IOException;

public class CreateSubscriptionWithSmtExample {
  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";
    String subscriptionId = "your-subscription-id";

    createSubscriptionWithSmtExample(projectId, topicId, subscriptionId);
  }

  public static void createSubscriptionWithSmtExample(
      String projectId, String topicId, String subscriptionId) throws IOException {

    // 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 (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {

      ProjectTopicName topicName = ProjectTopicName.of(projectId, topicId);
      ProjectSubscriptionName subscriptionName =
          ProjectSubscriptionName.of(projectId, subscriptionId);

      Subscription subscription =
          subscriptionAdminClient.createSubscription(
              Subscription.newBuilder()
                  .setName(subscriptionName.toString())
                  .setTopic(topicName.toString())
                  // Add the UDF message transform
                  .addMessageTransforms(transform)
                  .build());

      System.out.println("Created subscription with SMT: " + subscription.getAllFields());
    }
  }
}

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 de Pub/Sub con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Python Pub/Sub.

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

# TODO(developer): Choose an existing topic.
# project_id = "your-project-id"
# topic_id = "your-topic-id"
# subscription_id = "your-subscription-id"

publisher = pubsub_v1.PublisherClient()
subscriber = pubsub_v1.SubscriberClient()
topic_path = publisher.topic_path(project_id, topic_id)
subscription_path = subscriber.subscription_path(project_id, subscription_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)]

with subscriber:
    subscription = subscriber.create_subscription(
        request={
            "name": subscription_path,
            "topic": topic_path,
            "message_transforms": transforms,
        }
    )
    print(f"Created subscription with SMT: {subscription}")

Go

Antes de probar este ejemplo, sigue las instrucciones de configuración de Go que se indican en la guía de inicio rápido de Pub/Sub con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Go Pub/Sub.

// 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 subscriptions

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub"
)

// createSubscriptionWithSMT creates a subscription with a single message transform function applied.
func createSubscriptionWithSMT(w io.Writer, projectID, subID string, topic *pubsub.Topic) error {
	// projectID := "my-project-id"
	// subID := "my-sub"
	// topic of type https://godoc.org/cloud.google.com/go/pubsub#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.SubscriptionConfig{
		Topic:             topic,
		MessageTransforms: []pubsub.MessageTransform{transform},
	}
	sub, err := client.CreateSubscription(ctx, subID, cfg)
	if err != nil {
		return fmt.Errorf("CreateSubscription: %w", err)
	}
	fmt.Fprintf(w, "Created subscription with message transform: %v\n", sub)
	return nil
}

Cómo interactúan las SMTs con otras funciones de suscripción

Si tu suscripción usa tanto SMTs como filtros integrados de Pub/Sub, el filtro se aplica antes del SMT. Esto tiene las siguientes implicaciones:

Si tu SMT modifica los atributos del mensaje, el filtro de Pub/Sub no se aplica al nuevo conjunto de atributos.
Tu SMT no se aplicará a ningún mensaje que haya filtrado el filtro de Pub/Sub.

Si tu SMT filtra mensajes, ten en cuenta el impacto que tendrá en la monitorización de tu cartera de pedidos de suscripciones. Si insertas la suscripción en una pipeline de Dataflow, no filtres los mensajes con el SMT, ya que esto interrumpe el autoescalado de Dataflow.

Crear una suscripción 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 una suscripción con SMTs

Consola

gcloud

Java

Python

Go

Cómo interactúan las SMTs con otras funciones de suscripción

Siguientes pasos

Crear una suscripción con SMTs