Abo mit SMTs erstellen

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

Mit SMTs für Abos können Sie Nachrichtendaten und -attribute direkt in Pub/Sub auf einfache Weise ändern. Mit dieser Funktion können Sie Daten bereinigen, filtern oder das Format konvertieren, bevor die Nachrichten an einen Abonnentenclient gesendet werden.

Sie können ein Abo mit SMTs über die Google Cloud console, die Google Cloud CLI, die Clientbibliothek oder die Pub/Sub API erstellen.

Hinweis

Informationen zum Pub/Sub-Dienst und zur Terminologie
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, die erforderlich sind:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind zum Erstellen eines Abos mit SMTs erforderlich:

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-Typ benötigen Sie möglicherweise zusätzliche Berechtigungen. Die genaue Liste der Berechtigungen finden Sie im Dokument zum Erstellen des jeweiligen Abos. Wenn Sie beispielsweise ein BigQuery-Abo mit SMTs erstellen, lesen Sie den Artikel BigQuery-Abos erstellen.

Wenn Sie ein Abo in einem anderen Projekt als das Thema erstellen, müssen Sie dem Prinzipal 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 den Eigenschaften eines Abos.

Führen Sie die folgenden Schritte aus, um ein Pub/Sub-Abo mit einem oder mehreren SMTs zu erstellen. Sie können bis zu fünf SMTs pro Abo aktivieren.

Console

Rufen Sie in der Google Cloud console die Seite Pub/Sub Abos auf.

Zu den Abos
Klicken Sie auf Abo erstellen.
Geben Sie im Feld Abo-ID eine ID für Ihr Abo ein. Weitere Informationen zum Benennen von Abos finden Sie in den Benennungsrichtlinien.
Klicken Sie unter Transformationen auf Transformation hinzufügen.
Wählen Sie den Transformationstyp aus. Weitere Informationen zu den unterstützten SMT Typen finden Sie unter SMT-Typen.
Legen Sie die Konfigurationseigenschaften für den SMT fest. Die Eigenschaften hängen vom Typ des SMT ab. Weitere Informationen finden Sie in der Dokumentation für den jeweiligen SMT-Typ.
Optional. Klicken Sie auf Validieren, um den SMT zu validieren. Wenn der SMT gültig ist, wird die Meldung "Validation passed" angezeigt. Andernfalls wird eine Fehlermeldung angezeigt.
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 verschieben oder Nach unten verschieben. Wenn Sie einen SMT entfernen möchten, klicken Sie auf Löschen.
Optional. So testen Sie einen SMT mit 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 Nachricht 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 Test. Das Ergebnis der Anwendung des SMT auf die Nachricht wird unter Ausgabenachricht 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 Sequenz von Transformationen so testen:
1. Testen Sie den ersten SMT in der Sequenz wie in den vorherigen Schritten beschrieben.
2. Wählen Sie den nächsten SMT aus. Die Eingabenachricht wird mit der Ausgabenachricht aus dem vorherigen Test vorab ausgefüllt.
3. Testen Sie die SMTs der Reihe nach, um sicherzustellen, dass die gesamte Sequenz wie erwartet funktioniert.
Klicken Sie auf Erstellen , um das Abo zu erstellen.

gcloud

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 Befehlszeilenaufforderung 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.
Erstellen Sie eine YAML- oder JSON-Datei, die einen oder mehrere SMTs definiert. Die YAML- oder JSON-Definition hängt vom Typ des SMT ab. Weitere Informationen finden Sie unter SMT-Typen.

Wenn die Datei mehrere SMTs enthält, werden sie von Pub/Sub in der aufgeführten Reihenfolge ausgeführt.
Optional. Führen Sie den gcloud pubsub message-transforms validate Befehl aus, um einen 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 einen einzelnen SMT definiert. Wenn Sie mehrere SMTs erstellen, müssen Sie sie einzeln validieren.
Optional. Führen Sie den gcloud pubsub message-transforms test Befehl aus, um einen oder mehrere SMTs mit einer Pub/Sub Nachricht zu testen:
```
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 die einen oder mehrere SMTs definiert.
- 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 der Reihe nach aus und verwendet die Ausgabe jedes SMT als Eingabe für den nächsten. Der Befehl gibt die Ergebnisse jedes Schritts aus.
Führen Sie den gcloud pubsub subscriptions create Befehl 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 ist unveränderlich.
- 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 zu einer YAML- oder JSON -Datei, die einen oder mehrere SMTs definiert.

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 zu 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 zu 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 (Version 2) verwendet. Wenn Sie noch die Version 1 verwenden, lesen Sie den Migrationsleitfaden zu Version 2. Eine Liste der Codebeispiele für Version 1 finden Sie unter Veraltete Codebeispiele.

Bevor Sie dieses Beispiel testen, folgen Sie der Einrichtungsanleitung für Go in der Schnellstart-Anleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zu 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 Abo-Funktionen

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

Filtern

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

Wenn Ihr SMT die Nachrichtenattribute ändert, 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, müssen Sie die Auswirkungen auf die Überwachung Ihres Abo-Backlogs berücksichtigen.
Wenn Sie ein Abo mit einer Dataflow-Pipelineverbinden, verwenden Sie keinen Abo-SMT, um Nachrichten herauszufiltern, da dies die automatische Skalierung von Dataflow stört.

Nachrichtenreihenfolge

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

Abo mit SMTs erstellen Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Hinweis

Erforderliche Rollen und Berechtigungen

Erforderliche Berechtigungen

Abo mit SMTs erstellen

Console

gcloud

Java

Python

Go

Interaktion von SMTs mit anderen Abo-Funktionen

Filtern

Nachrichtenreihenfolge

Nächste Schritte

Abo mit SMTs erstellen