Thema mit SMTs erstellen

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

Mit Topic-SMTs können Nachrichtendaten und ‑attribute direkt in Pub/Sub leicht geändert werden. Mit dieser Funktion können Daten bereinigt, gefiltert oder in ein anderes Format konvertiert werden, bevor die Nachrichten im Thema veröffentlicht werden.

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

Hinweise

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 Themas 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 Themas mit SMTs erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen, um die notwendigen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

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

Erteilen Sie die Berechtigung zum Erstellen eines Themas für das Projekt: pubsub.topics.create

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

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

Thema mit SMTs erstellen

Bevor Sie ein Thema mit SMTs erstellen, sollten Sie sich die Dokumentation zu Eigenschaften eines Themas ansehen.

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

Console

Rufen Sie in der Google Cloud Console die Pub/Sub-Seite Themen auf.

Themen aufrufen
Klicken Sie auf Thema erstellen.
Geben Sie im Feld Themen-ID eine ID für das Thema ein. Weitere Informationen zur Benennung von Themen finden Sie in den Benennungsrichtlinien.
Klicken Sie unter Transformationen auf Transformation hinzufügen.
Geben Sie einen Funktionsnamen ein. Beispiel: redactSSN.
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 Thema erstellt, aber nicht für eingehende Nachrichten ausgeführt. Nachdem das Thema erstellt wurde, können Sie es bearbeiten, um die SMT zu aktivieren.

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;
}

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.
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.
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.
Klicken Sie auf Erstellen, um das Thema zu erstellen.

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.

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

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.
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.
Führen Sie den Befehl gcloud pubsub topics create aus, um das Thema zu erstellen:
```
gcloud pubsub topics create TOPIC_ID \
  --message-transforms-file=TRANSFORMS_FILE
```
Ersetzen Sie Folgendes:
- TOPIC_ID: Die ID oder der Name des Themas, das Sie erstellen möchten. Richtlinien zum Benennen eines Themas finden Sie unter Ressourcennamen. Der Name eines Themas kann nicht geändert werden.
- TRANSFORMS_FILE: Der Pfad zu einer 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.api.gax.rpc.AlreadyExistsException;
import com.google.cloud.pubsub.v1.TopicAdminClient;
import com.google.pubsub.v1.JavaScriptUDF;
import com.google.pubsub.v1.MessageTransform;
import com.google.pubsub.v1.Topic;
import com.google.pubsub.v1.TopicName;
import java.io.IOException;

public class CreateTopicWithSmtExample {

  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";

    createTopicWithSmtExample(projectId, topicId);
  }

  public static void createTopicWithSmtExample(String projectId, String topicId)
      throws IOException {
    TopicName topicName = TopicName.of(projectId, topicId);

    // 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 (TopicAdminClient topicAdminClient = TopicAdminClient.create()) {

      Topic topic =
          topicAdminClient.createTopic(
              Topic.newBuilder()
                  .setName(topicName.toString())
                  // Add the UDF message transform
                  .addMessageTransforms(transform)
                  .build());

      System.out.println("Created topic with SMT: " + topic.getName());
    } catch (AlreadyExistsException e) {
      System.out.println(topicName + "already exists.");
    }
  }
}

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, Topic

# TODO(developer)
# project_id = "your-project-id"
# topic_id = "your-topic-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)]

publisher = pubsub_v1.PublisherClient()
topic_path = publisher.topic_path(project_id, topic_id)

request = Topic(name=topic_path, message_transforms=transforms)

topic = publisher.create_topic(request=request)

print(f"Created topic: {topic.name} with SMT")

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"
)

// createTopicWithSMT creates a topic with a single message transform function applied.
func createTopicWithSMT(w io.Writer, projectID, topicID string) error {
	// projectID := "my-project-id"
	// topicID := "my-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 := &pubsubpb.MessageTransform{
		Transform: &pubsubpb.MessageTransform_JavascriptUdf{
			JavascriptUdf: &pubsubpb.JavaScriptUDF{
				FunctionName: "redactSSN",
				Code:         code,
			},
		},
	}

	topic := &pubsubpb.Topic{
		Name:              fmt.Sprintf("projects/%s/topics/%s", projectID, topicID),
		MessageTransforms: []*pubsubpb.MessageTransform{transform},
	}

	topic, err = client.TopicAdminClient.CreateTopic(ctx, topic)
	if err != nil {
		return fmt.Errorf("CreateTopic: %w", err)
	}

	fmt.Fprintf(w, "Created topic with message transform: %v\n", topic)
	return nil
}

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

Hinweise

Erforderliche Rollen und Berechtigungen

Erforderliche Berechtigungen

Thema mit SMTs erstellen

Console

gcloud

Java

Python

Go

Nächste Schritte

Thema mit SMTs erstellen