Testing apps locally with the emulator

To develop and test your application locally, you can use the Cloud Pub/Sub emulator, which provides local emulation of the production Cloud Pub/Sub environment. You run the Cloud Pub/Sub emulator using the gcloud command-line tool.

To run your application against the emulator, you need to do some configuration first, such as starting the emulator and setting environment variables.

Prerequisites

You must have the following to use the Cloud Pub/Sub emulator:

Installing the emulator

Install the emulator from a command prompt:

gcloud components install pubsub-emulator
gcloud components update

Starting the emulator

Start the emulator by invoking pubsub start from a command prompt:

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

where --project supplies the project ID to the emulator, and [options] can take other command-line arguments. See gcloud beta emulators pubsub start for a complete list of options.

After you start the emulator, you should see a message that resembles the following:

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

This indicates that the Pub/Sub server is now run at the emulator endpoint on your local machine instead of the real endpoint in the cloud. Operations such as creating a topic or subscription, publishing, and subscribing will all happen locally.

Setting environment variables

After you start the emulator, you need to set environment variables so that your application connects to the emulator instead of Cloud Pub/Sub. Set these environment variables on the same machine that you use to run your application.

You need to set the environment variables each time you start the emulator. The environment variables depend on dynamically assigned port numbers that could change when you restart the emulator.

Automatically setting the variables

If your application and the emulator run on the same machine, you can set the environment variables automatically:

Linux / macOS

Run env-init using command substitution:

$(gcloud beta emulators pubsub env-init)

Windows

Create and run a batch file using output from env-init:

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

Your application will now connect to the Cloud Pub/Sub emulator.

Manually setting the variables

If your application and the emulator run on different machines, set the environment variables manually:

  1. Run the env-init command:

     gcloud beta emulators pubsub env-init

  2. On the machine that runs your application, set the PUBSUB_EMULATOR_HOST environment variable and value as directed by the output of the env-init command. You can optionally set the PUBSUB_PROJECT_ID environment variable for the project you want to use for the emulator, but you only need to set PUBSUB_EMULATOR_HOST for your application to connect to the emulator. For example:

    Linux / macOS
    export PUBSUB_EMULATOR_HOST=localhost:8432
    export PUBSUB_PROJECT_ID=my-project-id
    Windows
    set PUBSUB_EMULATOR_HOST=localhost:8432
    set PUBSUB_PROJECT_ID=my-project-id

Your application will now connect to the Cloud Pub/Sub emulator.

Note: If you are using the Python App Engine Standard local development server, you must pass environment variables on the command line as follows:

Python

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

Using the emulator

To use the emulator, you must have an application built using the Google Cloud Client Libraries. The emulator does not support GCP Console or gcloud pubsub commands.

The following example demonstrates how to create a topic, publish messages, and read messages using the emulator and an application that uses the Python Google Cloud Client Library.

Complete the following steps on the machine where you set the emulator environment variables:

  1. Get the Cloud Pub/Sub Python samples from GitHub by cloning the full Python repository. The Cloud Pub/Sub samples are in the pubsub directory.

  2. In your cloned repository, navigate to the pubsub/cloud-client directory. You'll complete the rest of these steps in this directory.

  3. From within the pubsub/cloud-client directory, install the dependencies needed to run the example:

    pip install -r requirements.txt
    
  4. Create a topic:

    python publisher.py PUBSUB_PROJECT_ID create TOPIC_ID
    
  5. Create a subscription to the topic:

    • Create a pull subscription:
    python subscriber.py PUBSUB_PROJECT_ID create TOPIC_ID SUBSCRIPTION_ID
    
  6. Publish messages to the topic:

    python publisher.py PUBSUB_PROJECT_ID publish TOPIC_ID
    
  7. Read the messages published to the topic:

    python subscriber.py PUBSUB_PROJECT_ID receive SUBSCRIPTION_ID
    

Accessing environment variables

In all languages except for Java and C#, if you have set PUBSUB_EMULATOR_HOST as described in Setting environment variables, the Cloud Pub/Sub client libraries automatically call the API running in the local instance rather than Cloud Pub/Sub.

However, C# and Java client libraries require you to modify your code to use the emulator:

C#

Before trying this sample, follow the C# setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub C# API reference documentation .

// Copyright 2017 Google Inc. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

using Google.Apis.Logging;
using Google.Cloud.PubSub.V1;
using Google.Cloud.Translation.V2;
using static Google.Apis.Http.ConfigurableMessageHandler;
using Grpc.Core;
using System;
using Google.Api.Gax.ResourceNames;
using Google.Cloud.Vision.V1;
using System.Collections.Generic;
using Google.Cloud.Scheduler.V1;

