Créer un sujet avec des SMT

Ce document explique comment créer un sujet Pub/Sub avec des transformations de message unique (SMT).

Les transformations de message unique de sujet permettent de modifier légèrement les données et les attributs des messages directement dans Pub/Sub. Cette fonctionnalité permet de nettoyer, de filtrer ou de convertir le format des données avant la publication des messages dans le sujet.

Pour créer un sujet avec des SMT, vous pouvez utiliser la console Google Cloud , la Google Cloud CLI, la bibliothèque cliente ou l'API Pub/Sub.

Avant de commencer

Découvrez le service Pub/Sub et sa terminologie.
En savoir plus sur les SMT

Rôles et autorisations nécessaires

Pour obtenir les autorisations nécessaires pour créer un thème avec des SMT, demandez à votre administrateur de vous accorder le rôle IAM Éditeur Pub/Sub (roles/pubsub.editor) sur votre projet. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ce rôle prédéfini contient les autorisations requises pour créer un thème avec des SMT. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Les autorisations suivantes sont requises pour créer un sujet avec des SMT :

Accordez l'autorisation de créer un sujet sur le projet : pubsub.topics.create

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Vous pouvez configurer le contrôle des accès au niveau du projet et au niveau de ressources individuelles.

Créer un sujet avec des SMT

Avant de créer un sujet avec des SMT, consultez la documentation sur les propriétés d'un sujet.

Pour créer un abonnement Pub/Sub avec un ou plusieurs SMT, procédez comme suit.

Console

Dans la console Google Cloud , accédez à la page Sujets de Pub/Sub.

Accéder aux sujets
Cliquez sur Create topic (Créer un sujet).
Dans le champ ID du sujet, saisissez un ID pour votre sujet. Pour en savoir plus sur l'attribution de noms aux thèmes, consultez les consignes de dénomination.
Sous Transformations, cliquez sur Ajouter une transformation.
Saisissez un nom de fonction. Exemple : redactSSN.
Si vous ne souhaitez pas que la SMT soit active immédiatement, sélectionnez Désactiver la transformation. Lorsque cette option est sélectionnée, le SMT est créé avec le sujet, mais n'est pas exécuté sur les messages entrants. Une fois le sujet créé, vous pouvez le modifier pour activer le SMT.

Dans la zone de texte, saisissez le code du SMT. Exemple :

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

Facultatif. Pour valider le SMT, cliquez sur Valider. Si le SMT est valide, le message "Validation passed" s'affiche. Dans le cas contraire, un message d'erreur s'affiche.
Pour ajouter une autre transformation, cliquez sur Ajouter une transformation et répétez les étapes précédentes.

Pour organiser les SMT dans un ordre spécifique, cliquez sur Déplacer vers le haut ou Déplacer vers le bas. Pour supprimer un SMT, cliquez sur Supprimer.
Facultatif. Pour tester un SMT sur un exemple de message, procédez comme suit :
1. Cliquez sur Tester les transformations.
2. Dans la fenêtre Tester la transformation, sélectionnez la fonction que vous souhaitez tester.
3. Dans la fenêtre Message d'entrée, saisissez un exemple de message.
4. Pour ajouter un attribut au message, cliquez sur Ajouter un attribut, puis saisissez la clé et la valeur de l'attribut. Vous pouvez ajouter plusieurs attributs.
5. Cliquez sur Test. Le résultat de l'application de la SMT au message s'affiche sous Message de sortie.
6. Pour fermer la fenêtre Tester les transformations, cliquez sur Fermer.
Si vous créez plusieurs SMT, vous pouvez tester l'ensemble de la séquence de transformations comme suit :
1. Testez le premier SMT de la séquence, comme décrit dans les étapes précédentes.
2. Sélectionnez le prochain SMT. Le message d'entrée est prérempli avec le message de sortie du test précédent.
3. Continuez à tester les SMT dans l'ordre pour vous assurer que l'ensemble de la séquence fonctionne comme prévu.
Pour créer le sujet, cliquez sur Créer.

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.

Créez un fichier YAML ou JSON qui définit un ou plusieurs SMT. Si vous avez plusieurs SMT, ils sont exécutés sur les messages dans l'ordre dans lequel vous les listez.

Voici un exemple de fichier de transformation 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

Facultatif. Pour valider un SMT, exécutez la commande gcloud pubsub message-transforms validate :
```
gcloud pubsub message-transforms validate \
  --message-transform-file=TRANSFORM_FILE
```
Remplacez les éléments suivants :
- TRANSFORM_FILE : chemin d'accès à un fichier YAML ou JSON qui définit un seul SMT. Si vous créez plusieurs SMT, vous devez les valider individuellement.
Facultatif. Pour tester un ou plusieurs SMT sur un exemple de message Pub/Sub, exécutez la commande gcloud pubsub message-transforms test :
```
gcloud pubsub message-transforms test \
  --message-transforms-file=TRANSFORMS_FILE \
  --message=MESSAGE \
  --attribute=ATTRIBUTES
```
Remplacez les éléments suivants :
- TRANSFORMS_FILE : chemin d'accès à un fichier YAML ou JSON qui définit un ou plusieurs SMT.
- MESSAGE : corps du message exemple.
- ATTRIBUTES : facultatif. Liste d'attributs de message séparés par une virgule. Chaque attribut est une paire clé/valeur au format KEY="VALUE".
La commande exécute les SMT dans l'ordre, en utilisant la sortie de chaque SMT comme entrée pour le suivant. La commande affiche les résultats de chaque étape.
Pour créer le sujet, exécutez la commande gcloud pubsub topics create :
```
gcloud pubsub topics create TOPIC_ID \
  --message-transforms-file=TRANSFORMS_FILE
```
Remplacez les éléments suivants :
- TOPIC_ID : ID ou nom de la rubrique que vous souhaitez créer. Pour obtenir des consignes sur la façon de nommer un sujet, consultez Noms de ressources. Le nom d'un thème est immuable.
- TRANSFORMS_FILE : chemin d'accès à un fichier YAML ou JSON qui définit un ou plusieurs SMT.

Java

Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage Java qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour Java.


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

Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage Python qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour Python.

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

L'exemple suivant utilise la version majeure de la bibliothèque cliente Go Pub/Sub (v2). Si vous utilisez toujours la bibliothèque v1, consultez le guide de migration vers la v2. Pour obtenir la liste des exemples de code de la version 1, consultez les exemples de code obsolètes.

Avant d'essayer cet exemple, suivez les instructions de configuration pour Go du guide de démarrage rapide : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour Go.

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
}

Créer un sujet avec des SMT Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Avant de commencer

Rôles et autorisations nécessaires

Autorisations requises

Créer un sujet avec des SMT

Console

gcloud

Java

Python

Go

Étapes suivantes

Créer un sujet avec des SMT