Ao criar seu sistema do Pub/Sub, o desencapsulamento de payload pode ajudar você a se conectar a outros sistemas que não seguem todos os requisitos de uma implementação padrão de endpoint de push do Pub/Sub.
Confira alguns casos de uso possíveis para desencapsulamento de payload:
- Você não quer escrever um código de análise de mensagens específico do Pub/Sub para seus endpoints de push HTTP.
- Você prefere receber metadados de mensagens do Pub/Sub como cabeçalhos HTTP em vez dos metadados no corpo HTTP POST.
- Você quer enviar mensagens do Pub/Sub e excluir os metadados dele, por exemplo, ao enviar dados para uma API de terceiros.
Como funciona o desencapsulamento de payload
O desencapsulamento de payload é um recurso que remove todos os metadados das mensagens do Pub/Sub, exceto os dados da mensagem. Ao enviar dados de mensagens brutos, os assinantes podem processar a mensagem sem precisar obedecer a nenhum requisito de sistema do Pub/Sub.
- Com o desencapsulamento de payload, os dados da mensagem são entregues diretamente como o corpo HTTP.
- Sem o desencapsulamento de payload, o Pub/Sub entrega um objeto JSON que contém vários campos de metadados de mensagem e um campo de dados de mensagem. Nesse caso, o JSON precisa ser analisado para recuperar os dados da mensagem e, em seguida, decodificado em base64.
Gravar metadados
Depois de ativar o desencapsulamento de payload, use a opção gravar metadados, que adiciona os metadados removidos das mensagens ao cabeçalho da solicitação.
- Gravar metadados ativado. Adicione os metadados da mensagem de volta ao cabeçalho da solicitação. Também mostra os dados brutos e decodificados da mensagem.
- Gravação de metadados desativada. Mostra apenas os dados brutos e decodificados da mensagem.
Os metadados de gravação são expostos pelo Pub/Sub, pelo argumento --push-no-wrapper-write-metadata
da Google Cloud CLI e pela propriedade NoWrapper
da API.
Por padrão, esse valor é nulo.
Antes de começar
- Saiba mais sobre as assinaturas e as assinaturas push do Pub/Sub. O desencapsulamento de payload só pode ser usado com assinaturas de push.
- Saiba como configurar uma assinatura push.
Exemplo de mensagens encapsuladas e não encapsuladas
Os exemplos a seguir ilustram a diferença entre enviar uma mensagem HTTP
encapsulada e desencapsulada. Nesses exemplos, os dados da mensagem contêm a string {"status": "Hello there"}
.
Neste exemplo, uma assinatura é criada com o recurso de desencapsulamento de payload
ativado e publica uma mensagem em mytopic
. Ele usa uma chave de ordenação com o valor some-key
e o tipo de mídia é declarado como application/json
.
gcloud pubsub topics publish mytopic --message='{"status": "Hello there"}' --ordering-key="some-key" --attribute "Content-Type=application/json"
As seções a seguir mostram a diferença entre uma mensagem encapsulada e não encapsulada.
Mensagem ajustada
O exemplo a seguir mostra uma mensagem padrão encapsulada do Pub/Sub. Nesse caso, o desencapsulamento de payload não está ativado.
Publicar | O endpoint de push recebe |
---|---|
data="{"status": "Hello there"}" ordering_key="some-key" attributes= { {"Content-Type", "application/json"} } |
Content-Length: 361 Content-Type: application/json User-Agent: CloudPubSub-Google Host: subscription-project.uc.r.appspot.com { "message": { "attributes": { "Content-Type": "application/json" }, "data": "eyJzdGF0dXMiOiAiSGVsbG8gdGhlcmUifQ==", // Base64 - {"status": "Hello there"} "messageId": "2070443601311540", "message_id": "2070443601311540", "publishTime": "2021-02-26T19:13:55.749Z", "publish_time": "2021-02-26T19:13:55.749Z" }, "subscription": "projects/myproject/..." } |
Mensagem desencapsulada com metadados de gravação desativados
O exemplo a seguir mostra uma mensagem não encapsulada com a opção de metadados de gravação
desativada. Nesse caso, os cabeçalhos x-goog-pubsub-*
e os atributos da mensagem
não são incluídos.
Publicar | O endpoint de push recebe |
---|---|
data="{"status": "Hello there"}" ordering_key="some-key" attributes= { {"Content-Type", "application/json"} } |
Content-Length: 25 User-Agent: CloudPubSub-Google Host: subscription-project.uc.r.appspot.com {"status": "Hello there"} |
Mensagem desencapsulada com metadados de gravação ativados
O exemplo a seguir mostra uma mensagem não encapsulada com a opção de metadados de gravação
ativada. Nesse caso, os cabeçalhos x-goog-pubsub-*
e os atributos da mensagem
são incluídos.
Publicar | O endpoint de push recebe |
---|---|
data="{"status": "Hello there"}" ordering_key="some-key" attributes= { {"Content-Type", "application/json"} } |
x-goog-pubsub-subscription-name: "projects/myproject/..." x-goog-pubsub-message-id: "2070443601311540" x-goog-pubsub-publish-time: "2021-02-26T19:13:55.749Z" x-goog-pubsub-ordering-key: "some-key" Content-Type: application/json Content-Length: 12 User-Agent: CloudPubSub-Google Host: subscription-project.uc.r.appspot.com {"status": "Hello there"} |
Configurar o desencapsulamento de payload
É possível ativar a entrega por push de desencapsulamento de payload para uma assinatura usando a página Detalhes da assinatura do console Trusted Cloud , a Google Cloud CLI ou as bibliotecas de cliente.
Console
No console Trusted Cloud , acesse a página Assinaturas.
Clique em Criar assinatura.
No campo ID da assinatura, insira um nome.
Para informações sobre como nomear uma assinatura, consulte Diretrizes para nomear um tópico ou uma assinatura.
Selecione um tópico no menu suspenso. A assinatura recebe mensagens do tópico.
Em Tipo de entrega, selecione Push.
Para ativar o desencapsulamento de payload, selecione Ativar o desencapsulamento de payload.
(Opcional) Para preservar os metadados das mensagens no cabeçalho da solicitação, selecione Gravar metadados. Você precisa ativar essa opção para definir um cabeçalho Content-Type para suas mensagens.
Especifique um URL de endpoint.
Mantenha todos os outros valores padrão.
Clique em Criar.
gcloud
Para configurar uma assinatura com desencapsulamento de payload que inclua cabeçalhos HTTP padrão, execute o seguinte comando gcloud pubsub subscriptions create
:
gcloud pubsub subscriptions create SUBSCRIPTION \ --topic TOPIC \ --push-endpoint=PUSH_ENDPOINT \ --push-no-wrapper
Substitua:
SUBSCRIPTION
: o nome ou ID da sua assinatura de extração.TOPIC
: o ID do tópico.PUSH_ENDPOINT
: o URL a ser usado como endpoint para esta assinatura. Por exemplo,https://myproject.appspot.com/myhandler
--push-no-wrapper
: entrega os dados da mensagem diretamente como o corpo HTTP.
Para configurar uma assinatura com desencapsulamento de payload e controlar o uso de
cabeçalhos x-goog-pubsub-*
, execute o seguinte comando:
gcloud pubsub subscriptions create SUBSCRIPTION \ --topic TOPIC \ --push-endpoint=PUSH_ENDPOINT \ --push-no-wrapper \ --push-no-wrapper-write-metadata
--push-no-wrapper-write-metadata
: quando verdadeiro, grava os metadados da mensagem do Pub/Sub nos cabeçalhosx-goog-pubsub-<KEY>:<VAL>
da solicitação HTTP. Grava os atributos da mensagem do Pub/Sub nos cabeçalhos<KEY>:<VAL>
da solicitação HTTP.
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.
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.
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
O exemplo a seguir usa a versão principal da biblioteca de cliente do Go Pub/Sub (v2). Se você ainda estiver usando a biblioteca v1, consulte o guia de migração para a v2. Para conferir uma lista de exemplos de código da v1, consulte os exemplos de código descontinuados.
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.
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.
Definir um cabeçalho de tipo de conteúdo na mensagem
Depois de ativar o desencapsulamento de payload, o Pub/Sub não
define automaticamente um campo de cabeçalho de tipo de mídia na sua solicitação. Se você não definir explicitamente um campo de cabeçalho Content-Type
, o servidor da Web que processa sua solicitação poderá definir um valor padrão de application/octet-stream
ou interpretar a solicitação de maneira inesperada.
Se você precisar de um cabeçalho Content-Type
, declare-o explicitamente
no momento da publicação para cada mensagem publicada. Para isso, primeiro ative a opção Gravar metadados. O resultado de ativar a opção Gravar metadados
é mostrado nos exemplos fornecidos.
A seguir
- Se você estiver com problemas para desencapsular a carga útil, consulte Resolver problemas de desencapsulamento de carga útil.