Créer un sujet

Dans Pub/Sub, un sujet est une ressource nommée qui représente un flux de messages. Avant de pouvoir publier un sujet ou de vous y abonner, vous devez le créer. Pub/Sub est compatible avec deux types de sujets : un sujet standard et un sujet d'importation.

Ce document explique comment créer un sujet standard Pub/Sub. Pour en savoir plus sur les sujets d'importation et sur la manière d'en créer un, consultez À propos des sujets d'importation.

Pour créer un sujet, vous pouvez utiliser la Google Cloud console, 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.

• Découvrez le processus de publication.

Rôles et autorisations requis

Pour obtenir les autorisations nécessaires pour créer un sujet, 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 sujet. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

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. Vous pouvez créer un abonnement dans un projet et l'associer à un sujet situé dans un autre projet. Assurez-vous de disposer des autorisations requises pour chaque projet.

Propriétés d'un sujet

Lorsque vous créez ou mettez à jour un sujet, vous devez spécifier ses propriétés.

Ajouter un abonnement par défaut

Ajoute un abonnement par défaut au sujet Pub/Sub. Vous pouvez créer un autre abonnement pour le sujet après sa création. L'abonnement par défaut possède les propriétés suivantes :

• ID d'abonnement -sub
• Type de distribution : pull
• Durée de conservation des messages : sept jours
• Expiration après 31 jours d'inactivité
• Délai d'accusé de réception : 10 secondes
• Stratégie de nouvelle tentative : immédiate

Utiliser un schéma

Un schéma est un format que le champ de données du message doit respecter. Un schéma est un contrat entre l'éditeur et l'abonné que Pub/Sub applique. Les schémas de sujet permettent de standardiser les types de messages et les autorisations afin qu'ils puissent être utilisés par différentes équipes de votre organisation. Pub/Sub crée une autorité centrale pour les types de messages et les autorisations. Pour créer un sujet avec un schéma, consultez Présentation des schémas.

Activer l'ingestion

L'activation de cette propriété vous permet d'ingérer des données de streaming provenant de sources externes dans un sujet afin de pouvoir utiliser les fonctionnalités de Google Cloud. Pour créer un sujet d'importation pour l'ingestion, consultez les sections suivantes :

• Créer un sujet d'importation Amazon Kinesis Data Streams

• Créer un sujet d'importation Cloud Storage

• Créer un sujet Azure Event Hubs

• Créer un sujet Amazon MSK

• Créer un sujet Confluent Cloud

Activer la conservation des messages par sujet

Par défaut, un sujet Pub/Sub ignore les messages dès qu'ils sont confirmés par tous les abonnements associés au sujet. Vous pouvez également configurer un sujet pour qu'il conserve les messages pendant une période maximale de 31 jours, avec une durée de conservation minimale de 10 minutes.

La conservation des messages permet aux abonnements de relire les messages précédemment confirmés ou les messages publiés avant la création de l'abonnement. Pour en savoir plus, consultez la section Relire et supprimer définitivement des messages avec la recherche.

Les coûts de stockage des messages conservés par le sujet sont facturés au projet du sujet. Une fois la période de conservation des messages écoulée, Pub/Sub peut supprimer le message, quel que soit son état de confirmation.

Pour afficher les métriques concernant les messages conservés, utilisez les métriques Cloud Monitoring suivantes :

• topic/num_retained_messages: nombre de messages conservés
• topic/oldest_retained_message_age: âge du message conservé le plus ancien
• topic/retained_bytes: taille totale des messages conservés, en octets

Exporter les données des messages vers BigQuery

L'activation de cette propriété vous permet de créer un abonnement BigQuery qui écrit les messages dans une table BigQuery existante à mesure qu'ils sont reçus. Vous n'avez pas besoin de configurer un client abonné distinct. Pour en savoir plus sur les abonnements BigQuery, consultez Abonnements BigQuery.

Sauvegarder les données de message dans Cloud Storage

L'activation de cette propriété vous permet de créer un abonnement Cloud Storage qui écrit les messages dans une table Cloud Storage existante à mesure qu'ils sont reçus. Vous n'avez pas besoin de configurer un client abonné distinct. Pour en savoir plus sur les abonnements Cloud Storage, consultez Abonnements Cloud Storage.

Transformations

Les transformations de message unique par 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 que les messages ne soient publiés dans le sujet.

Pour en savoir plus sur les transformations de message unique, consultez Présentation des transformations de message unique.

Google-owned and Google-managed encryption key

Indique que le sujet est chiffré à l'aide de Google-owned and Google-managed encryption keys. Par défaut, Pub/Sub chiffre les messages avec Google-owned and Google-managed encryption keys . Par conséquent, le choix de cette option conserve le comportement par défaut. Google gère et alterne automatiquement les clés, ce qui garantit que vos messages sont toujours protégés par le chiffrement le plus puissant disponible. Cette option ne nécessite aucune configuration supplémentaire. Pour en savoir plus sur Google-owned and Google-managed encryption keys, consultez Chiffrement par défaut avec Google-owned and Google-managed encryption keys.

Clé Cloud KMS

Indique si le sujet est chiffré avec une clé de chiffrement gérée par le client (CMEK). Par défaut, Pub/Sub chiffre les messages avec Google-owned and Google-managed encryption keys . Si vous spécifiez cette option, Pub/Sub utilise le modèle de chiffrement encapsulé avec CMEK. Dans cette approche, Cloud KMS ne chiffre pas les messages. Au lieu de cela, Cloud KMS chiffre les clés de chiffrement des données (DEK) que Pub/Sub crée pour chaque sujet. Pub/Sub chiffre les messages à l'aide de la DEK la plus récente ayant été générée pour le sujet. Pub/Sub déchiffre les messages peu de temps avant qu'ils ne soient distribués aux abonnés. Pour en savoir plus sur la création d'une clé, consultez Configurer le chiffrement des messages.

