Creare una sottoscrizione con SMT

Questo documento spiega come creare una sottoscrizione Pub/Sub con Single Message Transform (SMT).

Le SMT di sottoscrizione consentono modifiche leggere ai dati e agli attributi dei messaggi direttamente in Pub/Sub. Questa funzionalità consente la pulizia, il filtraggio o la conversione del formato dei dati prima che i messaggi vengano inviati a un client abbonato.

Per creare una sottoscrizione con SMT, puoi utilizzare la Trusted Cloud console, Google Cloud CLI, la libreria client o l'API Pub/Sub.

Prima di iniziare

Ruoli e autorizzazioni richiesti

Per ottenere le autorizzazioni necessarie per creare un abbonamento con SMT, chiedi all'amministratore di concederti il ruolo IAM Pub/Sub Editor (roles/pubsub.editor) nel progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene le autorizzazioni necessarie per creare un abbonamento con SMT. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per creare un abbonamento con SMT sono necessarie le seguenti autorizzazioni:

  • Concedi l'autorizzazione per creare una sottoscrizione nel progetto: pubsub.subscriptions.create

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

A seconda del tipo di abbonamento, potresti aver bisogno di autorizzazioni aggiuntive. Per scoprire l'elenco esatto delle autorizzazioni, consulta il documento che illustra la creazione dell'abbonamento specifico. Ad esempio, se stai creando una sottoscrizione BigQuery con SMT, consulta la pagina Creare sottoscrizioni BigQuery.

Se crei una sottoscrizione in un progetto diverso da quello dell'argomento, devi concedere il ruolo roles/pubsub.subscriber all'entità del progetto che contiene la sottoscrizione nel progetto che contiene l'argomento.

Puoi configurare il controllo dell'accesso a livello di progetto e a livello di singola risorsa.

Creare una sottoscrizione con SMT

Prima di creare un abbonamento con SMT, consulta la documentazione relativa alle proprietà di un abbonamento.

I seguenti esempi presuppongono che tu voglia creare un abbonamento con questa funzione definita dall'utente SMT. Per saperne di più sulle UDF, consulta la panoramica delle UDF.

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

Console

  1. Nella console Trusted Cloud , vai alla pagina Sottoscrizioni di Pub/Sub.

    Vai agli abbonamenti

  2. Fai clic su Crea sottoscrizione.

    Viene visualizzata la pagina Crea sottoscrizione.

  3. Nel campo ID abbonamento, inserisci un ID per l'abbonamento. Per ulteriori informazioni sulla denominazione degli abbonamenti, consulta le linee guida per la denominazione.

  4. In Trasformazioni, fai clic su Aggiungi una trasformazione.

  5. Inserisci un nome di funzione. Ad esempio: redactSSN.

  6. Se non vuoi utilizzare la SMT con il tuo abbonamento immediatamente, fai clic sull'opzione Disattiva trasformazione. L'SMT verrà comunque salvato, ma non verrà eseguito man mano che i messaggi scorrono nella sottoscrizione.

  7. Inserisci una nuova trasformazione. Ad esempio:

    function redactSSN(message, metadata) {
      const data = JSON.parse(message.data);
      delete data['ssn'];
      message.data = JSON.stringify(data);
      return message;
    }
  8. Pub/Sub fornisce una funzione di convalida che consente di convalidare un SMT. Fai clic su Convalida per convalidare la trasformazione.

  9. Se vuoi aggiungere un'altra trasformazione, fai clic su Aggiungi una trasformazione.

  10. Per disporre tutti gli SMT in un ordine specifico, puoi utilizzare le frecce su e giù. Per rimuovere un SMT, fai clic sul pulsante di eliminazione.
  11. Pub/Sub fornisce una funzione di test che consente di controllare il risultato dell'esecuzione di SMT su un messaggio di esempio. Per testare le SMT, fai clic su Testa trasformazione.

  12. Nella finestra Testa trasformazione, seleziona la funzione che vuoi testare.

  13. Nella finestra Messaggio di input, inserisci un messaggio di esempio.

  14. Se vuoi aggiungere attributi del messaggio, fai clic su Aggiungi un attributo e inserisci una o più coppie chiave-valore.

  15. Fai clic su Test. Viene visualizzato il risultato dell'applicazione delle SMT al messaggio.

  16. Chiudi la finestra per interrompere il test delle SMT sui messaggi di esempio.

  17. Fai clic su Crea per creare l'abbonamento.

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 fornisce una funzione di convalida che consente di convalidare un SMT. Esegui il comando gcloud pubsub message-transforms validate:

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

    Sostituisci quanto segue:

    • TRANSFORM_FILE: il percorso del file YAML o JSON contenente un singolo SMT.

      Ecco un esempio di file di trasformazione 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 fornisce una funzione di test che consente di controllare il risultato dell'esecuzione di una o più SMT su un messaggio di esempio. Esegui il comando gcloud pubsub message-transforms test:

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

    Sostituisci quanto segue:

    • TRANSFORMS_FILE: il percorso del file YAML o JSON contenente uno o più SMT.

      Ecco un esempio di file di trasformazioni 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 del messaggio con cui testare gli SMT.

    • ATTRIBUTES: Attributi del messaggio con cui testare le SMT.

  4. Per creare l'abbonamento, esegui il comando gcloud pubsub subscriptions create:

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

    Sostituisci quanto segue:

    • SUBSCRIPTION_ID: l'ID o il nome dell'abbonamento che vuoi creare. Per le linee guida su come denominare un abbonamento, vedi Nomi delle risorse. Il nome di un abbonamento è immutabile.

    • TOPIC_NAME: Il nome dell'argomento a cui abbonarsi, nel formato projects/PROJECT_ID/topics/TOPIC_ID.

    • TRANSFORMS_FILE: Il percorso del file YAML o JSON contenente uno o più SMT.

      Ecco un esempio di file di trasformazioni 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

    Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di Pub/Sub per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Java.

    Per eseguire l'autenticazione in Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

    Prima di eseguire gli esempi di codice, imposta la variabile di ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN su s3nsapis.fr.

    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

    Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di Pub/Sub per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Python.

    Per eseguire l'autenticazione in Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

    Prima di eseguire gli esempi di codice, imposta la variabile di ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN su s3nsapis.fr.

    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

    Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella guida rapida di Pub/Sub per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Go.

    Per eseguire l'autenticazione in Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

    Prima di eseguire gli esempi di codice, imposta la variabile di ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN su 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 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
    }
    
    

Come interagiscono gli SMT con altre funzionalità di abbonamento

Se il tuo abbonamento utilizza sia SMT sia i filtri integrati di Pub/Sub, il filtro viene applicato prima dell'SMT. Ciò comporta le seguenti implicazioni:

  • Se il tuo SMT modifica gli attributi del messaggio, il filtro Pub/Sub non viene applicato al nuovo insieme di attributi.
  • Il tuo SMT non verrà applicato ai messaggi filtrati dal filtro Pub/Sub.

Se il tuo SMT filtra i messaggi, tieni presente l'impatto sul monitoraggio del backlog degli abbonamenti. Se inserisci l'abbonamento in una pipeline Dataflow, non filtrare i messaggi utilizzando SMT, in quanto interrompe la scalabilità automatica di Dataflow.

Passaggi successivi