Abo mit SMTs erstellen

In diesem Dokument wird erläutert, wie Sie ein Pub/Sub-Abo mit Single Message Transforms (SMTs) erstellen.

Abo-SMTs ermöglichen direkt in Pub/Sub einfache Änderungen an Nachrichtendaten und -attributen. Mit dieser Funktion können Daten bereinigt, gefiltert oder formatiert werden, bevor die Nachrichten an einen Abonnentenclient gesendet werden.

Wenn Sie ein Abo mit SMTs erstellen möchten, können Sie die Google Cloud Console, die Google Cloud CLI, die Clientbibliothek oder die Pub/Sub API verwenden.

Hinweis

• Informationen zum Pub/Sub-Dienst und seiner Terminologie

• Weitere Informationen zu SMTs

Erforderliche Rollen und Berechtigungen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Pub/Sub-Bearbeiter (roles/pubsub.editor) für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Erstellen eines Abos mit SMTs benötigen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierte Rolle enthält die Berechtigungen, die zum Erstellen eines Abos mit SMTs erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen, um die notwendigen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um ein Abo mit SMTs zu erstellen:

• Erteilen Sie die Berechtigung zum Erstellen eines Abos für das Projekt: pubsub.subscriptions.create

Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

Je nach Abo sind möglicherweise zusätzliche Berechtigungen erforderlich. Eine genaue Liste der Berechtigungen finden Sie im Dokument zum Erstellen des jeweiligen Abos. Wenn Sie beispielsweise ein BigQuery-Abo mit SMTs erstellen, finden Sie weitere Informationen unter BigQuery-Abos erstellen.

Wenn Sie ein Abo in einem anderen Projekt als dem Thema erstellen, müssen Sie dem Hauptkonto des Projekts, das das Abo enthält, die Rolle roles/pubsub.subscriber im Projekt zuweisen, das das Thema enthält.

Sie können die Zugriffssteuerung auf Projektebene und auf der Ebene einzelner Ressourcen konfigurieren.

Abo mit SMTs erstellen

Bevor Sie ein Abo mit SMTs erstellen, lesen Sie die Dokumentation zu Eigenschaften eines Abos.

Hinweis: Es wird dringend empfohlen, ein Thema für unzustellbare Nachrichten für Abos mit SMTs zu konfigurieren. Nachrichten, die aufgrund von SMT-Fehlern an das Thema für unzustellbare Nachrichten weitergeleitet werden, enthalten das Attribut CloudPubSubDeadLetterSourceSMTErrorMessage mit dem Grund für den SMT-Fehler.

So erstellen Sie ein Pub/Sub-Abo mit einem oder mehreren SMTs: Sie können bis zu fünf SMTs pro Abo aktivieren.

Console

1. Rufen Sie in der Google Cloud Console die Seite „Pub/Sub“ → Abos auf.

   Zu den Abos

2. Klicken Sie auf Abo erstellen.

3. Geben Sie im Feld Abo-ID eine ID für Ihr Abo ein. Weitere Informationen zum Benennen von Abos finden Sie in den Benennungsrichtlinien.

4. Klicken Sie unter Transformationen auf Transformation hinzufügen.

5. Wählen Sie den Transformationstyp aus. Weitere Informationen zu den unterstützten SMT-Typen finden Sie unter SMT-Typen.

6. Konfigurationsattribute für das SMT festlegen Die Menge der Eigenschaften hängt vom Typ des SMT ab. Weitere Informationen finden Sie in der Dokumentation für den jeweiligen SMT-Typ.

7. Optional. Klicken Sie auf Validieren, um das SMT zu validieren. Wenn das SMT gültig ist, wird die Meldung "Validation passed" angezeigt. Andernfalls wird eine Fehlermeldung angezeigt.

8. Wenn Sie eine weitere Transformation hinzufügen möchten, klicken Sie auf Transformation hinzufügen und wiederholen Sie die vorherigen Schritte.

   Wenn Sie die SMTs in einer bestimmten Reihenfolge anordnen möchten, klicken Sie auf Nach oben oder Nach unten. Wenn Sie ein SMT entfernen möchten, klicken Sie auf  Löschen.

