Test delle applicazioni in locale con l'emulatore

Per sviluppare e testare l'applicazione localmente, puoi utilizzare l'emulatore Pub/Sub, che fornisce l'emulazione locale del servizio Pub/Sub di produzione. Esegui l'emulatore Pub/Sub utilizzando Google Cloud CLI.

Per eseguire l'applicazione rispetto all'emulatore, avvia prima l'emulatore e imposta le variabili di ambiente. L'applicazione deve comunicare con l'emulatore anziché con il servizio Pub/Sub di produzione. Le risorse create e i messaggi pubblicati nell'emulatore vengono mantenuti per la durata della sessione dell'emulatore.

Prima di iniziare

Completa i seguenti prerequisiti prima di utilizzare l'emulatore Pub/Sub:

Installa l'emulatore

Installa l'emulatore da un prompt dei comandi:

gcloud components install pubsub-emulator
gcloud components update

Installa l'emulatore come immagine container

Per installare ed eseguire l'emulatore come container, scarica e installa l' immagine Docker gCloud.

Avvia l'emulatore

Avvia l'emulatore richiamando pubsub start da un prompt dei comandi. Prima di eseguire il comando, sostituisci PUBSUB_PROJECT_ID con una stringa ID progetto valida. Google Cloud La stringa non deve rappresentare un progetto Google Cloud reale perché l'emulatore Pub/Sub viene eseguito localmente.

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

Per un elenco completo dei flag, consulta gcloud beta emulators pubsub start.

Dopo aver avviato l'emulatore, viene visualizzato un messaggio simile al seguente:

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

Questo messaggio indica che il server Pub/Sub viene eseguito sull'endpoint dell'emulatore sulla tua macchina locale anziché sull' Google Cloud endpoint. Tutte le operazioni vengono eseguite localmente, tra cui:

  • Creazione di un argomento o di una sottoscrizione
  • Pubblicazione
  • Sottoscrizione

Imposta le variabili di ambiente

Dopo aver avviato l'emulatore, devi impostare le variabili di ambiente in modo che l'applicazione si connetta all'emulatore anziché a Pub/Sub. Imposta queste variabili di ambiente sulla stessa macchina che utilizzi per eseguire l'applicazione.

Devi impostare le variabili di ambiente ogni volta che avvii l'emulatore. Le variabili di ambiente dipendono dai numeri di porta assegnati dinamicamente che potrebbero cambiare quando riavvii l'emulatore.

Imposta automaticamente le variabili

Se l'applicazione e l'emulatore vengono eseguiti sulla stessa macchina, puoi impostare automaticamente le variabili di ambiente:

Linux / macOS

Esegui env-init utilizzando la sostituzione dei comandi:

$(gcloud beta emulators pubsub env-init)

Windows

Crea ed esegui un file batch utilizzando l'output di env-init:

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

L'applicazione si connetterà all'emulatore Pub/Sub.

Imposta manualmente le variabili

Se l'applicazione e l'emulatore vengono eseguiti su macchine diverse, imposta manualmente le variabili di ambiente:

  1. Esegui il comando env-init:

     gcloud beta emulators pubsub env-init

  2. Sulla macchina che esegue l'applicazione, imposta la variabile di ambiente PUBSUB_EMULATOR_HOST e il relativo valore come indicato dall'output del comando env-init. Questa configurazione connette l'applicazione all'emulatore. Facoltativamente, puoi impostare la variabile di ambiente PUBSUB_PROJECT_ID per il progetto che vuoi utilizzare per l'emulatore.

    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

L'applicazione si connetterà all'emulatore Pub/Sub.

Nota: se utilizzi il server di sviluppo locale di App Engine standard Python, devi passare questa variabile di ambiente nella riga di comando come segue:

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

dev_appserver.py è incluso in [PATH_TO_CLOUD_SDK]/google-cloud-sdk/bin/dev_appserver.py.

Utilizza l'emulatore

Per utilizzare l'emulatore, devi avere un'applicazione creata utilizzando le librerie client di Cloud. L'emulatore non supporta i comandi della console o gcloud pubsub . Google Cloud

L'esempio seguente mostra l'utilizzo dell'emulatore e di un'applicazione che utilizza la libreria client di Cloud Python per eseguire varie operazioni. Questi esempi includono la creazione di un argomento, la pubblicazione di messaggi e la lettura di messaggi.

Completa i seguenti passaggi sulla macchina in cui hai impostato le variabili di ambiente dell'emulatore:

  1. Recupera gli esempi Python di Pub/Sub da GitHub clonando l'intero repository Python.

  2. Nel repository clonato, vai alla directory samples/snippets. Completa il resto di questi passaggi in questa directory.

  3. Dalla directory samples/snippets, installa le dipendenze necessarie per eseguire l'esempio:

    pip install -r requirements.txt

  4. Crea un argomento:

     python publisher.py PUBSUB_PROJECT_ID create TOPIC_ID

  5. (Facoltativo) Se non hai un endpoint push locale per testare le sottoscrizioni push nell'emulatore, completa i seguenti passaggi per crearne uno su http://[::1]:3000/messages.

    1. Installa JSON Server. 
      npm install -g json-server
    2. Avvia JSON Server. 
      json-server --port 3000 --watch db.json
      dove db.json contiene il seguente codice di avvio: 
      {
   "messages": []
}
    3. Prendi nota di http://[::1]:3000/messages per PUSH_ENDPOINT nel passaggio successivo.

  6. Crea una sottoscrizione all'argomento:

    • Crea una sottoscrizione pull:

      python subscriber.py PUBSUB_PROJECT_ID create TOPIC_ID SUBSCRIPTION_ID

    • Crea una sottoscrizione push:

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

  7. Pubblica i messaggi nell'argomento:

     python publisher.py PUBSUB_PROJECT_ID publish TOPIC_ID

  8. Leggi i messaggi pubblicati nell'argomento:

    • Recupera i messaggi dalla sottoscrizione pull:

      python subscriber.py PUBSUB_PROJECT_ID receive SUBSCRIPTION_ID

    • Osserva i messaggi inviati all'endpoint push locale. Ad esempio, i messaggi hanno il seguente aspetto:

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