Créer un sujet

Créez un sujet avant de pouvoir y publier des messages ou de vous y abonner.

PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID
Authorization: Bearer ACCESS_TOKEN

{
"name": "projects/PROJECT_ID/topics/TOPIC_ID"
}

namespace pubsub = ::google::cloud::pubsub;
namespace pubsub_admin = ::google::cloud::pubsub_admin;
[](pubsub_admin::TopicAdminClient client, std::string project_id,
   std::string topic_id) {
  auto topic = client.CreateTopic(
      pubsub::Topic(std::move(project_id), std::move(topic_id)).FullName());
  // Note that kAlreadyExists is a possible error when the library retries.
  if (topic.status().code() == google::cloud::StatusCode::kAlreadyExists) {
    std::cout << "The topic already exists\n";
    return;
  }
  if (!topic) throw std::move(topic).status();

  std::cout << "The topic was successfully created: " << topic->DebugString()
            << "\n";
}

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

public class CreateTopicSample
{
    public Topic CreateTopic(string projectId, string topicId)
    {
        PublisherServiceApiClient publisher = PublisherServiceApiClient.Create();
        var topicName = TopicName.FromProjectTopic(projectId, topicId);
        Topic topic = null;

        try
        {
            topic = publisher.CreateTopic(topicName);
            Console.WriteLine($"Topic {topic.Name} created.");
        }
        catch (RpcException e) when (e.Status.StatusCode == StatusCode.AlreadyExists)
        {
            Console.WriteLine($"Topic {topicName} already exists.");
        }
        return topic;
    }
}

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub/v2"
	"cloud.google.com/go/pubsub/v2/apiv1/pubsubpb"
)

func create(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()

	topic := &pubsubpb.Topic{
		Name: fmt.Sprintf("projects/%s/topics/%s", projectID, topicID),
	}
	t, err := client.TopicAdminClient.CreateTopic(ctx, topic)
	if err != nil {
		return fmt.Errorf("CreateTopic: %w", err)
	}
	fmt.Fprintf(w, "Topic created: %v\n", t)
	return nil
}

import com.google.cloud.pubsub.v1.TopicAdminClient;
import com.google.pubsub.v1.Topic;
import com.google.pubsub.v1.TopicName;
import java.io.IOException;

public class CreateTopicExample {
  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";

    createTopicExample(projectId, topicId);
  }

  public static void createTopicExample(String projectId, String topicId) throws IOException {
    try (TopicAdminClient topicAdminClient = TopicAdminClient.create()) {
      TopicName topicName = TopicName.of(projectId, topicId);
      Topic topic = topicAdminClient.createTopic(topicName);
      System.out.println("Created topic: " + topic.getName());
    }
  }
}

/**
 * TODO(developer): Uncomment this variable before running the sample.
 */
// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';

// Imports the Google Cloud client library
const {PubSub} = require('@google-cloud/pubsub');

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function createTopic(topicNameOrId) {
  // Creates a new topic
  await pubSubClient.createTopic(topicNameOrId);
  console.log(`Topic ${topicNameOrId} created.`);
}

/**
 * TODO(developer): Uncomment this variable before running the sample.
 */
// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';

// Imports the Google Cloud client library
import {PubSub} from '@google-cloud/pubsub';

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function createTopic(topicNameOrId: string) {
  // Creates a new topic
  await pubSubClient.createTopic(topicNameOrId);
  console.log(`Topic ${topicNameOrId} created.`);
}

use Google\Cloud\PubSub\PubSubClient;

/**
 * Creates a Pub/Sub topic.
 *
 * @param string $projectId  The Google project ID.
 * @param string $topicName  The Pub/Sub topic name.
 */
function create_topic($projectId, $topicName)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    $topic = $pubsub->createTopic($topicName);

    printf('Topic created: %s' . PHP_EOL, $topic->name());
}

from google.cloud import pubsub_v1

# TODO(developer)
# project_id = "your-project-id"
# topic_id = "your-topic-id"

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

topic = publisher.create_topic(request={"name": topic_path})

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

# topic_id = "your-topic-id"

pubsub = Google::Cloud::PubSub.new
topic_admin = pubsub.topic_admin

topic = topic_admin.create_topic name: pubsub.topic_path(topic_id)

puts "Topic #{topic.name} created."

Contraintes liées aux règles d'administration

Les règles d'administration peuvent limiter la création de sujets. Par exemple, une règle peut limiter le stockage des messages dans une région Compute Engine. Pour éviter les erreurs de création de sujets, examinez et mettez à jour les règles d'administration, si nécessaire, avant de créer un sujet.

Si votre projet a été créé récemment, attendez quelques minutes que la règle d'administration s'initialise avant de créer un sujet.

Accéder à la page Règles d'administration

Pour en savoir plus, consultez Configurer des règles de stockage des messages.

Étape suivante

• Choisissez le type d'abonnement pour votre sujet.

• Découvrez comment publier un message dans un sujet.

• Résolvez les problèmes liés à un sujet.

• Créez ou modifiez un sujet avec la gcloud CLI, les API REST, ou les bibliothèques clientes.