Como testar aplicativos localmente com o emulador

Para desenvolver e testar seu aplicativo localmente, você pode usar o emulador do Pub/Sub, que fornece emulação local do ambiente de produção do Pub/Sub. Você executa o emulador do Pub/Sub usando a ferramenta de linha de comando gcloud.

Para executar seu aplicativo no emulador, primeiro você precisa iniciar o emulador e definir variáveis de ambiente para que seu aplicativo se comunique com o emulador em vez do Pub/Sub de produção.

Observação: você pode usar endpoints não criptografados (ou seja, http) no emulador, como nos exemplos abaixo. Na produção, recomendamos endpoints seguros (https).

Pré-requisitos

Você precisa ter o seguinte para usar o emulador do Pub/Sub:

Ambiente de desenvolvimento do Python devidamente configurado. Consulte este guia para ver detalhes.
Java JRE (versão 7 ou posterior) instalado.
O Google Cloud SDK instalado. O SDK do Cloud contém a ferramenta de linha de comando gcloud.
Um aplicativo criado com as Bibliotecas de cliente do Google Cloud.

Como instalar o emulador

Instale o emulador no prompt de comando:

    gcloud components install pubsub-emulator
    gcloud components update

Como iniciar o emulador

Invoque pubsub start em um prompt de comando para iniciar o emulador. Antes de executar o comando, substitua PUBSUB_PROJECT_ID por um ID do projeto do Google Cloud. Nesse caso, o ID do projeto pode ser qualquer string válida. Ele não precisa representar um projeto real do Google Cloud porque o emulador do Pub/Sub é executado localmente.

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

Veja uma lista completa de opções em gcloud beta emulators pubsub start.

Depois de iniciar o emulador, você verá uma mensagem semelhante a esta:

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

Isso indica que o servidor do Pub/Sub é executado no endpoint do emulador em sua máquina local em vez do endpoint do Google Cloud. Todas as operações ocorrem localmente, incluindo:

criação de um tópico ou de uma assinatura;
publicação;
assinatura.

Definir variáveis de ambiente

Depois de iniciar o emulador, você precisa definir variáveis de ambiente para que seu aplicativo se conecte ao emulador em vez do Pub/Sub. Defina essas variáveis de ambiente na mesma máquina usada para executar o aplicativo.

Defina as variáveis de ambiente sempre que iniciar o emulador. As variáveis de ambiente dependem de números de portas atribuídos dinamicamente que podem ser alterados ao reiniciar o emulador.

Definir automaticamente as variáveis

Se o aplicativo e o emulador forem executados na mesma máquina, defina as variáveis de ambiente automaticamente:

Linux/macOS

Execute env-init usando a substituição de comando:

    $(gcloud beta emulators pubsub env-init)

Windows

Crie e execute um arquivo de lote usando a saída de env-init:

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

O aplicativo se conectará ao emulador do Pub/Sub.

Definir manualmente as variáveis

Se o aplicativo e o emulador forem executados em máquinas diferentes, configure as variáveis de ambiente manualmente:

Execute o comando env-init:

     gcloud beta emulators pubsub env-init

Na máquina que executa o aplicativo, defina o valor e a variável de ambiente PUBSUB_EMULATOR_HOST de acordo com a direção da saída do comando env-init. Também é possível definir a variável de ambiente PUBSUB_PROJECT_ID referente ao projeto que quer usar para o emulador, mas só precisa configurar PUBSUB_EMULATOR_HOST para que o aplicativo se conecte ao emulador. Exemplo:
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
```

O aplicativo se conectará ao emulador do Pub/Sub.

Observação: para usar o servidor de desenvolvimento local do App Engine Standard para Python, transmita as variáveis de ambiente para a linha de comando da seguinte forma:

Python

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

Como usar o emulador

Para usar o emulador, você precisa ter um aplicativo criado com as bibliotecas de cliente do Google Cloud. O emulador não é compatível com o Console do Cloud nem com os comandos gcloud pubsub.

No exemplo a seguir, demonstramos como criar um tópico, publicar mensagens e ler mensagens com o emulador e um aplicativo que usa a biblioteca de cliente do Google Cloud para Python.

Conclua as seguintes etapas no computador em que você configurou as variáveis de ambiente do emulador:

Faça o download das amostras do Pub/Sub para Python no GitHub. Para isso, clone o repositório inteiro do Python (em inglês). As amostras do Pub/Sub estão no diretório pubsub.
Em seu repositório clonado, navegue até o diretório pubsub/cloud-client. Você concluirá o restante das etapas nesse diretório.
No diretório pubsub/cloud-client, instale as dependências necessárias para executar o exemplo:
```
    pip install -r requirements.txt
    
