Para publicar uma mensagem com o Pub/Sub, um aplicativo editor cria e envia mensagens para um tópico.
Este documento oferece uma visão geral do fluxo de trabalho de publicação, incluindo o conceito de tópicos e mensagens.
Sobre os tópicos
Um tópico do Pub/Sub é um recurso nomeado que representa um feed de mensagens. Quando um editor envia uma mensagem, ele tem como destino um tópico específico. O serviço do Pub/Sub usa esse nome de tópico para encaminhar a mensagem a todas as assinaturas anexadas ao tópico. Se houver vários assinantes para uma assinatura, apenas um deles receberá a mensagem.
Os editores não precisam saber quantos assinantes existem. Eles se concentram no tópico, garantindo a separação de problemas entre o envio e o recebimento de mensagens.
O Pub/Sub oferece suporte a dois tipos de tópicos: um padrão e um de importação.
Propriedades de um tópico
Ao criar ou atualizar um tópico, é possível especificar as propriedades dele.
Para mais informações sobre as propriedades do tópico, consulte Propriedades de um tópico.
Sobre os tópicos de importação
Um tópico de importação permite que o Pub/Sub ingira dados de streaming de outra origem e atue como o aplicativo editor que envia os dados para o tópico. É possível ativar a ingestão em um tópico usando o console, a Google Cloud CLI, chamadas REST ou as bibliotecas de cliente. Como parte do gerenciamento do tópico de importação, Google Cloud o oferece monitoramento e escalonamento do pipeline de ingestão.
Sem um tópico de importação, o streaming de dados para o Pub/Sub de uma fonte de dados exige um serviço adicional. Esse serviço adicional extrai dados da origem original e os publica no Pub/Sub. O serviço adicional pode ser um mecanismo de streaming, como o Apache Spark, ou um serviço personalizado. Também é necessário configurar, implantar, executar, escalonar e monitorar esse serviço.
A seguir, uma lista de informações importantes sobre tópicos de importação:
Assim como um tópico padrão, ainda é possível publicar manualmente em um tópico de importação.
Só é possível anexar uma única fonte de ingestão a um tópico de importação.
Recomendamos tópicos de importação para dados de streaming. Se você estiver considerando a ingestão de dados em lote no BigQuery em vez da ingestão de dados de streaming, tente o serviço de transferência de dados do BigQuery. Se você quiser ingerir dados no Cloud Storage, o Serviço de transferência do Cloud Storage (STS) é uma boa opção.
O Pub/Sub oferece suporte às seguintes origens para tópicos de importação:
Replicação de dados em um tópico
Um tópico do Pub/Sub usa três zonas para armazenar dados. O serviço oferece suporte à replicação síncrona em pelo menos duas zonas e à replicação de melhor esforço em uma terceira zona adicional. A replicação do Pub/Sub está em apenas uma região.
Sobre as mensagens
Uma mensagem do Pub/Sub são os dados transferidos pelo serviço.
Uma mensagem consiste em campos com os dados e os metadados da mensagem. Uma mensagem precisa conter dados ou pelo menos um atributo.
Os dados da mensagem: esse é o conteúdo principal da mensagem e pode ser qualquer texto ou dado binário. Ele representa as informações reais que você quer comunicar entre editores e assinantes. Se você estiver usando a API REST diretamente, os dados da mensagem precisarão ser codificados em base64. Consulte o exemplo na guia REST na seção Publicar mensagens.
Uma chave de ordenação: esse é um identificador opcional que representa a entidade para a qual as mensagens precisam ser ordenadas. As mensagens com a mesma chave de ordenação precisam ser entregues a um assinante na ordem em que foram publicadas. Uma chave de ordenação só é necessária se você quiser a entrega ordenada das mensagens. Para mais informações sobre chaves de ordenação, consulte Ordenar mensagens.
Atributos: são pares de chave-valor opcionais que fornecem contexto e informações adicionais sobre a mensagem. Eles podem ser usados para rotear, filtrar ou enriquecer o conteúdo da mensagem. Por exemplo, é possível adicionar atributos como carimbos de data/hora ou IDs de transação. Para mais informações sobre atributos usados na publicação de mensagens, consulte Usar atributos para publicar uma mensagem.
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
Ao publicar mensagens usando bibliotecas de cliente do Pub/Sub, forneça os data da mensagem como uma matriz de bytes, como um Buffer do Node.js. Se os dados forem uma string, primeiro será necessário codificá-los em bytes, por exemplo, usando a codificação UTF-8, antes de transmiti-los à biblioteca de cliente.
Se você estiver usando a API REST diretamente, os dados da mensagem precisarão ser codificados em base64 e enviados como uma string.
O exemplo a seguir mostra uma representação JSON de uma mensagem enviada por um cliente:
{
"data": "VGhpcyBpcyB0aGUgY29yZSBtZXNzYWdlIGNvbnRlbnQu",
"attributes": {
"category": "notification",
"user_id": "12345",
"priority": "medium"
},
"orderingKey": "12345"
}
Quando um assinante recebe a mensagem, ela inclui valores para messageId e publishTime, adicionados pelo serviço do Pub/Sub:
{
"data": "VGhpcyBpcyB0aGUgY29yZSBtZXNzYWdlIGNvbnRlbnQu",
"attributes": {
"category": "notification",
"user_id": "12345",
"priority": "medium"
},
"messageId": "19443130675731448",
"publishTime": "2026-05-04T23:15:19.863Z",
"orderingKey": "12345"
}
}
Fluxo de trabalho de publicação de mensagens
Para publicar uma mensagem com o Pub/Sub, um aplicativo editor cria e envia mensagens para um tópico.
- Criar uma mensagem contendo seus dados.
- Selecione os atributos de publicação opcionais.
- Envie uma solicitação para o servidor do Pub/Sub publicar a mensagem em um tópico especificado.
O serviço do Pub/Sub recebe a mensagem e a processa da seguinte maneira:
A mensagem é armazenada para distribuição.
A mensagem é replicada em várias zonas para durabilidade e alta disponibilidade.
O Pub/Sub identifica os assinantes com assinaturas que correspondem ao tópico da mensagem e entrega uma cópia da mensagem a cada um deles.
O Pub/Sub oferece entrega de mensagens pelo menos uma vez e ordenação de melhor esforço para os assinantes atuais.
Para mais informações sobre o sistema do Pub/Sub, consulte Visão geral do serviço do Pub/Sub.
Para mais informações sobre como o Pub/Sub funciona, consulte Visão geral arquitetônica do Pub/Sub.