Tester des applications localement avec l'émulateur

Pour développer et tester votre application localement, vous pouvez utiliser l'émulateur Pub/Sub, qui fournit une émulation locale du service de production Pub/Sub. Vous exécutez l'émulateur Pub/Sub à l'aide de la Google Cloud CLI.

Pour exécuter votre application sur l'émulateur, commencez par le démarrer et définissez les variables d'environnement. Votre application doit communiquer avec l'émulateur au lieu du service Pub/Sub de production. Les ressources créées et les messages publiés dans l'émulateur sont conservés pendant toute la durée de vie de la session de l'émulateur.

Remarque:Pour tester les abonnements push dans l'émulateur, vous pouvez utiliser des points de terminaison push non chiffrés (c'est-à-dire http), comme dans les exemples suivants. En production, seuls les points de terminaison push sécurisés (https) sont autorisés.

Avant de commencer

Remplissez les conditions préalables suivantes avant d'utiliser l'émulateur Pub/Sub:

• Configurez un environnement de développement Python.

• Installez un JDK.

• Installez la Google Cloud CLI.

• Créer une application à l'aide des bibliothèques clientes Cloud

Installer l'émulateur

Installez l'émulateur depuis une invite de commande :

gcloud components install pubsub-emulator
gcloud components update

Installer l'émulateur en tant qu'image de conteneur

Pour installer et exécuter l'émulateur en tant que conteneur, téléchargez et installez l'image Docker gcloud.

Démarrer l'émulateur

Pour démarrer l'émulateur, exécutez la commande pubsub start à partir d'une invite de commande : Avant d'exécuter la commande, remplacez PUBSUB_PROJECT_ID par une chaîne correspondant à un ID de projet Google Cloud valide. La chaîne n'a pas besoin de représenter un vrai projet Google Cloud, car l'émulateur Pub/Sub s'exécute localement.

gcloud beta emulators pubsub start --project=PUBSUB_PROJECT_ID [options]

Pour obtenir la liste complète des options, consultez la page gcloud beta emulators pubsub start.

Une fois l'émulateur démarré, un message semblable à celui-ci s'affiche:

...
[pubsub] This is the Pub/Sub fake.
[pubsub] Implementation may be incomplete or differ from the real system.
...
[pubsub] INFO: Server started, listening on 8085

Ce message indique que le serveur Pub/Sub s'exécute au niveau du point de terminaison de l'émulateur sur votre ordinateur local et non sur le point de terminaison Google Cloud. Toutes les opérations sont effectuées localement, y compris les suivantes:

• Créer un sujet ou un abonnement
• Publication…
• Abonnement

Remarque:L'émulateur écoute par défaut sur le port 8085 de votre hôte local IPv6 (::1). Vous pouvez demander à l'émulateur d'écouter sur le port 8085 sur toutes les adresses IP de votre système en définissant --host-port=0.0.0.0:8085. Si IPv6 est désactivé sur votre système, vous pouvez spécifier IPv4 (127.0.0.1) en définissant --host-port=127.0.0.1:8085.

Définir des variables d'environnement

Après avoir démarré l'émulateur, vous devez définir les variables d'environnement afin que votre application se connecte à l'émulateur au lieu de Pub/Sub. Définissez ces variables d'environnement sur la même machine que celle utilisée pour exécuter votre application.

Vous devez définir les variables d'environnement chaque fois que vous démarrez l'émulateur. Elles dépendent des numéros de port attribués de manière dynamique, qui sont susceptibles d'être modifiés lorsque vous redémarrez l'émulateur.

Définir les variables automatiquement

Si votre application et l'émulateur s'exécutent sur la même machine, vous pouvez définir les variables d'environnement automatiquement comme suit :

Linux/macOS

Exécutez env-init à l'aide de la substitution de commande :

$(gcloud beta emulators pubsub env-init)

Windows

Créez et exécutez un fichier batch à l'aide du résultat de la commande env-init :