```

Crie um tópico:

     python publisher.py PUBSUB_PROJECT_ID create TOPIC_ID

(Opcional) Se você não tiver um endpoint de push local para testar inscrições de push no emulador, conclua as etapas a seguir para criar um em http://localhost:3000/messages.
1. Instale o servidor JSON.
```
    npm install -g json-server
    
```
2. Inicie o servidor JSON.
```
    json-server --port 3000 --watch db.json
    
```
  db.json contém o seguinte código inicial:
```
    {
       "messages": []
    }
    
```
3. Anote http://localhost:3000/messages para PUSH_ENDPOINT na próxima etapa.

Crie uma assinatura para o tópico:

Crie uma assinatura de pull:

    python subscriber.py PUBSUB_PROJECT_ID create TOPIC_ID SUBSCRIPTION_ID

Crie uma inscrição de push:

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

Publique mensagens no tópico:

     python publisher.py PUBSUB_PROJECT_ID publish TOPIC_ID

Leia as mensagens publicadas no tópico:

Recupere as mensagens da assinatura de pull:

    python subscriber.py PUBSUB_PROJECT_ID receive SUBSCRIPTION_ID

Observe as mensagens entregues no endpoint de push local. Por exemplo, as mensagens têm esta aparência:

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

Como acessar as variáveis de ambiente

Em todas as linguagens, exceto Java e C#, se você configurar PUBSUB_EMULATOR_HOST conforme descrito em Como definir variáveis de ambiente, as bibliotecas de cliente do Pub/Sub chamarão automaticamente a API em execução na instância local em vez do Pub/Sub.

No entanto, é preciso modificar seu código para usar o emulador nas bibliotecas cliente C# e Java:

C#

Antes de testar este exemplo, siga as instruções de configuração do C# no Guia de início rápido do Cloud Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Cloud Pub/Sub para C# (em inglês).

Ver no GitHub Feedback

// For example, "localhost:8615"
    string emulatorHostAndPort = Environment.GetEnvironmentVariable("PUBSUB_EMULATOR_HOST");

    PublisherServiceApiClient client = new PublisherServiceApiClientBuilder
    {
        Endpoint = emulatorHostAndPort,
        ChannelCredentials = ChannelCredentials.Insecure
    }.Build();
    client.CreateTopic(new TopicName("project", "topic"));
    foreach (var topic in client.ListTopics(new ProjectName("project")))
    {
        Console.WriteLine(topic.Name);
    }

Java

Antes de testar essa amostra, siga as instruções de configuração do Java no guia de início rápido do Cloud Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Cloud Pub/Sub para Java (em inglês).

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

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

Interromper o emulador

Para interromper o emulador, pressione as teclas Ctrl+C.

Depois de interromper o emulador, execute o seguinte comando para remover a variável de ambiente PUBSUB_EMULATOR_HOST para que o aplicativo se conecte ao Pub/Sub:

Linux/macOS

    unset PUBSUB_EMULATOR_HOST

Windows

set PUBSUB_EMULATOR_HOST=

Argumentos de linha de comando do emulador

Consulte os detalhes sobre argumentos de linha de comando do emulador Pub/Sub em gcloud beta emulators pubsub.

Limitações conhecidas

No momento, as RPCs UpdateTopic e UpdateSnapshot não são compatíveis.
As operações do IAM não são compatíveis.
A retenção configurável de mensagens não é compatível. Todas as mensagens são retidas indefinidamente.
A expiração da assinatura não é compatível. As assinaturas não expiram.

Para registrar problemas, acesse o fórum do Pub/Sub (em inglês).