Créer des abonnements pull

Ce document explique comment créer un abonnement pull. Vous pouvez utiliser la console Google Cloud, 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 requis

Pour créer un abonnement, vous devez configurer le contrôle des accès au niveau du projet. Vous avez également besoin d'autorisations au niveau des ressources si vos abonnements et vos sujets se trouvent dans différents projets, comme indiqué plus loin dans cette section.

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

Autorisations requises

Les autorisations suivantes sont requises pour créer des abonnements pull:

  • Extraire à partir d'un abonnement : pubsub.subscriptions.consume
  • Créez un abonnement : pubsub.subscriptions.create
  • Supprimer un abonnement : pubsub.subscriptions.delete
  • Obtenir un abonnement : pubsub.subscriptions.get
  • Lister un abonnement : pubsub.subscriptions.list
  • Modifier un abonnement : pubsub.subscriptions.update
  • Joindre un abonnement à un sujet : pubsub.topics.attachSubscription
  • Obtenez la stratégie IAM d'un abonnement : pubsub.subscriptions.getIamPolicy
  • Configurez la stratégie IAM pour un abonnement : pubsub.subscriptions.setIamPolicy

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

Si vous devez créer des abonnements pull dans un projet associés à un sujet dans un autre projet, demandez à l'administrateur du sujet de vous accorder également le rôle IAM (roles/pubsub.editor) Éditeur Pub/Sub sur le sujet.

Propriétés des abonnements pull

Lorsque vous configurez un abonnement pull, vous pouvez spécifier les propriétés suivantes.

Propriétés communes

Découvrez les propriétés d'abonnement courantes que vous pouvez définir pour tous les abonnements.

Diffusion de type "exactement une fois"

Distribution de type "exactement une fois". Si cette valeur est définie, Pub/Sub garantit une distribution de type exactement une fois. Si aucun attribut n'est spécifié, l'abonnement prend en charge la distribution au moins une fois pour chaque message.

Créer un abonnement pull

Les exemples suivants montrent comment créer un abonnement avec une distribution pull, à l'aide des paramètres par défaut fournis.

Console

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

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

    Accéder aux 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 la section Consignes de dénomination d'un sujet ou d'un abonnement.

  4. Choisissez ou créez un sujet dans le menu déroulant. L'abonnement reçoit les messages du sujet.
  5. Laissez le type de distribution sur Pull.
  6. Conservez toutes les autres valeurs par défaut.
  7. 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 Google Cloud, accédez à la page Topics (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. Saisissez l'ID de l'abonnement.

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

  5. Laissez le type de distribution sur Pull.
  6. Conservez toutes les autres valeurs par défaut.
  7. Cliquez sur Créer.

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

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 actuels de l'application, exécutez la commande suivante : 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++ du guide de démarrage rapide de Pub/Sub : utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub C++.

    Pour vous authentifier auprès de Pub/Sub, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

    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 de configuration pour C# du guide de démarrage rapide de Pub/Sub : utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub C#.

    Pour vous authentifier auprès de Pub/Sub, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

    
    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

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

    Pour vous authentifier auprès de Pub/Sub, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

    import (
    	"context"
    	"fmt"
    	"io"
    	"time"
    
    	"cloud.google.com/go/pubsub"
    )
    
    func create(w io.Writer, projectID, subID string, topic *pubsub.Topic) error {
    	// projectID := "my-project-id"
    	// subID := "my-sub"
    	// topic of type https://godoc.org/cloud.google.com/go/pubsub#Topic
    	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.CreateSubscription(ctx, subID, pubsub.SubscriptionConfig{
    		Topic:       topic,
    		AckDeadline: 20 * time.Second,
    	})
    	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 de configuration pour Java du guide de démarrage rapide de Pub/Sub : utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub Java.

    Pour vous authentifier auprès de Pub/Sub, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

    
    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

    /**
     * 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.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 de configuration pour PHP du guide de démarrage rapide de Pub/Sub : utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub PHP.

    Pour vous authentifier auprès de Pub/Sub, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

    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 de configuration pour Python du guide de démarrage rapide de Pub/Sub : utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub Python.

    Pour vous authentifier auprès de Pub/Sub, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

    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

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

    Pour vous authentifier auprès de Pub/Sub, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

    # topic_id        = "your-topic-id"
    # subscription_id = "your-subscription-id"
    
    pubsub = Google::Cloud::Pubsub.new
    
    topic        = pubsub.topic topic_id
    subscription = topic.subscribe subscription_id
    
    puts "Pull subscription #{subscription_id} created."

    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 de surveillance de Pub/Sub.

    Vous pouvez également surveiller les abonnements à partir de Pub/Sub.

    Étape suivante

    • Créez ou modifiez un abonnement à l'aide des commandes gcloud.
    • Créez ou modifiez un abonnement à l'aide des API REST.