Neste documento, você verá informações sobre a publicação de mensagens.
Um aplicativo do editor cria e envia mensagens para um tópico. O Pub/Sub oferece entrega de mensagens pelo menos uma vez e ordenação de melhor esforço para os assinantes atuais.
Este é o fluxo geral de um aplicativo do editor:
- Criar uma mensagem contendo seus dados.
- Envie uma solicitação ao servidor do Pub/Sub para publicar a mensagem no tópico especificado.
Antes de começar
Antes de configurar o fluxo de trabalho de publicação, conclua as seguintes tarefas:
- Saiba mais sobre tópicos e o fluxo de trabalho de publicação.
- Crie um tópico.
- Escolha e crie uma assinatura.
Funções exigidas
Para ter as permissões necessárias para publicar mensagens em um tópico,
peça ao administrador para conceder a você o
papel do IAM de Editor do Pub/Sub (roles/pubsub.publisher
) no tópico.
Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.
Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.
Você precisa de permissões adicionais para criar ou atualizar tópicos e assinaturas.
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
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
Para saber mais sobre as mensagens, consulte Formato das mensagens.
Publique mensagens
É possível publicar mensagens com o console do Google Cloud, a Google Cloud CLI, a API Pub/Sub e as bibliotecas de cliente. As bibliotecas de cliente podem publicar mensagens de maneira assíncrona.
Os exemplos a seguir demonstram como publicar uma mensagem em um tópico.
Console
Para publicar uma mensagem, siga estas etapas:
No console do Google Cloud, acesse a página de tópicos do Pub/Sub.
Clique no código do tópico.
Na página Detalhes do tópico em Mensagens, clique em Publicar mensagem.
No campo Corpo da mensagem, digite os dados da mensagem.
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 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 Content-Type: application/json 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.
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.
Usar atributos para publicar uma mensagem
É possível incorporar atributos personalizados como metadados nas mensagens do Pub/Sub. Os atributos são usados para dar mais informações sobre a mensagem, como prioridade, origem ou destino. Os atributos também podem ser usados para filtrar mensagens na assinatura.
Siga estas diretrizes para usar atributos nas suas mensagens:
Os atributos podem ser strings de texto ou de bytes.
Você pode ter no máximo 100 atributos por mensagem.
As chaves de atributo não podem começar com
goog
e não podem exceder 256 bytes.Os valores do atributo não podem exceder 1.024 bytes.
O esquema da mensagem pode ser representado da seguinte forma:
{ "data": string, "attributes": { string: string, ... }, "messageId": string, "publishTime": string, "orderingKey": string }
Para cópias do lado da publicação, é possível ver valores publishTime
diferentes
para a mesma mensagem original no lado do cliente, mesmo com o mesmo messageId
.
O esquema JSON do PubsubMessage
é publicado como parte da documentação do REST e RPC. Você pode usar atributos personalizados para carimbos de data/hora de eventos.
Os exemplos a seguir demonstram como publicar uma mensagem com atributos em um tópico.
Console
Para publicar uma mensagem com atributos, siga estas etapas:
No console do Google Cloud, acesse a página Tópicos.
Clique no tópico em que você quer publicar mensagens.
Na página de detalhes do tópico, clique em Mensagens.
Clique em Publicar mensagem.
No campo Corpo da mensagem, digite os dados da mensagem.
Em Atributos da mensagem, clique em Adicionar um atributo.
Insira um par de chave-valor.
Adicione mais atributos, se necessário.
Clique em Publicar.
gcloud
gcloud pubsub topics publish my-topic --message="hello" \ --attribute="origin=gcloud-sample,username=gcp,eventTime='2021-01-01T12:00:00Z'"
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.
Usar chaves de ordenação para publicar uma mensagem
Para receber mensagens em ordem nos clientes assinantes, configure os clientes do editor para publicar mensagens com chaves de ordenação.
Para entender o conceito de ordenação de chaves, consulte Ordenar mensagens.
Esta é uma lista de considerações importantes sobre mensagens ordenadas para clientes editores:
Ordem em um único cliente editor: quando um único cliente editor publica mensagens com a mesma chave de ordem na mesma região, o assinante recebe essas mensagens na ordem exata em que foram publicadas. Por exemplo, se um cliente editor publicar as mensagens 1, 2 e 3 com a chave de ordenação A, o cliente assinante as receberá na ordem 1, 2, 3.
Ordem em vários clientes de editores: a ordem das mensagens recebidas pelos clientes assinantes é consistente com a ordem em que foram publicadas na mesma região, mesmo quando vários clientes de editores usam a mesma chave de ordem. No entanto, os próprios clientes do editor não têm conhecimento desse pedido.
Por exemplo, se os clientes do editor X e Y publicarem mensagens com a chave de ordenação A, e a mensagem de X for recebida pelo Pub/Sub antes da Y, todos os clientes do assinante receberão a mensagem de X antes da Y. Se for necessária uma ordem estrita das mensagens em diferentes clientes de editores, esses clientes precisarão implementar um mecanismo adicional de coordenação para garantir que não publiquem mensagens com a mesma chave de ordem simultaneamente. Por exemplo, um serviço de bloqueio pode ser usado para manter a propriedade de uma chave de ordem durante a publicação.
Ordem entre regiões: a ordem das mensagens é esperada apenas para mensagens publicadas na mesma região. Portanto, verifique se os clientes do editor usam os endpoints do serviço de localização para publicar mensagens na mesma região para a mesma chave de ordem. Os clientes assinantes podem receber essas mensagens em ordem.
Falhas de publicação: quando a publicação com uma chave de ordem falha, as mensagens em fila da mesma chave de ordem no editor falham, incluindo futuras solicitações de publicação dessa chave. Será preciso retomar a publicação com chaves de ordenação quando essas falhas ocorrerem. Para um exemplo de como retomar a operação de publicação, consulte Repetir solicitações com chaves de ordenação.
É possível publicar mensagens com chaves de ordenação usando o console do Google Cloud, a Google Cloud CLI, a API Pub/Sub ou as bibliotecas de cliente.
Console
Para publicar uma mensagem com atributos, siga estas etapas:
No console do Google Cloud, acesse a página Tópicos.
Clique no tópico em que você quer publicar mensagens.
Na página de detalhes do tópico, clique em Mensagens.
Clique em Publicar mensagem.
No campo Corpo da mensagem, digite os dados da mensagem.
No campo Ordem da mensagem, 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 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 Content-Type: application/json 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.
Monitorar um editor
O Cloud Monitoring tem várias métricas para monitorar tópicos.
Para monitorar um tópico e manter um editor íntegro, consulte Manter um editor íntegro.
A seguir
Para restringir os locais em que o Pub/Sub armazena dados de mensagens, consulte Como restringir locais de recursos do Pub/Sub.
Para publicar mensagens com esquema, consulte Visão geral do esquema.
Para saber como configurar opções avançadas de entrega, consulte: