Neste documento, você verá informações sobre a publicação de mensagens.
Para informações sobre como criar, excluir e administrar tópicos e assinaturas, consulte Como gerenciar tópicos e assinaturas.
Para restringir por tópico os locais em que dados de mensagem são armazenados, consulte Como restringir locais de recursos do Pub/Sub.
Para mais informações sobre como receber mensagens, consulte o Guia do assinante.
Um aplicativo do editor cria e envia mensagens para um tópico. O Pub/Sub oferece entrega da mensagem pelo menos uma vez e ordenação dos assinantes existentes no modelo de "melhor esforço" (best-effort), como explicado na Visão geral do assinante.
Este é o fluxo geral de um aplicativo do editor:
- Criar uma mensagem contendo seus dados.
- Enviar uma solicitação para o servidor do Pub/Sub publicar a mensagem no tópico desejado.
Formato de mensagem
Uma mensagem consiste em campos com os dados e os metadados da mensagem. Especifique pelo menos um dos seguintes itens na mensagem:
- Dados da mensagem
- Uma chave de ordenação
- Atributos com metadados adicionais
Se você estiver usando a API REST, os dados da mensagem precisarão ser codificados em base64.
O serviço Pub/Sub adiciona os seguintes campos à mensagem:
- Um ID de mensagem exclusivo para o tópico
- Carimbo de data/hora de quando o serviço do Pub/Sub recebe a mensagem
Como publicar mensagens
É possível publicar mensagens com a ferramenta de linha de comando gcloud
ou a API Pub/Sub. As
bibliotecas de cliente podem publicar mensagens de forma assíncrona.
Console
Para publicar uma mensagem, siga estas etapas:
No Console do Cloud, acesse a página Tópicos do Pub/Sub.
Clique no código do tópico.
Na página Detalhes do tópico, clique em Publicar mensagens.
No campo Corpo da mensagem, digite os dados da mensagem.
Opcional: adicione atributos de mensagens.
Clique em Adicionar atributo de mensagem.
Insira uma chave e um valor para o atributo.
Clique em Publicar.
gcloud
Para publicar uma mensagem, use o comando gcloud pubsub topics publish:
gcloud pubsub topics publish TOPIC_ID \ --message=MESSAGE_DATA \ [--attribute=KEY="VALUE",...]
Substitua:
- TOPIC_ID: o ID do tópico
- MESSAGE_DATA: uma string codificada em base64 com os dados da mensagem.
- KEY: a chave de um atributo de mensagem
- VALUE: o valor da chave do atributo da mensagem
REST
Para publicar uma mensagem, envie uma solicitação POST como esta:
POST https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID:publish Authorization: Bearer $(gcloud auth application-default print-access-token)
Substitua:
- PROJECT_ID: o ID do projeto com o tópico.
- TOPIC_ID: o ID do tópico
Especifique os campos a seguir no corpo da solicitação:
{ "messages": [ { "attributes": { "KEY": "VALUE", ... }, "data": "MESSAGE_DATA", } ] }
Substitua:
- KEY: a chave de um atributo de mensagem
- VALUE: o valor da chave do atributo da mensagem
- MESSAGE_DATA: uma string codificada em base64 com os dados da mensagem.
A mensagem precisa conter um campo de dados não vazio ou pelo menos um atributo.
Se a solicitação for bem-sucedida, a resposta será um objeto JSON com o ID da mensagem. O exemplo a seguir é uma resposta com um ID de mensagem.
{ "messageIds": [ "19916711285", ] }
C++
Antes de tentar esse exemplo, siga as instruções de configuração do C++ em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C++.
C#
Antes de tentar esse exemplo, siga as instruções de configuração do C# em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C#.
Go
Antes de tentar esse exemplo, siga as instruções de configuração do Go em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Go.
Java
Antes de tentar essa amostra, siga as instruções de configuração do Java em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Java.
Node.js
Antes de tentar essa amostra, siga as instruções de configuração do Node.js em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Node.js.
PHP
Antes de tentar esse exemplo, siga as instruções de configuração do PHP em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub PHP.
Python
Antes de tentar esse exemplo, siga as instruções de configuração do Python em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Python.
Ruby
Antes de tentar esse exemplo, siga as instruções de configuração do Ruby em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Ruby.
Depois que você publica uma mensagem, o serviço do Pub/Sub retorna o ID da mensagem ao editor.
Como usar atributos
É possível incorporar atributos personalizados como metadados nas mensagens do Pub/Sub. Os atributos podem ser strings de texto ou de bytes. O esquema da mensagem pode ser representado da seguinte forma:
{ "data": string, "attributes": { string: string, ... }, "messageId": string, "publishTime": string, "orderingKey": string }
O esquema JSON do PubsubMessage
é publicado como parte da documentação do REST e RPC.
gcloud
gcloud pubsub topics publish my-topic --message="hello" \ --attribute="origin=gcloud-sample,username=gcp"
C++
Antes de tentar esse exemplo, siga as instruções de configuração do C++ em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C++.
C#
Antes de tentar esse exemplo, siga as instruções de configuração do C# em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C#.
Go
Antes de tentar esse exemplo, siga as instruções de configuração do Go em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Go.
Java
Antes de tentar essa amostra, siga as instruções de configuração do Java em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Java.
Node.js
Antes de tentar essa amostra, siga as instruções de configuração do Node.js em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Node.js.
Python
Antes de tentar esse exemplo, siga as instruções de configuração do Python em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Python.
Ruby
Antes de tentar esse exemplo, siga as instruções de configuração do Ruby em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Ruby.
Como usar chaves de ordenação
Se as mensagens tiverem a mesma chave de ordem e você publicar as mensagens na mesma região, os assinantes poderão receber as mensagens na ordem. A publicação de mensagens com chaves de ordem pode aumentar a latência. Para publicar mensagens na mesma região, use um endpoint regional.
É possível publicar mensagens com chaves de ordem usando o Console do Cloud, a ferramenta de linha de comando gcloud
ou a API Pub/Sub.
Console
No Console do Cloud, acesse a página Tópicos do Pub/Sub.
Clique no código do tópico.
Na página Detalhes do tópico, clique em Publicar mensagens.
No campo Corpo da mensagem, digite os dados da mensagem.
No campo Chave de ordem, insira uma chave de ordem.
Clique em Publicar.
gcloud
Para publicar uma mensagem com uma chave de ordem, use o comando gcloud pubsub topics publish
e a sinalização --ordering-key
:
gcloud pubsub topics publish TOPIC_ID \ --message=MESSAGE_DATA \ --ordering-key=ORDERING_KEY
Substitua:
- TOPIC_ID: o ID do tópico
- MESSAGE_DATA: uma string codificada em base64 com os dados da mensagem.
- ORDERING_KEY: uma string com uma chave de ordem
REST
Para publicar uma mensagem com uma chave de ordem, envie uma solicitação POST como esta:
POST https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID:publish Authorization: Bearer $(gcloud auth application-default print-access-token)
Substitua:
- PROJECT_ID: o ID do projeto com o tópico.
- TOPIC_ID: o ID do tópico
Especifique os campos a seguir no corpo da solicitação:
{ "messages": [ { "attributes": { "KEY": "VALUE", ... }, "data": "MESSAGE_DATA", "ordering_key": "ORDERING_KEY", } ] }
Substitua:
- KEY: a chave de um atributo de mensagem
- VALUE: o valor da chave do atributo da mensagem
- MESSAGE_DATA: uma string codificada em base64 com os dados da mensagem.
- ORDERING_KEY: uma string com uma chave de ordem
A mensagem precisa conter um campo de dados não vazio ou pelo menos um atributo.
Se a solicitação for bem-sucedida, a resposta será um objeto JSON com o ID da mensagem. O exemplo a seguir é uma resposta com um ID de mensagem.
{ "messageIds": [ "19916711285", ] }
C++
Antes de tentar esse exemplo, siga as instruções de configuração do C++ em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C++.
C#
Antes de tentar esse exemplo, siga as instruções de configuração do C# em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C#.
Go
Antes de tentar esse exemplo, siga as instruções de configuração do Go em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Go.
Java
Antes de tentar essa amostra, siga as instruções de configuração do Java em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Java.
Node.js
Antes de tentar essa amostra, siga as instruções de configuração do Node.js em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Node.js.
Python
Antes de tentar esse exemplo, siga as instruções de configuração do Python em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Python.
Ruby
Antes de tentar esse exemplo, siga as instruções de configuração do Ruby em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Ruby.
Mensagens em lote
As bibliotecas de cliente do Pub/Sub agrupam várias mensagens em uma única chamada para o serviço. Lotes maiores aumentam a capacidade das mensagens, ou seja, a taxa de mensagens enviadas por CPU. O custo do agrupamento é a latência das mensagens individuais, que são enfileiradas na memória até que o lote correspondente seja completamente preenchido e esteja pronto para ser enviado pela rede. Para minimizar a latência, desative o agrupamento. Isso é particularmente importante para aplicativos que publicam uma única mensagem como parte de uma sequência de solicitação e resposta. Um exemplo comum desse padrão pode ser observado em aplicativos sem servidor e orientados a eventos que usam o Cloud Functions ou o App Engine.
As mensagens podem ser agrupadas com base no tamanho da solicitação em bytes, na quantidade de mensagens e no tempo. Você pode modificar as configurações padrão conforme exibido nesta amostra:
C++
Antes de tentar esse exemplo, siga as instruções de configuração do C++ em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C++.
C#
Antes de tentar esse exemplo, siga as instruções de configuração do C# em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C#.
Go
Antes de tentar esse exemplo, siga as instruções de configuração do Go em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Go.
Java
Antes de tentar essa amostra, siga as instruções de configuração do Java em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Java.
Node.js
Antes de tentar essa amostra, siga as instruções de configuração do Node.js em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Node.js.
PHP
Antes de tentar esse exemplo, siga as instruções de configuração do PHP em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub PHP.
Python
Antes de tentar esse exemplo, siga as instruções de configuração do Python em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Python.
Ruby
Antes de tentar esse exemplo, siga as instruções de configuração do Ruby em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Ruby.
Como reenviar solicitações
As publicações com falha são automaticamente reenviadas, com a exceção de erros que não possibilitem novas tentativas. Este exemplo de código demonstra a criação de um editor com configurações de reenvio personalizadas. Nem todas as bibliotecas de cliente são compatíveis com essas configurações, por isso consulte a documentação de referência de APIs para a linguagem escolhida.
C++
Antes de tentar esse exemplo, siga as instruções de configuração do C++ em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C++.
C#
Antes de tentar esse exemplo, siga as instruções de configuração do C# em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C#.
Java
Antes de tentar essa amostra, siga as instruções de configuração do Java em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Java.
Node.js
Antes de tentar essa amostra, siga as instruções de configuração do Node.js em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Node.js.
Python
Antes de tentar esse exemplo, siga as instruções de configuração do Python em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Python.
As configurações de nova tentativa controlam como as bibliotecas de cliente do Pub/Sub tentam publicar solicitações novamente. As bibliotecas de cliente têm alguma das seguintes configurações de repetição:
- Tempo limite da solicitação inicial: o tempo antes de uma biblioteca de cliente parar de esperar a conclusão da solicitação de publicação inicial.
- Atraso de nova tentativa: quanto tempo após uma solicitação atingir o tempo limite em que uma biblioteca de cliente aguarda a nova tentativa de solicitação.
- Tempo limite total: quanto tempo antes de uma biblioteca de cliente parar de tentar publicar as solicitações novamente.
Para tentar publicar as solicitações novamente, o tempo limite da solicitação inicial precisa ser menor que o tempo limite total. Por exemplo, se você estiver usando espera exponencial, as bibliotecas de cliente calculam o tempo limite da solicitação e o atraso de nova tentativa da seguinte maneira:
- Após cada solicitação de publicação, o tempo limite da solicitação aumenta de acordo com o multiplicador de tempo limite da solicitação, até atingir o tempo limite máximo.
- Após cada nova tentativa, o tempo de atraso para a nova tentativa aumenta de acordo com o multiplicador de atraso máximo, até o atraso máximo de nova tentativa.
Quando uma biblioteca de cliente repete uma solicitação e a mensagem tem uma chave de ordem, ela repete repetidamente a solicitação, independentemente das configurações de tentativa.
Se ocorrer um erro não passível de repetição, a biblioteca de cliente não publicará a mensagem e interromperá a publicação de outras mensagens com a mesma chave de ordem. Por exemplo, quando um editor envia uma mensagem para um tópico que não existe, ocorre um erro que não pode ser repetido. Para continuar publicando mensagens com a mesma chave de ordem, chame um método para retomar a publicação e comece a publicar novamente.
O exemplo a seguir mostra como retomar a publicação de mensagens com a mesma chave de ordem.
C++
Antes de tentar esse exemplo, siga as instruções de configuração do C++ em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C++.
C#
Antes de tentar esse exemplo, siga as instruções de configuração do C# em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C#.
Go
Antes de tentar esse exemplo, siga as instruções de configuração do Go em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Go.
Java
Antes de tentar essa amostra, siga as instruções de configuração do Java em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Java.
Node.js
Antes de tentar essa amostra, siga as instruções de configuração do Node.js em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Node.js.
Python
Antes de tentar esse exemplo, siga as instruções de configuração do Python em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Python.
Ruby
Antes de tentar esse exemplo, siga as instruções de configuração do Ruby em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Ruby.
Controle de simultaneidade
A compatibilidade com a simultaneidade depende da linguagem de programação. Consulte a documentação de referência de APIs para mais informações.
O exemplo a seguir ilustra como controlar a simultaneidade em um editor:
C++
Antes de tentar esse exemplo, siga as instruções de configuração do C++ em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C++.
Go
Antes de tentar esse exemplo, siga as instruções de configuração do Go em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Go.
Java
Antes de tentar essa amostra, siga as instruções de configuração do Java em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Java.
Ruby
Antes de tentar esse exemplo, siga as instruções de configuração do Ruby em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Ruby.