namespace Google.Cloud.Tools.Snippets
{
    public class FaqSnippets
    {
        public void Emulator()
        {
            // Sample: Emulator
            // For example, "localhost:8615"
            string emulatorHostAndPort = Environment.GetEnvironmentVariable("PUBSUB_EMULATOR_HOST");

            Channel channel = new Channel(emulatorHostAndPort, ChannelCredentials.Insecure);
            PublisherServiceApiClient client = PublisherServiceApiClient.Create(channel);
            client.CreateTopic(new TopicName("project", "topic"));
            foreach (var topic in client.ListTopics(new ProjectName("project")))
            {
                Console.WriteLine(topic.Name);
            }
            // End sample
        }

        public void RestLogging()
        {
            // Sample: RestLogging
            // Required using directives:
            // using static Google.Apis.Http.ConfigurableMessageHandler;
            // using Google.Apis.Logging;
            // using Google.Cloud.Translation.V2;

            // Register a verbose console logger
            ApplicationContext.RegisterLogger(new ConsoleLogger(LogLevel.All));

            // Create a translation client
            TranslationClient client = TranslationClient.Create();

            // Configure which events the message handler will log.
            client.Service.HttpClient.MessageHandler.LogEvents =
                LogEventType.RequestHeaders | LogEventType.ResponseBody;

            // Make the request
            client.ListLanguages();
            // End sample
        }

        public void ProtoRepeatedField1()
        {
            // Sample: ProtoRepeatedField1
            // In normal code you'd populate these individual requests with more
            // information.
            AnnotateImageRequest request1 = new AnnotateImageRequest();
            AnnotateImageRequest request2 = new AnnotateImageRequest();

            // Create the batch request using an object initializer
            BatchAnnotateImagesRequest batch = new BatchAnnotateImagesRequest
            {
                // Populate the repeated field with a collection initializer
                Requests = { request1, request2 }
            };
            // End sample
        }

        public void ProtoRepeatedField2()
        {
            // Sample: ProtoRepeatedField2
            // In normal code you'd populate these individual requests with more
            // information.
            AnnotateImageRequest request1 = new AnnotateImageRequest();
            AnnotateImageRequest request2 = new AnnotateImageRequest();

            // Populate the batch without using an object initializer, just by calling
            // Add on the repeated field
            BatchAnnotateImagesRequest batch = new BatchAnnotateImagesRequest();
            batch.Requests.Add(request1);
            batch.Requests.Add(request2);
            // End sample
        }

        public void ProtoRepeatedField3()
        {
            // Sample: ProtoRepeatedField3
            // In normal code you'd populate these individual requests with more
            // information.
            List<AnnotateImageRequest> requests = new List<AnnotateImageRequest>
            {
                new AnnotateImageRequest(),
                new AnnotateImageRequest()
            };

            // Create the batch request using an object initializer
            BatchAnnotateImagesRequest batch = new BatchAnnotateImagesRequest
            {
                // Populate the repeated field using the Add overload that accepts
                // an IEnumerable<T>
                Requests = { requests }
            };
            // End sample
        }

        public void ProtoMap1()
        {
            // Sample: ProtoMap1
            HttpTarget target = new HttpTarget
            {
                Headers =
                {
                    {  "X-Custom-Header1", "Value1" },
                    {  "X-Custom-Header2", "Value2" },
                }
            };
            // End sample
        }

        public void ProtoMap2()
        {
            // Sample: ProtoMap2
            HttpTarget target = new HttpTarget
            {
                Headers =
                {
                    ["X-Custom-Header1"] = "Value1",
                    ["X-Custom-Header2"] = "Value2",
                }
            };
            // End sample
        }

        public void ProtoMap3()
        {
            // Sample: ProtoMap3
            HttpTarget target = new HttpTarget();
            target.Headers["X-Custom-Header1"] = "Value1";
            target.Headers["X-Custom-Header2"] = "Value2";
            // End sample
        }
    }
}

Java

Before trying this sample, follow the Java setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Java API reference documentation .

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

  ProjectTopicName topicName = ProjectTopicName.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();
}

Stopping the emulator

To stop the emulator, press Control+C.

After you stop the emulator, run the following command to remove the PUBSUB_EMULATOR_HOST environment variable so your application will connect to Cloud Pub/Sub:

Linux / macOS
unset PUBSUB_EMULATOR_HOST
Windows
set PUBSUB_EMULATOR_HOST=

Emulator command-line arguments

For details on command-line arguments for the Cloud Pub/Sub emulator, see gcloud beta emulators pubsub.

Known limitations

  • Push subscriptions are not currently supported by the emulator.
  • IAM operations are not currently supported.

To file issues, visit the Cloud Pub/Sub forum.

هل كانت هذه الصفحة مفيدة؟ يرجى تقييم أدائنا:

إرسال تعليقات حول...

Cloud Pub/Sub Documentation