Accedi alle variabili di ambiente

In tutte le lingue, ad eccezione di Java e C#, se hai impostato PUBSUB_EMULATOR_HOST come descritto in Imposta le variabili di ambiente, le librerie client Pub/Sub chiamano automaticamente l'API in esecuzione nell' istanza locale anziché Pub/Sub.

Tuttavia, le librerie client C# e Java richiedono di modificare il codice per utilizzare l'emulatore:

C#

Prima di provare questo esempio, segui le istruzioni di configurazione di C# nella guida rapida di Pub/Sub per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API C# Pub/Sub.

Per eseguire l'autenticazione in Pub/Sub, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 


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

Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di Pub/Sub per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'Java API Pub/Sub.

Per eseguire l'autenticazione in Pub/Sub, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 


import com.google.api.core.ApiFuture;
import com.google.api.gax.core.CredentialsProvider;
import com.google.api.gax.core.NoCredentialsProvider;
import com.google.api.gax.grpc.GrpcTransportChannel;
import com.google.api.gax.rpc.FixedTransportChannelProvider;
import com.google.api.gax.rpc.TransportChannelProvider;
import com.google.cloud.pubsub.v1.Publisher;
import com.google.cloud.pubsub.v1.TopicAdminClient;
import com.google.cloud.pubsub.v1.TopicAdminSettings;
import com.google.protobuf.ByteString;
import com.google.pubsub.v1.PubsubMessage;
import com.google.pubsub.v1.Topic;
import com.google.pubsub.v1.TopicName;
import io.grpc.ManagedChannel;
import io.grpc.ManagedChannelBuilder;

public class UsePubSubEmulatorExample {
  public static void main(String... args) throws Exception {
    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`.
      // Can be done similarly for a `SubscriptionAdminClient`.
      TopicAdminClient topicAdminClient =
          TopicAdminClient.create(
              TopicAdminSettings.newBuilder()
                  .setTransportChannelProvider(channelProvider)
                  .setCredentialsProvider(credentialsProvider)
                  .build());

      TopicName topicName = TopicName.of("my-project-id", "my-topic-id");
      Topic topic = topicAdminClient.createTopic(topicName);
      System.out.println("Created topic: " + topic.getName());

      // Set the channel and credentials provider when creating a `Publisher`.
      // Can be done similarly for a `Subscriber`.
      Publisher publisher =
          Publisher.newBuilder(topicName)
              .setChannelProvider(channelProvider)
              .setCredentialsProvider(credentialsProvider)
              .build();

      String message = "Hello World!";
      ByteString data = ByteString.copyFromUtf8(message);
      PubsubMessage pubsubMessage = PubsubMessage.newBuilder().setData(data).build();

      ApiFuture<String> messageIdFuture = publisher.publish(pubsubMessage);
      String messageId = messageIdFuture.get();
      System.out.println("Published message ID: " + messageId);
    } finally {
      channel.shutdown();
    }
  }
}

Arresta l'emulatore

Per arrestare l'emulatore, premi Control+C.

Dopo aver arrestato l'emulatore, esegui il seguente comando per rimuovere la variabile di ambiente PUBSUB_EMULATOR_HOST in modo che l'applicazione si connetta a Pub/Sub:

Linux / macOS
unset PUBSUB_EMULATOR_HOST
Windows
set PUBSUB_EMULATOR_HOST=

Argomenti della riga di comando dell'emulatore

Per maggiori dettagli sugli argomenti della riga di comando per l'emulatore Pub/Sub, consulta gcloud beta emulators pubsub.

Funzionalità supportate

L'emulatore supporta le seguenti funzionalità Pub/Sub:

  • Pubblicazione di messaggi
  • Ricezione di messaggi da sottoscrizioni push e pull
  • Ordinamento dei messaggi
  • Ripetizione della visione dei messaggi
  • Inoltro di messaggi ad argomenti messaggi non recapitabili
  • Criteri di nuovi tentativi per la consegna dei messaggi
  • Supporto dello schema per Avro
  • Filtri

Limitazioni note

  • Le RPC UpdateTopic e UpdateSnapshot non sono supportate.
  • Le operazioni IAM non sono supportate.
  • La conservazione dei messaggi configurabile non è supportata; tutti i messaggi vengono conservati a tempo indeterminato.
  • La scadenza della sottoscrizione non è supportata. Le sottoscrizioni non scadono.
  • Supporto dello schema per i buffer di protocollo.
  • È possibile creare sottoscrizioni BigQuery, ma non inviano messaggi a BigQuery.
  • La ricerca di un timestamp per le sottoscrizioni ordinate non è supportata.
  • È possibile creare argomenti e sottoscrizioni con SMT (Single Message Transforms), ma i messaggi non verranno trasformati.

Per segnalare problemi, invia un issue tracker pubblico.

Passaggi successivi

  • Per scoprire come utilizzare l'emulatore Pub/Sub con minikube, consulta questo post del blog.