Créer des abonnements pull

Ce document explique comment créer un abonnement pull. Vous pouvez utiliser la console Cloud de Confiance , Google Cloud CLI, la bibliothèque cliente ou l'API Pub/Sub pour créer un abonnement pull.

Avant de commencer

Rôles et autorisations nécessaires

Pour obtenir les autorisations nécessaires pour créer un abonnement par extraction, demandez à votre administrateur de vous accorder le rôle IAM Éditeur Pub/Sub (roles/pubsub.editor) sur le 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 abonnement pull. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Les autorisations suivantes sont requises pour créer un abonnement pull :

  • pubsub.subscriptions.create sur le projet
  • pubsub.topics.attachSubscription sur le thème

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

Abonnements interprojets

Si vous créez un abonnement dans un projet pour un sujet dans un autre projet, vous devez disposer de l'autorisation pubsub.subscriptions.create dans le projet dans lequel vous créez l'abonnement et de l'autorisation pubsub.topics.attachSubscription sur le sujet.

Créer un abonnement pull

Console

Pour créer un abonnement pull, procédez comme suit :

  1. Dans la console Cloud de Confiance , accédez à la page Abonnements.

    Accéder à "Abonnements"

  2. Cliquez sur Créer un abonnement.

  3. Dans le champ ID d'abonnement, saisissez un nom.

    Pour savoir comment nommer un abonnement, consultez Consignes de dénomination d'un sujet ou d'un abonnement.

  4. Dans la liste Sujet Pub/Sub, sélectionnez un sujet à partir duquel l'abonnement doit lire les messages.

  5. Pour Type de distribution, sélectionnez Pull.

  6. (Facultatif) Dans la section Transformations, ajoutez une ou plusieurs transformations de message unique (SMT). Pour en savoir plus, consultez Créer un abonnement avec des SMT.

  7. Facultatif : Dans le champ Filtre, saisissez une expression de filtre pour filtrer les messages de l'abonnement. Pour en savoir plus, consultez Filtrer les messages d'un abonnement.

  8. Pour Stratégie de nouvelle tentative, sélectionnez une option. Pour en savoir plus, consultez la Politique de relance des abonnements.

  9. Facultatif : activez une file d'attente de lettres mortes pour recevoir les messages non distribuables.

    1. Cochez la case Mise en file d'attente de lettres mortes.

    2. Dans la liste Thème de messages non distribués, sélectionnez ou créez le thème de messages non distribués.

    3. Dans le champ Nombre maximal de tentatives d'envoi, saisissez le nombre maximal de tentatives d'envoi.

  10. Facultatif : Dans la section Propriétés de diffusion, activez ou désactivez les options de diffusion suivantes :

  11. Facultatif : Dans la section Délai de confirmation, définissez le délai dont dispose l'abonné pour traiter et confirmer les messages. Pour en savoir plus, consultez Prolonger le délai d'accusé de réception avec la gestion des baux.

  12. Facultatif : Dans la section Options de durée de vie, configurez la durée pendant laquelle l'abonnement conserve les messages.

    1. Dans la section Durée de conservation des messages, spécifiez la durée de conservation des messages non reconnus.

    2. Pour conserver les messages confirmés et non confirmés, cochez la case Conserver les messages confirmés.

    Pour en savoir plus, consultez Configurer la conservation des messages pour un abonnement.

  13. Facultatif : Pour Période d'expiration, sélectionnez une option :

    1. Pour définir l'expiration de l'abonnement, cochez la case Expire après ce nombre de jours d'inactivité. Saisissez le nombre de jours pendant lesquels l'abonnement peut rester inactif avant que Pub/Sub ne le supprime.

    2. Pour désactiver l'expiration de l'abonnement, cochez la case Jamais.

    Pour en savoir plus, consultez Expiration de l'abonnement.

  14. Cliquez sur Créer.

