Abo mit SMTs erstellen

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

Mit Abo-SMTs können Sie Nachrichtendaten und ‑attribute direkt in Pub/Sub ändern. Mit dieser Funktion können Daten bereinigt, gefiltert oder in ein anderes Format konvertiert werden, 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.

Hinweise

• 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. Die genaue Liste der Berechtigungen finden Sie in dem Dokument, in dem das Erstellen des jeweiligen Abos beschrieben wird. Wenn Sie beispielsweise ein BigQuery-Abo mit SMTs erstellen, lesen Sie die Seite BigQuery-Abos erstellen.

Wenn Sie ein Abo in einem anderen Projekt als dem 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, sollten Sie sich die Dokumentation zu Eigenschaften eines Abos ansehen.

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 mit für unzustellbare Nachrichten weitergeleitet werden, enthalten ein Attribut CloudPubSubDeadLetterSourceSMTErrorMessage mit dem Grund für den SMT-Fehler.

So erstellen Sie ein Pub/Sub-Abo mit einem oder mehreren SMTs:

Console

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

   Zu den Abos

2. Klicken Sie auf Abo erstellen.

   Die Seite Abo erstellen wird geöffnet.

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

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

5. Geben Sie einen Funktionsnamen ein. Beispiel: redactSSN.

6. Wenn Sie nicht möchten, dass die SMT sofort aktiv ist, wählen Sie Transformation deaktivieren aus. Wenn diese Option ausgewählt ist, wird das SMT mit dem Abo erstellt, aber nicht für eingehende Nachrichten ausgeführt. Nachdem das Abo erstellt wurde, können Sie es bearbeiten, um die SMT zu aktivieren.

7. Geben Sie im Textbereich den Code für das SMT ein. Beispiel:

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

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

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

10. Optional. So testen Sie ein SMT mit einer Beispielnachricht:

    1. Klicken Sie auf Transformationen testen.

    2. Wählen Sie im Fenster Testtransformierung 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 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 Abfolge von Transformationen so testen:

    1. Testen Sie das erste 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.

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

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. Erstellen Sie eine YAML- oder JSON-Datei, in der ein oder mehrere SMTs definiert sind. Wenn Sie mehrere SMTs haben, werden sie für Nachrichten in der Reihenfolge ausgeführt, in der Sie sie auflisten.

   Hier ist ein Beispiel für eine YAML-Transformationsdatei:

   - 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. 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 ein einzelnes SMT definiert. Wenn Sie mehrere SMTs erstellen, müssen Sie sie einzeln validieren.

4. Optional. Führen Sie den Befehl gcloud pubsub message-transforms test aus, um einen oder mehrere SMTs für eine Beispiel-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, in der ein 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, das als KEY="VALUE" formatiert ist.

   Der Befehl führt die SMTs in der 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 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 zur YAML- oder JSON-Datei, in der ein oder mehrere SMTs definiert sind.

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 (v2) verwendet. Wenn Sie noch die v1-Bibliothek verwenden, finden Sie hier eine Anleitung zur Migration zu v2. Eine Liste der Codebeispiele für Version 1 finden Sie unter Eingestellte 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 Abofunktionen

Wenn in Ihrem Abo sowohl SMTs als auch die integrierten Filter von Pub/Sub verwendet werden, wird der Filter vor dem SMT angewendet. Dies 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 wurden.

Wenn Ihr SMT Nachrichten herausfiltert, sollten Sie sich über die Auswirkungen auf die Überwachung Ihres Abo-Rückstands im Klaren sein. Wenn Sie das Abo in eine Dataflow-Pipeline einfügen, filtern Sie Nachrichten nicht mit dem SMT heraus, da dies die automatische Skalierung von Dataflow beeinträchtigt.

Nächste Schritte

• Fehlerbehebung bei SMTs

• SMTs für Abos aktualisieren

• SMTs für Abos löschen