gcloud beta emulators pubsub env-init > set_vars.cmd && set_vars.cmd

Votre application se connecte alors à l'émulateur Pub/Sub.

Définir les variables manuellement

Si votre application et l'émulateur s'exécutent sur des machines différentes, définissez les variables d'environnement manuellement :

1. Exécutez la commande env-init :

    gcloud beta emulators pubsub env-init

2. Sur la machine qui exécute votre application, définissez la variable d'environnement PUBSUB_EMULATOR_HOST ainsi que sa valeur, comme indiqué par le résultat de la commande env-init. Cette configuration connecte votre application à l'émulateur. Vous pouvez éventuellement définir la variable d'environnement PUBSUB_PROJECT_ID pour le projet que vous souhaitez utiliser pour l'émulateur. Exemple :

   Linux/macOS

   export PUBSUB_EMULATOR_HOST=[::1]:8432
   export PUBSUB_PROJECT_ID=my-project-id

   Windows

   set PUBSUB_EMULATOR_HOST=[::1]:8432
   set PUBSUB_PROJECT_ID=my-project-id

Votre application se connecte alors à l'émulateur Pub/Sub.

Remarque:Si vous utilisez le serveur de développement local de l'environnement standard App Engine pour Python, vous devez transmettre cette variable d'environnement dans la ligne de commande comme suit:

dev_appserver.py app.yaml --env_var PUBSUB_EMULATOR_HOST=${PUBSUB_EMULATOR_HOST}

dev_appserver.py est inclus dans votre [PATH_TO_CLOUD_SDK]/google-cloud-sdk/bin/dev_appserver.py.

Utiliser l'émulateur

Pour utiliser l'émulateur, vous devez disposer d'une application créée à l'aide des bibliothèques clientes Cloud. L'émulateur n'est pas compatible avec la console Google Cloud ni avec les commandes gcloud pubsub.

L'exemple suivant montre comment utiliser l'émulateur et une application qui effectue diverses opérations à l'aide de la bibliothèque cliente Cloud Python. Ces opérations incluent, par exemple, la création d'un sujet, la publication de messages et la lecture de messages.

Suivez les étapes ci-dessous sur la machine sur laquelle vous avez défini les variables d'environnement de l'émulateur :

1. Récupérez les fichiers d'exemple Python pour Pub/Sub depuis GitHub en clonant l'intégralité du dépôt Python.

2. Dans votre dépôt cloné, accédez au répertoire samples/snippets. Vous allez effectuer le reste de ces étapes dans ce répertoire.

3. À partir du répertoire samples/snippets, installez les dépendances dont vous avez besoin pour exécuter l'exemple:

   pip install -r requirements.txt
   

4. Créez un sujet :

    python publisher.py PUBSUB_PROJECT_ID create TOPIC_ID
   

5. (Facultatif) Si vous ne disposez pas d'un point de terminaison push local permettant de tester les abonnements push dans l'émulateur, procédez comme suit pour en créer un sur http://[::1]:3000/messages.

   1. Installez le serveur JSON.

      npm install -g json-server
      

   2. Démarrez le serveur JSON.

      json-server --port 3000 --watch db.json
      

      où db.json contient le code de démarrage suivant:

      {
         "messages": []
      }
      

   3. Notez http://[::1]:3000/messages pour PUSH_ENDPOINT lors de l'étape suivante.

6. Créez un abonnement associé au sujet :

   • Créez un abonnement pull :

     python subscriber.py PUBSUB_PROJECT_ID create TOPIC_ID SUBSCRIPTION_ID
     

   • Créez un abonnement push :

     python subscriber.py PUBSUB_PROJECT_ID create-push TOPIC_ID SUBSCRIPTION_ID \
     PUSH_ENDPOINT
     

7. Publiez des messages sur le sujet :

    python publisher.py PUBSUB_PROJECT_ID publish TOPIC_ID
   