Vous pouvez également créer un abonnement à partir de la section Sujets. Ce raccourci est utile pour associer des sujets à des abonnements.

  1. Dans la console Cloud de Confiance , accédez à la page Sujets.

    Accéder aux sujets

  2. Cliquez sur à côté du sujet pour lequel vous souhaitez créer un abonnement.

  3. Dans le menu contextuel, sélectionnez Créer un abonnement.

  4. Sur la page Ajouter un abonnement au sujet, suivez les étapes décrites dans la procédure précédente. L'ID de la chaîne est automatiquement renseigné.

gcloud

  1. Dans la console Cloud de Confiance , activez Cloud Shell.

    Activer Cloud Shell

    En bas de la console Cloud de Confiance , une session Cloud Shell démarre et affiche une invite de ligne de commande. Cloud Shell est un environnement shell dans lequel Google Cloud CLI est déjà installé, et dans lequel des valeurs sont déjà définies pour votre projet actuel. L'initialisation de la session peut prendre quelques secondes.

  2. Pour créer un abonnement pull, exécutez la commande gcloud pubsub subscriptions create.
    gcloud pubsub subscriptions create SUBSCRIPTION_ID --topic=TOPIC_ID

    Remplacez les éléments suivants :

    • SUBSCRIPTION_ID : nom ou ID de votre nouvel abonnement pull.
    • TOPIC_ID : nom ou ID de votre thème.

REST

Pour créer un abonnement pull, utilisez la méthode projects.subscriptions.create :

Requête :

La demande doit être authentifiée à l'aide d'un jeton d'accès dans l'en-tête Authorization. Pour obtenir un jeton d'accès pour les Identifiants par défaut de l'application actuelle : gcloud auth application-default print-access-token.

PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID
Authorization: Bearer ACCESS_TOKEN

Corps de la requête :

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

Où :

  • PROJECT_ID est l'ID de votre projet.
  • SUBSCRIPTION_ID est l'ID de votre abonnement.
  • TOPIC_ID est l'ID de votre sujet.

Réponse :

{
"name": "projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID",
"topic": "projects/PROJECT_ID/topics/TOPIC_ID",
"pushConfig": {},
"ackDeadlineSeconds": 10,
"messageRetentionDuration": "604800s",
"expirationPolicy": {
"ttl": "2678400s"
}
}

C++

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

namespace pubsub_admin = ::google::cloud::pubsub_admin;
namespace pubsub = ::google::cloud::pubsub;
[](pubsub_admin::SubscriptionAdminClient client,
   std::string const& project_id, std::string const& topic_id,
   std::string const& subscription_id) {
  google::pubsub::v1::Subscription request;
  request.set_name(
      pubsub::Subscription(project_id, subscription_id).FullName());
  request.set_topic(pubsub::Topic(project_id, topic_id).FullName());
  auto sub = client.CreateSubscription(request);
  if (sub.status().code() == google::cloud::StatusCode::kAlreadyExists) {
    std::cout << "The subscription already exists\n";
    return;
  }
  if (!sub) throw std::move(sub).status();

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

C#

Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage C# 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 de l'API Pub/Sub C#.


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

public class CreateSubscriptionSample
{
    public Subscription CreateSubscription(string projectId, string topicId, string subscriptionId)
    {
        SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
        TopicName topicName = TopicName.FromProjectTopic(projectId, topicId);

        SubscriptionName subscriptionName = SubscriptionName.FromProjectSubscription(projectId, subscriptionId);
        Subscription subscription = null;

        try
        {
            subscription = subscriber.CreateSubscription(subscriptionName, topicName, pushConfig: null, ackDeadlineSeconds: 60);
        }
        catch (RpcException e) when (e.Status.StatusCode == StatusCode.AlreadyExists)
        {
            // Already exists.  That's fine.
        }
        return subscription;
    }
}

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 v1, consultez les exemples de code obsolètes.

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

import (
	"context"
	"fmt"
	"io"

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

func create(w io.Writer, projectID, topic, subscription string) error {
	// projectID := "my-project-id"
	// topic := "projects/my-project-id/topics/my-topic"
	// subscription := "projects/my-project/subscriptions/my-sub"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %w", err)
	}
	defer client.Close()

	sub, err := client.SubscriptionAdminClient.CreateSubscription(ctx, &pubsubpb.Subscription{
		Name:  subscription,
		Topic: topic,
	})
	if err != nil {
		return fmt.Errorf("CreateSubscription: %w", err)
	}
	fmt.Fprintf(w, "Created subscription: %v\n", sub)
	return nil
}

Java

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


import com.google.cloud.pubsub.v1.SubscriptionAdminClient;
import com.google.pubsub.v1.PushConfig;
import com.google.pubsub.v1.Subscription;
import com.google.pubsub.v1.SubscriptionName;
import com.google.pubsub.v1.TopicName;
import java.io.IOException;

public class CreatePullSubscriptionExample {
  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String subscriptionId = "your-subscription-id";
    String topicId = "your-topic-id";

    createPullSubscriptionExample(projectId, subscriptionId, topicId);
  }

  public static void createPullSubscriptionExample(
      String projectId, String subscriptionId, String topicId) throws IOException {
    try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {
      TopicName topicName = TopicName.of(projectId, topicId);
      SubscriptionName subscriptionName = SubscriptionName.of(projectId, subscriptionId);
      // Create a pull subscription with default acknowledgement deadline of 10 seconds.
      // Messages not successfully acknowledged within 10 seconds will get resent by the server.
      Subscription subscription =
          subscriptionAdminClient.createSubscription(
              subscriptionName, topicName, PushConfig.getDefaultInstance(), 10);
      System.out.println("Created pull subscription: " + subscription.getName());
    }
  }
}

