Como testar aplicativos localmente com o emulador

Para desenvolver e testar seu aplicativo localmente, é possível usar o emulador do Pub/Sub, que fornece emulação local do serviço 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 serviço de Pub/Sub de produção. Os recursos criados e as mensagens publicadas no emulador são mantidos durante o ciclo de vida da sessão do emulador.

Observação: para testar assinaturas de push no emulador, use endpoints de push não criptografados (ou seja, http), como nos exemplos abaixo. Na produção, somente endpoints de push seguros (https) são permitidos.

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 cliente do Google Cloud.

Como instalar o emulador

Instale o emulador no prompt de comando:

gcloud components install pubsub-emulator
gcloud components update

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 uma string válida de ID do projeto do Google Cloud. A string 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]

Consulte gcloud beta emulators pubsub start para ver uma lista completa de sinalizações.

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;
Inscrição

Como 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. Faça isso na mesma máquina usada na execução do seu aplicativo.

É necessário configurar as variáveis de ambiente sempre que iniciar o emulador. Elas dependem de números de portas dinamicamente atribuídas que podem ser alteradas durante a reinicialização do emulador.

Como configurar 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.

Como configurar 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, passe 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).
Em seu repositório clonado, navegue até o diretório samples/snippets. Você concluirá o restante das etapas nesse diretório.
No diretório samples/snippets, 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 essa amostra, siga as instruções de configuração do C# no Guia de início rápido do Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C#.

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 Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Java.

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

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

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.

Recursos compatíveis

O emulador é compatível com os seguintes recursos do Pub/Sub:

Como publicar mensagens
Como receber mensagens de assinaturas de push e pull
Como ordenar mensagens
Como repetir mensagens
Como encaminhar mensagens para tópicos de mensagem mortas
Novas tentativas de entrega na entrega de mensagens
Compatibilidade de esquema com Avro

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.
A filtragem não é compatível.
Suporte a esquema para buffers de protocolo.

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