8. Consultez les messages publiés sur le sujet :

   • Récupérez les messages de votre abonnement pull :

     python subscriber.py PUBSUB_PROJECT_ID receive SUBSCRIPTION_ID
     

   • Observez les messages envoyés à votre point de terminaison push local. Par exemple, les messages se présentent sous la forme suivante :

     {
       "messages": [
           {
               "subscription": "projects/PUBSUB_PROJECT_ID/subscriptions/SUBSCRIPTION_ID",
               "message": {
                   "data": "TWVzc2FnZSBudW1iZXIgMQ==",
                   "messageId": "10",
                   "attributes": {}
               },
               "id": 1
           },
           ...
       ]
     }
     

Accéder aux variables d'environnement

Dans tous les langages, à l'exception de Java et C#, les bibliothèques clientes Pub/Sub appellent automatiquement l'API s'exécutant dans l'instance locale plutôt que Pub/Sub, si vous avez défini PUBSUB_EMULATOR_HOST tel que décrit dans la section Définir des variables d'environnement.

Toutefois, afin d'utiliser l'émulateur, vous devez modifier votre code pour les bibliothèques clientes pour C# et Java :

C#

Avant d'essayer cet exemple, suivez les instructions de configuration de C# décrites dans le guide de démarrage rapide de Pub/Sub à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de 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 Configurer l'authentification pour un environnement de développement local.

using Google.Api.Gax;
using Google.Cloud.PubSub.V1;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

public class EmulatorSupportSample
{
    public async Task WithEmulatorAsync(string projectId, string topicId, string subscriptionId)
    {
        // Use EmulatorDetection.EmulatorOrProduction to create service clients that will
        // that will connect to the PubSub emulator if the PUBSUB_EMULATOR_HOST environment
        // variable is set, but will otherwise connect to the production environment.

        // Create the PublisherServiceApiClient using the PublisherServiceApiClientBuilder
        // and setting the EmulatorDection property.
        PublisherServiceApiClient publisherService = await new PublisherServiceApiClientBuilder
        {
            EmulatorDetection = EmulatorDetection.EmulatorOrProduction
        }.BuildAsync();

        // Use the client as you'd normally do, to create a topic in this example.
        TopicName topicName = new TopicName(projectId, topicId);
        publisherService.CreateTopic(topicName);

        // Create the SubscriberServiceApiClient using the SubscriberServiceApiClientBuilder
        // and setting the EmulatorDection property.
        SubscriberServiceApiClient subscriberService = await new SubscriberServiceApiClientBuilder
        {
            EmulatorDetection = EmulatorDetection.EmulatorOrProduction
        }.BuildAsync();

        // Use the client as you'd normally do, to create a subscription in this example.
        SubscriptionName subscriptionName = new SubscriptionName(projectId, subscriptionId);
        subscriberService.CreateSubscription(subscriptionName, topicName, pushConfig: null, ackDeadlineSeconds: 60);

        // Create the PublisherClient using PublisherClientBuilder to set the EmulatorDetection property.
        PublisherClient publisher = await new PublisherClientBuilder
        {
            TopicName = topicName,
            EmulatorDetection = EmulatorDetection.EmulatorOrProduction
        }.BuildAsync();
        // Use the client as you'd normally do, to send a message in this example.
        await publisher.PublishAsync("Hello, Pubsub");
        await publisher.ShutdownAsync(TimeSpan.FromSeconds(15));

        // Create the SubscriberClient using SubscriberClientBuild to set the EmulatorDetection property.
        SubscriberClient subscriber = await new SubscriberClientBuilder
        {
            SubscriptionName = subscriptionName,
            EmulatorDetection = EmulatorDetection.EmulatorOrProduction
        }.BuildAsync();
        List<PubsubMessage> receivedMessages = new List<PubsubMessage>();

        // Use the client as you'd normally do, to listen for messages in this example.
        await subscriber.StartAsync((msg, cancellationToken) =>
        {
            receivedMessages.Add(msg);
            Console.WriteLine($"Received message {msg.MessageId} published at {msg.PublishTime.ToDateTime()}");
            Console.WriteLine($"Text: '{msg.Data.ToStringUtf8()}'");
            // In this example we stop the subscriber when the message is received.
            // You may leave the subscriber running, and it will continue to received published messages
            // if any.
            // This is non-blocking, and the returned Task may be awaited.
            subscriber.StopAsync(TimeSpan.FromSeconds(15));
            // Return Reply.Ack to indicate this message has been handled.
            return Task.FromResult(SubscriberClient.Reply.Ack);
        });
    }
}