Node.js

Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage Node.js 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 de l'API Pub/Sub en langage Node.js.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_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 createSubscription(topicNameOrId, subscriptionNameOrId) {
  // Creates a new subscription
  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId);
  console.log(`Subscription ${subscriptionNameOrId} created.`);
}

Node.ts

Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage Node.js 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 de l'API Pub/Sub en langage Node.js.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_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 createSubscription(
  topicNameOrId: string,
  subscriptionNameOrId: string,
) {
  // Creates a new subscription
  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId);
  console.log(`Subscription ${subscriptionNameOrId} created.`);
}

PHP

Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage PHP 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 de l'API Pub/Sub en langage PHP.

use Google\Cloud\PubSub\PubSubClient;

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

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

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 de l'API Pub/Sub en langage Python.

from google.cloud import pubsub_v1

# TODO(developer)
# 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)

# Wrap the subscriber in a 'with' block to automatically call close() to
# close the underlying gRPC channel when done.
with subscriber:
    subscription = subscriber.create_subscription(
        request={"name": subscription_path, "topic": topic_path}
    )

print(f"Subscription created: {subscription}")

Ruby

L'exemple suivant utilise la bibliothèque cliente Ruby Pub/Sub v3. Si vous utilisez toujours la bibliothèque v2, consultez le guide de migration vers la v3. Pour obtenir la liste des exemples de code Ruby v2, consultez les exemples de code obsolètes.

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

# topic_id        = "your-topic-id"
# subscription_id = "your-subscription-id"

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

subscription = subscription_admin.create_subscription \
  name: pubsub.subscription_path(subscription_id),
  topic: pubsub.topic_path(topic_id)

puts "Pull subscription #{subscription_id} created."

Rust

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

use google_cloud_pubsub::client::SubscriptionAdmin;

pub async fn sample(
    client: &SubscriptionAdmin,
    project_id: &str,
    topic_id: &str,
    subscription_id: &str,
) -> anyhow::Result<()> {
    let subscription_name = format!("projects/{project_id}/subscriptions/{subscription_id}");
    let topic_name = format!("projects/{project_id}/topics/{topic_id}");

    let subscription = client
        .create_subscription()
        .set_name(subscription_name)
        .set_topic(topic_name)
        .send()
        .await?;

    println!("successfully created subscription {subscription:?}");
    Ok(())
}

Surveiller les abonnements pull

Cloud Monitoring fournit un certain nombre de métriques pour surveiller les abonnements.

Pour obtenir la liste de toutes les métriques disponibles liées à Pub/Sub et leurs descriptions, consultez la documentation sur la surveillance de Pub/Sub.

Vous pouvez également surveiller les abonnements dans Pub/Sub.

Étapes suivantes