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 aos 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 enviadas para 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 Editor do Pub/Sub (roles/pubsub.editor) do IAM 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.

Para criar uma subscrição do Pub/Sub com um ou mais SMTs, siga os passos abaixo.

Consola

Na Google Cloud consola, aceda à página Subscrições do Pub/Sub.

Aceda a Subscrições
Clique em Criar subscrição.

É apresentada a página Criar subscrição.
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.
Em Transformações, clique em Adicionar uma transformação.
Introduza um nome de função. Por exemplo: redactSSN.
Se não quiser que a SMT esteja ativa imediatamente, selecione Desativar transformação. Quando esta opção é selecionada, o SMT é criado com a subscrição, mas não é executado em mensagens recebidas. Depois de criar a subscrição, pode editá-la para ativar a SMT.

Na área de texto, introduza o código do SMT. Por exemplo:

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

Opcional. Para validar o SMT, clique em Validar. Se o SMT for válido, é apresentada a mensagem "Validation passed". Caso contrário, é apresentada uma mensagem de erro.
Para adicionar outra transformação, clique em Adicionar uma transformação e repita os passos anteriores.

Para organizar os SMTs numa ordem específica, clique em Mover para cima ou Mover para baixo. Para remover um SMT, clique em Eliminar.
Opcional. Para testar um SMT numa mensagem de exemplo, siga estes passos:
1. Clique em Testar transformações.
2. Na janela Testar transformação, selecione a função que quer testar.
3. Na janela Introduzir mensagem, introduza uma mensagem de exemplo.
4. Para adicionar um atributo à mensagem, clique em Adicionar um atributo e introduza a chave e o valor do atributo. Pode adicionar vários atributos.
5. Clique em Testar. O resultado da aplicação da SMT na mensagem é apresentado em Mensagem de saída.
6. Para fechar a janela Testar transformações, clique em Fechar.
Se criar mais do que um SMT, pode testar toda a sequência de transformações da seguinte forma:
1. Teste o primeiro SMT na sequência, conforme descrito nos passos anteriores.
2. Selecione o SMT seguinte. A mensagem de entrada é pré-preenchida com a mensagem de saída do teste anterior.
3. Continue a testar os SMTs por ordem para se certificar de que toda a sequência funciona como esperado.
Clique em Criar para criar a subscrição.

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.

Crie um ficheiro YAML ou JSON que defina um ou mais SMTs. Se tiver mais do que um SMT, estes são executados nas mensagens pela ordem em que os indica.

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

Opcional. Para 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 um ficheiro YAML ou JSON que define um único SMT. Se estiver a criar vários SMTs, tem de validá-los individualmente.
Opcional. Para testar um ou mais SMTs numa mensagem Pub/Sub de amostra, execute o comando gcloud pubsub message-transforms test:
```
gcloud pubsub message-transforms test \
  --message-transforms-file=TRANSFORMS_FILE \
  --message=MESSAGE \
  --attribute=ATTRIBUTES
```
Substitua o seguinte:
- TRANSFORMS_FILE: o caminho para um ficheiro YAML ou JSON que define um ou mais SMTs.
- MESSAGE: o corpo da mensagem de amostra.
- ATTRIBUTES: opcional. Uma lista de atributos de mensagens separados por vírgulas. Cada atributo é um par de chave-valor formatado como KEY="VALUE".
O comando executa os SMTs por ordem, usando a saída de cada SMT como entrada para o seguinte. O comando produz os resultados de cada passo.
Para criar a subscrição, execute o comando gcloud pubsub subscriptions create:
```
gcloud pubsub subscriptions create SUBSCRIPTION_ID \
    --topic=projects/PROJECT_ID/topics/TOPIC_ID \
    --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.
- PROJECT_ID: o ID do projeto que contém o tópico.
- TOPIC_ID: o ID do tópico ao qual subscrever.
- TRANSFORMS_FILE: o caminho para o ficheiro YAML ou JSON que define um ou mais SMTs.

Java

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

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 instruções de configuração do Python no artigo Início rápido: usar bibliotecas cliente. Para mais informações, consulte a documentação de referência da 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}")

Ir

O exemplo seguinte usa a versão principal da biblioteca de cliente Go Pub/Sub (v2). Se ainda estiver a usar a biblioteca v1, consulte o guia de migração para a v2. Para ver uma lista de exemplos de código da v1, consulte os exemplos de código descontinuados.

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

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.

Crie uma subscrição com SMTs Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

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

Autorizações necessárias

Crie uma subscrição com SMTs

Consola

gcloud

Java

Python

Ir

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

O que se segue?

Crie uma subscrição com SMTs