Crie uma subscrição com SMTs

Este documento explica como criar uma subscrição do Pub/Sub com transformações de mensagens únicas (SMTs).

As SMTs de subscrição permitem modificações simples aos dados das mensagens e atributos diretamente no Pub/Sub. Esta funcionalidade permite a limpeza, a filtragem ou a conversão de formato de dados antes de as mensagens serem entregues a um cliente subscritor.

Para criar uma subscrição com SMTs, pode usar a Google Cloud consola, a Google Cloud CLI, a biblioteca cliente ou a API Pub/Sub.

Antes de começar

• Saiba mais sobre o serviço Pub/Sub e a respetiva terminologia.

• Saiba mais sobre os SMTs.

Funções e autorizações necessárias

Para obter as autorizações de que precisa para criar uma subscrição com SMTs, peça ao seu administrador para lhe conceder a função IAM de 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 uma subscrição 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

São necessárias as seguintes autorizações para criar uma subscrição com SMTs:

• Conceda a autorização para criar uma subscrição no projeto: pubsub.subscriptions.create

Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.

Consoante o tipo de subscrição, pode precisar de autorizações adicionais. Para saber a lista exata de autorizações, consulte o documento que aborda a criação da subscrição específica. Por exemplo, se estiver a criar uma subscrição do BigQuery com SMTs, consulte a página Crie subscrições do BigQuery.

Se criar uma subscrição num projeto diferente do tópico, tem de conceder a função roles/pubsub.subscriber ao principal do projeto que contém a subscrição no projeto que contém o tópico.

Pode configurar o controlo de acesso ao nível do projeto e ao nível do recurso individual.

Crie uma subscrição com SMTs

Antes de criar uma subscrição com SMTs, reveja a documentação sobre as Propriedades de uma subscrição.

Nota: recomendamos vivamente que configure um tópico de mensagens não entregues para subscrições com SMTs. As mensagens encaminhadas para o tópico de mensagens não entregues devido a falhas de SMT contêm um atributo CloudPubSubDeadLetterSourceSMTErrorMessage que indica o motivo da falha de SMT.

Os exemplos seguintes partem do princípio de que quer criar uma subscrição 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 Subscrições do Pub/Sub.

   Aceder a Subscrições

2. Clique em Criar subscrição.

   É apresentada a página Criar subscrição.

3. No campo ID da subscrição, introduza um ID para a sua subscrição. Para mais informações sobre a atribuição de nomes a subscrições, 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 a SMT com a sua subscrição imediatamente, clique na opção Desativar transformação. Esta ação continua a guardar o SMT, mas não o executa à medida que as mensagens fluem através da sua subscrição.

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 a subscrição.

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 a subscrição, execute o comando gcloud pubsub subscriptions create:

   gcloud pubsub subscriptions create SUBSCRIPTION_ID \
       --topic=TOPIC_NAME \
       --message-transforms-file=TRANSFORMS_FILE

   Substitua o seguinte:

   • SUBSCRIPTION_ID: o ID ou o nome da subscrição que quer criar. Para ver diretrizes sobre como atribuir um nome a uma subscrição, consulte o artigo Nomes de recursos. O nome de uma subscrição é imutável.

   • TOPIC_NAME: o nome do tópico ao qual subscrever, no formato projects/PROJECT_ID/topics/TOPIC_ID.

   • 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

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

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

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub/v2"
	"cloud.google.com/go/pubsub/v2/apiv1/pubsubpb"
)

// createSubscriptionWithSMT creates a subscription with a single message transform function applied.
func createSubscriptionWithSMT(w io.Writer, projectID, topicID, subID string) error {
	// projectID := "my-project-id"
	// topicID := "my-topic"
	// subID := "my-sub"
	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,
			},
		},
	}

	sub := &pubsubpb.Subscription{
		Name:              fmt.Sprintf("projects/%s/subscriptions/%s", projectID, subID),
		Topic:             fmt.Sprintf("projects/%s/topics/%s", projectID, topicID),
		MessageTransforms: []*pubsubpb.MessageTransform{transform},
	}
	sub, err = client.SubscriptionAdminClient.CreateSubscription(ctx, sub)
	if err != nil {
		return fmt.Errorf("CreateSubscription: %w", err)
	}
	fmt.Fprintf(w, "Created subscription with message transform: %v\n", sub)
	return nil
}

Como os SMTs interagem com outras funcionalidades de subscrição

Se a sua subscrição usar SMTs e filtros incorporados do Pub/Sub, o filtro é aplicado antes do SMT. Isto tem as seguintes implicações:

• Se o SMT alterar os atributos da mensagem, o filtro do Pub/Sub não é aplicado ao novo conjunto de atributos.
• O SMT não é aplicado a nenhuma mensagem que tenha sido filtrada pelo filtro do Pub/Sub.

Se o SMT filtrar mensagens, tenha em atenção o impacto na monitorização do atraso das subscrições. Se introduzir a subscrição num pipeline do Dataflow, não filtre as mensagens com o SMT, pois interrompe a escala automática do Dataflow.

O que se segue?

• Resolva problemas de SMTs

• Atualize os SMTs de subscrição

• Elimine os SMTs de subscrição