Java

Avant d'essayer cet exemple, suivez les instructions de configuration de Java décrites dans le guide de démarrage rapide de Pub/Sub à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de 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 Configurer l'authentification pour un environnement de développement local.

String hostport = System.getenv("PUBSUB_EMULATOR_HOST");
ManagedChannel channel = ManagedChannelBuilder.forTarget(hostport).usePlaintext().build();
try {
  TransportChannelProvider channelProvider =
      FixedTransportChannelProvider.create(GrpcTransportChannel.create(channel));
  CredentialsProvider credentialsProvider = NoCredentialsProvider.create();

  // Set the channel and credentials provider when creating a `TopicAdminClient`.
  // Similarly for SubscriptionAdminClient
  TopicAdminClient topicClient =
      TopicAdminClient.create(
          TopicAdminSettings.newBuilder()
              .setTransportChannelProvider(channelProvider)
              .setCredentialsProvider(credentialsProvider)
              .build());

  TopicName topicName = TopicName.of("my-project-id", "my-topic-id");
  // Set the channel and credentials provider when creating a `Publisher`.
  // Similarly for Subscriber
  Publisher publisher =
      Publisher.newBuilder(topicName)
          .setChannelProvider(channelProvider)
          .setCredentialsProvider(credentialsProvider)
          .build();
} finally {
  channel.shutdown();
}

Arrêter l'émulateur

Pour arrêter l'émulateur, appuyez sur les touches Ctrl+C.

Une fois l'émulateur arrêté, exécutez la commande suivante pour supprimer la variable d'environnement PUBSUB_EMULATOR_HOST, afin que votre application se connecte à Pub/Sub :

Linux/macOS

unset PUBSUB_EMULATOR_HOST

Windows

set PUBSUB_EMULATOR_HOST=

Arguments de ligne de commande de l'émulateur

Pour en savoir plus sur les arguments de ligne de commande de l'émulateur Pub/Sub, consultez la page gcloud beta emulators pubsub.

Fonctionnalités compatibles

L'émulateur est compatible avec les fonctionnalités Pub/Sub suivantes :

• Publier des messages
• Recevoir des messages provenant d'abonnements push et pull
• Trier des messages
• Rouvrir des messages
• Transférer des messages vers des files d'attente de lettres mortes
• Stratégies de nouvelle tentative pour la distribution des messages
• Compatibilité des schémas pour Avro

Limitations connues

• Les RPC UpdateTopic et UpdateSnapshot ne sont pas acceptés.
• Les opérations IAM ne sont pas compatibles.
• La conservation configurable des messages n'est pas compatible. Tous les messages sont conservés indéfiniment.
• Il n'est pas possible de définir une date d'expiration pour l'abonnement. Les abonnements n'expirent pas.
• Le filtrage n'est pas compatible.
• Schéma compatible pour les tampons de protocole.
• Vous pouvez créer des abonnements BigQuery, mais n'envoyez pas de messages à BigQuery.
• La recherche d'un horodatage pour les abonnements commandés n'est pas acceptée.

Pour signaler des problèmes, utilisez l'outil public de suivi des problèmes.

Étapes suivantes

• Pour savoir comment utiliser l'émulateur Pub/Sub avec minikube, consultez cet article de blog.