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. Puoi eseguire l'emulatore Pub/Sub utilizzando Google Cloud CLI.

Per eseguire l'applicazione sull'emulatore, devi prima avviare l'emulatore e impostare le variabili di ambiente. La tua applicazione deve comunicare con l'emulatore anziché con il servizio Pub/Sub di produzione. Le risorse create e i messaggi pubblicati nell'emulatore vengono conservati per tutta la durata della sessione dell'emulatore.

Nota: per testare le sottoscrizioni di tipo push nell'emulatore, puoi utilizzare gli endpoint push non criptati (ossia http), come negli esempi seguenti. In produzione sono consentiti solo gli endpoint push protetti (https).

Prima di iniziare

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

Configurare un ambiente di sviluppo Python.
Installa un JDK.
Installa Google Cloud CLI.
Creare 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 Cloud.

Avvio dell'emulatore

Avvia l'emulatore richiamando pubsub start da un prompt dei comandi. Prima di eseguire il comando, sostituisci PUBSUB_PROJECT_ID con una ID progetto Google Cloud valida. La stringa non deve rappresentare un vero progetto Google Cloud 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 nell'endpoint dell'emulatore sulla tua macchina locale anziché nell'endpoint di Google Cloud. Tutte le operazioni vengono eseguite localmente, tra cui:

Creazione di un argomento o una sottoscrizione
Pubblicazione in corso…
Sottoscrizione in corso

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.

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 del comando:

$(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 ora si connetterà all'emulatore Pub/Sub.

Impostando manualmente le variabili

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

Esegui il comando env-init:
```
 gcloud beta emulators pubsub env-init
```
Sul computer che esegue la tua applicazione, imposta la variabile di ambiente e il valore PUBSUB_EMULATOR_HOST come indicato dall'output del comando env-init. Questa configurazione ti connette all'emulatore. Facoltativamente, puoi impostare la variabile di ambiente PUBSUB_PROJECT_ID per il progetto che vuoi utilizzare per l'emulatore. Ad esempio:
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 ora si connetterà all'emulatore Pub/Sub.

Nota: se utilizzi il server di sviluppo locale Python App Engine Standard, devi passare questa variabile di ambiente dalla 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.

Usare l'emulatore

Per utilizzare l'emulatore, devi avere creato un'applicazione con le librerie client Cloud. L'emulatore non supporta i comandi di Google Cloud Console o gcloud pubsub.

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

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

Scarica gli esempi Python Pub/Sub da GitHub clonando il repository Python completo.
Nel repository clonato, vai alla directory samples/snippets. Completa i passaggi rimanenti di questa directory.
Nella directory samples/snippets, installa le dipendenze necessarie per eseguire l'esempio:
```
pip install -r requirements.txt
```

Creare un argomento:

 python publisher.py PUBSUB_PROJECT_ID create TOPIC_ID

(Facoltativo) Se non hai un endpoint push locale per testare le sottoscrizioni 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 iniziale:
```
{
   "messages": []
}
```
3. Annota http://[::1]:3000/messages per PUSH_ENDPOINT nel passaggio successivo.

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

Pubblica messaggi nell'argomento:

 python publisher.py PUBSUB_PROJECT_ID publish TOPIC_ID

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 al tuo endpoint di destinazione 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, ad eccezione di Java e C#, se hai impostato PUBSUB_EMULATOR_HOST come descritto nella sezione Impostazione delle variabili di ambiente, le librerie client di Pub/Sub chiamano automaticamente l'API in esecuzione nell'istanza locale, anziché Pub/Sub.

Tuttavia, le librerie client C# e Java richiedono la modifica del codice per utilizzare l'emulatore:

C#

Prima di provare questo esempio, segui le istruzioni per la configurazione di C# nella guida rapida di Pub/Sub mediante librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento per l'API C# Pub/Sub.

Visualizza su GitHub Feedback


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 per la configurazione di Java nella guida rapida di Pub/Sub mediante librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento per l'API Java Pub/Sub.

Visualizza su GitHub Feedback

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

Per interrompere l'emulatore, premi Ctrl + C.

Dopo aver arrestato l'emulatore, esegui il comando seguente 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à di Pub/Sub:

Pubblicazione di messaggi
Ricezione di messaggi da sottoscrizioni push e pull
Ordinamento dei messaggi
Ripetizione della visione dei messaggi
Inoltro dei messaggi ad argomenti messaggi non recapitabili
Riprova i criteri sulla consegna dei messaggi
Supporto dello schema per Avro

Limitazioni note

Le RPC UpdateTopic e UpdateSnapshot non sono supportate.
Le operazioni IAM non sono supportate.
La conservazione configurabile dei messaggi non è supportata; tutti i messaggi vengono conservati per un periodo indeterminato.
La scadenza dell'abbonamento non è supportata. Gli abbonamenti non hanno scadenza.
I filtri non sono supportati.
Supporto dello schema per i buffer di protocollo.
È possibile creare sottoscrizioni BigQuery, ma non inviare messaggi a BigQuery.

Per segnalare problemi, invia una pagina pubblica di segnalazione dei problemi.

Passaggi successivi

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