9. Optional. So testen Sie eine SMT an einer Beispielnachricht:

   1. Klicken Sie auf Transformationen testen.

   2. Wählen Sie im Fenster Transformation testen die Funktion aus, die Sie testen möchten.

   3. Geben Sie im Fenster Eingabenachricht eine Beispielnachricht ein.

   4. Wenn Sie der Mitteilung ein Attribut hinzufügen möchten, klicken Sie auf Attribut hinzufügen und geben Sie den Schlüssel und den Wert des Attributs ein. Sie können mehrere Attribute hinzufügen.

   5. Klicken Sie auf Testen. Das Ergebnis der Anwendung des SMT auf die Nachricht wird unter Ausgabemeldung angezeigt.

   6. Klicken Sie auf  Schließen, um das Fenster Transformationen testen zu schließen.

   Wenn Sie mehrere SMTs erstellen, können Sie die gesamte Transformationssequenz so testen:

   1. Testen Sie das erste SMT in der Sequenz, wie in den vorherigen Schritten beschrieben.
   2. Wählen Sie das nächste SMT aus. Die Eingabenachricht wird mit der Ausgabenachricht aus dem vorherigen Test vorab ausgefüllt.
   3. Testen Sie die SMTs der Reihe nach, um sicherzugehen, dass die gesamte Sequenz wie erwartet funktioniert.

10. Klicken Sie auf Erstellen, um das Abo zu erstellen.

gcloud

1. Aktivieren Sie Cloud Shell in der Google Cloud Console.

   Cloud Shell aktivieren

   Unten in der Google Cloud Console wird eine Cloud Shell-Sitzung gestartet und eine Eingabeaufforderung angezeigt. Cloud Shell ist eine Shell-Umgebung, in der das Google Cloud CLI bereits installiert ist und Werte für Ihr aktuelles Projekt bereits festgelegt sind. Das Initialisieren der Sitzung kann einige Sekunden dauern.

2. Erstellen Sie eine YAML- oder JSON-Datei, in der ein oder mehrere SMTs definiert sind. Die YAML- oder JSON-Definition hängt vom Typ des SMT ab. Weitere Informationen finden Sie unter Arten von SMTs.

   Wenn die Datei mehrere SMTs enthält, werden sie von Pub/Sub in der aufgeführten Reihenfolge ausgeführt.

3. Optional. Führen Sie den Befehl gcloud pubsub message-transforms validate aus, um ein SMT zu validieren:

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

   Ersetzen Sie Folgendes:

   • TRANSFORM_FILE: Der Pfad zu einer YAML- oder JSON-Datei, die eine einzelne SMT definiert. Wenn Sie mehrere SMTs erstellen, müssen Sie sie einzeln validieren.

4. Optional. Wenn Sie eine oder mehrere SMTs für eine Pub/Sub-Beispielnachricht testen möchten, führen Sie den Befehl gcloud pubsub message-transforms test aus:

   gcloud pubsub message-transforms test \
     --message-transforms-file=TRANSFORMS_FILE \
     --message=MESSAGE \
     --attribute=ATTRIBUTES
   

   Ersetzen Sie Folgendes:

   • TRANSFORMS_FILE: Der Pfad zu einer YAML- oder JSON-Datei, in der eine oder mehrere SMTs definiert sind.
   • MESSAGE: Der Text der Beispielnachricht.
   • ATTRIBUTES: Optional. Eine durch Kommas getrennte Liste von Nachrichtenattributen. Jedes Attribut ist ein Schlüssel/Wert-Paar im Format KEY="VALUE".

   Der Befehl führt die SMTs in der richtigen Reihenfolge aus und verwendet die Ausgabe jeder SMT als Eingabe für die nächste. Der Befehl gibt die Ergebnisse der einzelnen Schritte aus.

5. Führen Sie den Befehl gcloud pubsub subscriptions create aus, um das Abo zu erstellen:

   gcloud pubsub subscriptions create SUBSCRIPTION_ID \
       --topic=projects/PROJECT_ID/topics/TOPIC_ID \
       --message-transforms-file=TRANSFORMS_FILE
   

   Ersetzen Sie Folgendes:

   • SUBSCRIPTION_ID: Die ID oder der Name des Abos, das Sie erstellen möchten. Richtlinien zum Benennen eines Abos finden Sie unter Ressourcennamen. Der Name eines Abos kann nicht geändert werden.

   • PROJECT_ID: Die ID des Projekts, das das Thema enthält.

   • TOPIC_ID: Die ID des Themas, das abonniert werden soll.

   • TRANSFORMS_FILE: Der Pfad zur YAML- oder JSON-Datei, in der ein oder mehrere SMTs definiert sind.

