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. L'exécution de l'émulateur Pub/Sub s'effectue à l'aide de Google Cloud CLI.

Pour exécuter votre application sur l'émulateur, vous devez d'abord démarrer l'émulateur et définir les variables d'environnement. Votre application doit communiquer avec l'émulateur, et non avec le service de production Pub/Sub. 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.

Avant de commencer

Avant d'utiliser l'émulateur Pub/Sub, vous devez remplir les conditions préalables suivantes :

• Configurer un environnement de développement Python.

• Installer un JDK.

• Installer 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 d'ID de projet valide Google Cloud project ID. La chaîne n'a pas besoin de représenter un projet réel 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 Google Cloud point de terminaison. Toutes les opérations se déroulent localement, y compris les suivantes :

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

Définir des variables d'environnement

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

Les variables d'environnement doivent être définies 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 :

$(gcloud beta emulators pubsub 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 également définir la variable d'environnement PUBSUB_PROJECT_ID pour le projet que vous souhaitez utiliser pour l'émulateur.

   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 Python App Engine Standard, vous devez transmettre cette variable d'environnement sur 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 les commandes de la console ou Google Cloud gcloud pubsub.

L'exemple suivant montre comment utiliser l'émulateur et une application qui utilise la bibliothèque cliente Cloud Python pour effectuer diverses opérations. Par exemple, il explique comment créer un sujet, publier des messages et consulter des 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 effectuerez le reste de ces étapes dans ce répertoire.

3. Depuis le répertoire samples/snippets, installez les dépendances nécessaires à l'exécution de 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 pour tester les abonnements push dans l'émulateur, procédez comme suit pour en créer un à l'adresse 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 :

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 =