Nesta página, explicamos como publicar mensagens em tópicos do Lite. É possível publicar mensagens com a biblioteca de cliente do Pub/Sub Lite para Java.
Depois de publicar mensagens e criar uma assinatura do Lite em um tópico, é possível receber mensagens da assinatura do Lite.
Formato de mensagem
Uma mensagem consiste em campos com os dados e os metadados da mensagem. Especifique qualquer um dos itens a seguir na mensagem:
- Dados da mensagem
- Uma chave de ordenação
- um horário de evento;
- Atributos com metadados adicionais
A biblioteca de cliente atribui a mensagem automaticamente a uma partição, e o serviço Pub/Sub Lite adiciona os campos a seguir à mensagem:
- Um ID de mensagem exclusivo na partição
- Um carimbo de data/hora para quando o serviço Pub/Sub Lite armazena a mensagem na partição
Como publicar mensagens
Para publicar mensagens, solicite uma conexão de streaming para o tópico do Lite e, em seguida, envie mensagens pela conexão de streaming.
O exemplo a seguir mostra como publicar mensagens em um tópico do Lite:
gcloud
Este comando requer o Python 3.6 ou superior e a instalação do pacote Python grpcio. Para usuários do MacOS, Linux e Cloud Shell, execute o seguinte:
sudo pip3 install grpcio
export CLOUDSDK_PYTHON_SITEPACKAGES=1
Para publicar uma mensagem, use o comando gcloud pubsub lite-topics publish:
gcloud pubsub lite-topics publish TOPIC_ID \
--location=LITE_LOCATION \
--message=MESSAGE_DATA
Substitua:
- TOPIC_ID: o ID do tópico do Lite
- LITE_LOCATION: o local do tópico do Lite;
- MESSAGE_DATA: uma string com os dados da mensagem.
Go
Antes de executar este exemplo, siga as instruções de configuração do Go em Bibliotecas de cliente do Pub/Sub Lite.
Java
Antes de executar este exemplo, siga as instruções de configuração do Java nas bibliotecas de cliente do Pub/Sub Lite.
Python
Antes de executar este exemplo, siga as instruções de configuração do Java nas bibliotecas de cliente do Pub/Sub Lite.
A biblioteca de cliente envia mensagens de forma assíncrona e lida com erros. Se ocorrer um erro, a biblioteca de cliente enviará a mensagem novamente.
- O serviço do Pub/Sub Lite fecha o stream.
- A biblioteca de cliente armazena em buffer as mensagens e restabelece uma conexão com o tópico do Lite.
- A biblioteca cliente envia as mensagens em ordem.
Depois de publicar uma mensagem, o serviço Pub/Sub Lite armazena a mensagem em uma partição e retorna os ID da mensagem para o editor.
Como usar chaves de ordenação
Se as mensagens tiverem a mesma chave de ordenação, a biblioteca de cliente atribuirá as mensagens à mesma partição. A chave de ordenação precisa ser uma string de, no máximo, 1.024 bytes.
A chave de ordenação está no
campo key
de uma mensagem.
É possível definir chaves de ordenação com a biblioteca de cliente.
gcloud
Este comando requer o Python 3.6 ou superior e a instalação do pacote Python grpcio. Para usuários do MacOS, Linux e Cloud Shell, execute o seguinte:
sudo pip3 install grpcio
export CLOUDSDK_PYTHON_SITEPACKAGES=1
Para publicar uma mensagem, use o comando gcloud pubsub lite-topics publish:
gcloud pubsub lite-topics publish TOPIC_ID \
--location=LITE_LOCATION \
--ordering-key=ORDERING_KEY \
--message=MESSAGE_DATA
Substitua:
- TOPIC_ID: o ID do tópico do Lite
- LITE_LOCATION: o local do tópico do Lite;
- ORDERING_KEY: uma string usada para atribuir mensagens a partições;
- MESSAGE_DATA: uma string com os dados da mensagem.
Go
Antes de executar este exemplo, siga as instruções de configuração do Go em Bibliotecas de cliente do Pub/Sub Lite.
Java
Antes de executar este exemplo, siga as instruções de configuração do Java nas bibliotecas de cliente do Pub/Sub Lite.
Python
Antes de executar este exemplo, siga as instruções de configuração do Java nas bibliotecas de cliente do Pub/Sub Lite.
É possível enviar várias mensagens para a mesma partição usando as chaves de ordem. Assim, os assinantes recebem as mensagens na ordem. A biblioteca de cliente pode atribuir várias chaves de ordenação à mesma partição.
Definir o horário do evento
Você pode usar o horário do evento para publicar suas mensagens do Lite. O horário do evento é um horário que você pode adicionar à sua mensagem.
É possível definir o carimbo de data/hora do evento com a biblioteca de cliente ou a CLI gcloud.
Este comando requer o Python 3.6 ou superior e a instalação do pacote Python grpcio. Para usuários do MacOS, Linux e Cloud Shell, execute o seguinte:
sudo pip3 install grpcio
export CLOUDSDK_PYTHON_SITEPACKAGES=1
Para publicar uma mensagem, use o comando gcloud pubsub lite-topics publish:
gcloud pubsub lite-topics publish TOPIC_ID \
--location=LITE_LOCATION \
--event-time=EVENT_TIME \
--message=MESSAGE_DATA
Substitua:
TOPIC_ID: o ID do tópico do Lite
LITE_LOCATION: o local do tópico do Lite;
EVENT_TIME: um horário do evento especificado pelo usuário. Para mais informações sobre formatos de hora, execute
gcloud topic datetimes
.MESSAGE_DATA: uma string com os dados da mensagem;
Como usar atributos
Atributos da mensagem são pares de chave-valor com metadados sobre a mensagem. Os atributos podem ser strings de texto ou de byte.
Os atributos estão no
campo attributes
de uma mensagem. Você pode definir atributos com a biblioteca de cliente.
gcloud
Este comando requer o Python 3.6 ou superior e a instalação do pacote Python grpcio. Para usuários do MacOS, Linux e Cloud Shell, execute o seguinte:
sudo pip3 install grpcio
export CLOUDSDK_PYTHON_SITEPACKAGES=1
Para publicar uma mensagem, use o comando gcloud pubsub lite-topics publish:
gcloud pubsub lite-topics publish TOPIC_ID \
--location=LITE_LOCATION \
--message=MESSAGE_DATA \
--attribute=KEY=VALUE,...
Substitua:
- TOPIC_ID: o ID do tópico do Lite
- LITE_LOCATION: o local do tópico do Lite;
- MESSAGE_DATA: uma string com os dados da mensagem;
- KEY: a chave de um atributo de mensagem
- VALUE: o valor da chave do atributo da mensagem
Go
Antes de executar este exemplo, siga as instruções de configuração do Go em Bibliotecas de cliente do Pub/Sub Lite.
Java
Antes de executar este exemplo, siga as instruções de configuração do Java nas bibliotecas de cliente do Pub/Sub Lite.
Python
Antes de executar este exemplo, siga as instruções de configuração do Java nas bibliotecas de cliente do Pub/Sub Lite.
Os atributos podem indicar como processar uma mensagem. Os assinantes podem analisar o
campo attributes
de uma mensagem e processar a mensagem de acordo com os
atributos dela.
Mensagens em lote
A biblioteca de cliente publica mensagens em lotes. Os lotes maiores usam menos recursos de computação, mas aumentam a latência. É possível alterar o tamanho do lote com configurações de lote.
A tabela a seguir lista as configurações de lote que podem ser definidas:
Configuração | Descrição | Padrão |
---|---|---|
Tamanho da solicitação | O tamanho máximo, em bytes, do lote. | 3.5 MiB |
número de mensagens | O número máximo de mensagens em um lote. | 1.000 mensagens |
Atraso na publicação | O tempo, em milissegundos, entre adicionar a mensagem a um lote e enviá-lo ao tópico do Lite. | 50 milissegundos |
É possível definir configurações em lote com a biblioteca de cliente.
Go
Antes de executar este exemplo, siga as instruções de configuração do Go em Bibliotecas de cliente do Pub/Sub Lite.
Java
Antes de executar este exemplo, siga as instruções de configuração do Java nas bibliotecas de cliente do Pub/Sub Lite.
Python
Antes de executar este exemplo, siga as instruções de configuração do Java nas bibliotecas de cliente do Pub/Sub Lite.
Quando um aplicativo do editor é iniciado, a biblioteca de cliente cria um lote para cada partição em um tópico do Lite. Por exemplo, se um tópico do Lite tem duas partições, os editores criam dois lotes e enviam cada lote para uma partição.
Depois de publicar uma mensagem, a biblioteca cliente a armazena em buffer até que o lote exceda o tamanho máximo da solicitação, o número máximo de mensagens ou o atraso de publicação.
Como ordenar mensagens
Os tópicos do Lite classificam as mensagens em cada partição ao publicar as mensagens. Para atribuir mensagens à mesma partição, use uma chave de ordenação.
O Pub/Sub Lite entrega as mensagens de uma partição em ordem, e os assinantes podem processá-las na ordem. Para mais detalhes, consulte Como receber mensagens.
Idempotência da publicação
As bibliotecas de cliente do Pub/Sub Lite são compatíveis com publicações idempotentes, seguintes versões:
- java-pubsublite: versão 1.10.0.
- python-pubsublite: versão 1.8.0.
- google-cloud-go: versão 1.7.0 do pubsublite.
Se houver uma nova tentativa de publicação de uma mensagem devido a erros na rede ou no servidor, armazenados exatamente uma vez. A idempotência é garantida somente dentro da mesma sessão. não é possível garantir que a mesma mensagem seja publicada novamente usando um novo editor para o cliente. Ele não tem custos adicionais de serviço nem aumenta a latência de rede.
Ativar ou desativar a publicação idempotente
A publicação Idempotente é ativada por padrão no cliente do Pub/Sub Lite bibliotecas. Ela pode ser desativada usando as configurações de cliente do editor nas respectivas biblioteca de cliente.
Se a publicação idempotente estiver ativada, o deslocamento retornado em um resultado de publicação
pode ser -1
. Esse valor é retornado quando a mensagem é identificada como um
cópia de uma mensagem já publicada, mas o servidor não
têm informações suficientes para retornar o deslocamento da mensagem no momento da publicação.
As mensagens recebidas pelos assinantes sempre têm um deslocamento válido.
Solução de problemas
Cópias recebidas
Como a idempotência é limitada a uma única sessão, cópias podem ser recebidas se você recria o cliente editor para publicar as mesmas mensagens.
Um cliente assinante pode receber a mesma mensagem várias vezes se as partições são atribuídos automaticamente aos assinantes pelo serviço Pub/Sub Lite (a configuração padrão). Uma mensagem pode ser reenviada para outro assinante quando ocorre uma reatribuição.
Erro do editor
O estado de uma sessão do editor é como um lixo coletado no servidor após sete dias de inatividade. Se uma sessão for retomada após esse período, o cliente editor termina com uma mensagem de erro semelhante a "Falha na pré-condição: esperada para que o número de sequência de publicação de..." e não aceita novas mensagens. Recrie o cliente do editor para resolver esse erro.