C#

Bevor Sie dieses Beispiel testen, folgen Sie der Einrichtungsanleitung für C# in der Schnellstart-Anleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub C# API.

using Google.Cloud.PubSub.V1;
using System;

public class CreateSubscriptionWithSingleMessageTransformSample
{
    public Subscription CreateSubscriptionWithSingleMessageTransform(string projectId, string topicId, string subscriptionId)
    {
        SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
        TopicName topicName = TopicName.FromProjectTopic(projectId, topicId);

        SubscriptionName subscriptionName = SubscriptionName.FromProjectSubscription(projectId, subscriptionId);
        MessageTransform removeSSNTransform = new MessageTransform
        {
            JavascriptUdf = new JavaScriptUDF
            {
                FunctionName = "redactSsn",
                Code = "function redactSsn(message, metadata) {"
                + "   const data = JSON.parse(message.data);"
                + "   delete data['ssn'];"
                + "   message.data = JSON.stringify(data);"
                + "   return message;"
                + "}"
            },
        };

        var subscription = subscriber.CreateSubscription(new Subscription
        {
            SubscriptionName = subscriptionName,
            TopicAsTopicName = topicName,
            MessageTransforms = { removeSSNTransform },
        });
        Console.WriteLine($"Subscription {subscription.Name} created with SMT.");

        return subscription;
    }
}

Java

Bevor Sie dieses Beispiel testen, folgen Sie der Einrichtungsanleitung für Java in der Kurzanleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub Java API.

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

Bevor Sie dieses Beispiel testen, folgen Sie der Einrichtungsanleitung für Python in der Schnellstart-Anleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub Python API.

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

Im folgenden Beispiel wird die Hauptversion der Go Pub/Sub-Clientbibliothek (v2) verwendet. Wenn Sie noch die v1-Bibliothek verwenden, finden Sie hier die Migrationsanleitung zu v2. Eine Liste der Codebeispiele für Version 1 finden Sie unter Eingestellte Codebeispiele.

Bevor Sie dieses Beispiel ausprobieren, folgen Sie der Go-Einrichtungsanleitung in der Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub Go API.

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
}

Interaktion von SMTs mit anderen Abofunktionen

Beachten Sie bei der Verwendung eines Abo-SMT die folgenden Punkte.

Filtern

Wenn in Ihrem Abo sowohl SMTs als auch die integrierten Filter von Pub/Sub verwendet werden, wird der Filter vor dem SMT angewendet. Das hat folgende Auswirkungen:

• Wenn durch die SMT die Nachrichtenattribute geändert werden, wird der Pub/Sub-Filter nicht auf die neuen Attribute angewendet.
• Ihr SMT wird nicht auf Nachrichten angewendet, die vom Pub/Sub-Filter herausgefiltert werden.
• Wenn Ihr SMT Nachrichten herausfiltert, sollten Sie sich über die Auswirkungen auf die Überwachung Ihres Abo-Rückstands im Klaren sein.
• Wenn Sie ein Abo mit einer Dataflow-Pipeline verbinden, verwenden Sie kein Abo-SMT, um Nachrichten herauszufiltern, da dies die automatische Skalierung von Dataflow beeinträchtigt.

Nachrichtenreihenfolge

Wenn Sie eine SMT für ein Abo definieren, für das die Reihenfolge aktiviert ist, und beim Ausführen der SMT ein Fehler auftritt, werden nachfolgende Nachrichten für denselben Reihenfolgeschlüssel nicht an den Abonnenten zugestellt. Um dieses Problem zu vermeiden, richten Sie ein Thema für unzustellbare Nachrichten für das Abo ein, um die unverarbeitete Nachricht aus dem Nachrichten-Backlog zu entfernen.

Nächste Schritte

• Fehlerbehebung bei SMTs für Abos

• SMTs für Abos aktualisieren

• SMTs für Abos löschen