Test delle applicazioni in locale con l'emulatore

Per sviluppare e testare la tua applicazione in locale, 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 nell'emulatore, avvia innanzitutto l'emulatore e imposta le variabili di ambiente. L'applicazione deve comunicare con l'emulatore anziché con il servizio di produzione Pub/Sub. Le risorse create e i messaggi pubblicati nell'emulatore vengono conservati per tutta la durata della sessione dell'emulatore.

Nota: per testare gli abbonamenti push nell'emulatore, puoi utilizzare endpoint push non criptati (ovvero http), come nei seguenti esempi. In produzione sono consentiti solo gli endpoint push sicuri (https).

Prima di iniziare

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

• Configura un ambiente di sviluppo Python.

• Installa un JDK.

• Installa Google Cloud CLI.

• Crea un'applicazione utilizzando le librerie client di Cloud.

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.

Avvio dell'emulatore

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

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

Consulta gcloud beta emulators pubsub start per un elenco completo dei flag.

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'endpoint Google Cloud. Tutte le operazioni avvengono localmente, tra cui:

• Creazione di un argomento o di una sottoscrizione
• In fase di pubblicazione
• Sottoscrizione in corso

Nota: l'emulatore rimane in ascolto sulla porta 8085 del tuo localhost IPv6 (::1) per impostazione predefinita. Puoi fare in modo che l'emulatore sia in ascolto sulla porta 8085 su tutti gli indirizzi IP sul tuo sistema impostando --host-port=0.0.0.0:8085. Se IPv6 è disabilitato sul sistema, puoi specificare IPv4 (127.0.0.1) impostando --host-port=127.0.0.1:8085.

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 da numeri di porta assegnati dinamicamente che potrebbero cambiare al riavvio dell'emulatore.

Impostazione automatica delle variabili

Se la tua 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

La tua applicazione si connetterà all'emulatore Pub/Sub.

Impostare manualmente le variabili

Se la tua 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 e il valore PUBSUB_EMULATOR_HOST come indicato dall'output del comando env-init. Questa configurazione collega la tua 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

La tua applicazione si connetterà all'emulatore Pub/Sub.

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

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.

Utilizzo dell'emulatore

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

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

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

1. Ottieni gli esempi di Python Pub/Sub da GitHub clonando il repository Python completo.

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

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

   pip install -r requirements.txt
   

4. Creare un argomento:

    python publisher.py PUBSUB_PROJECT_ID create TOPIC_ID
   

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

   1. Installa JSON Server.

      npm install -g json-server
      

   2. Avvia il server JSON.

      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
     

   • Creare una sottoscrizione push:

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

7. Pubblica 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 recapitati 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
           },
           ...
       ]
     }
     

Accesso alle variabili di ambiente

In tutti i linguaggi tranne Java e C#, se hai impostato PUBSUB_EMULATOR_HOST come descritto in Impostazione delle 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 sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API C# di Pub/Sub.

Per eseguire l'autenticazione in Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare 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 sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Java di Pub/Sub.

Per eseguire l'autenticazione in Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

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();
}

Arresto dell'emulatore in corso...

Per interrompere l'emulatore, premi Ctrl+C.

Dopo aver arrestato l'emulatore, esegui questo comando per rimuovere la variabile di ambiente PUBSUB_EMULATOR_HOST in modo che la tua 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, vedi gcloud beta emulators pubsub.

Funzionalità supportate

L'emulatore supporta le seguenti funzionalità di 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
• Criterio di nuovo tentativo alla consegna dei messaggi
• Supporto di schemi per Avro

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 per un tempo indeterminato.
• La scadenza dell'abbonamento non è supportata. Gli abbonamenti non hanno scadenza.
• I filtri non sono supportati.
• Supporto degli schemi per i buffer di protocollo.
• Le sottoscrizioni BigQuery possono essere create, ma non inviano messaggi a BigQuery.
• La ricerca di un timestamp per gli abbonamenti ordinati non è supportata.

Per segnalare eventuali problemi, invia uno Issue Tracker pubblico.

Passaggi successivi

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