Ao criar seu sistema do Pub/Sub, o desempacotamento de payload pode ajudar a se conectar a outros sistemas que não aderem a todos os requisitos de um endpoint de push padrão do Pub/Sub.
Confira alguns casos de uso possíveis para descompactação de payloads:
- Você não quer escrever um código de análise de mensagens específico do Pub/Sub para os endpoints de push HTTP.
- Você prefere receber metadados de mensagens do Pub/Sub como cabeçalhos HTTP em vez dos metadados no corpo do POST HTTP.
- Você quer enviar mensagens do Pub/Sub e excluir os metadados do Pub/Sub, 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 brutos os assinantes podem processar a mensagem sem precisar seguir as os requisitos do sistema do Pub/Sub.
- Com a abertura de payload, os dados da mensagem são entregues diretamente como o corpo HTTP.
- Sem o desencapsulamento de payload, o Pub/Sub envia 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 extrair os dados da mensagem e, em seguida, decodificado em base64.
Gravar metadados
Depois de ativar o desencapsulamento de payload, use a opção write metadata, que adiciona metadados de mensagens removidos anteriormente ao cabeçalho da solicitação.
- Metadados de gravação ativados. Adicione os metadados da mensagem de volta ao cabeçalho da solicitação. Também entrega os dados brutos e decodificados da mensagem.
- Gravar metadados desativado. Mostra apenas os dados brutos e decodificados da mensagem.
Os metadados de gravação são expostos por meio do Pub/Sub, a Google Cloud CLI
argumento --push-no-wrapper-write-metadata
e a propriedade de API NoWrapper
.
Por padrão, esse valor é nulo.
Antes de começar
- Saiba mais sobre as assinaturas do Pub/Sub e assinaturas push. O desencapsulamento de payload só pode ser usado com assinaturas de push.
- Saiba como configurar uma assinatura push.
Exemplo de mensagens com e sem wrapper
Os exemplos a seguir ilustram a diferença entre o envio de uma
uma mensagem HTTP encapsulada ou não. Nestes exemplos, os dados da mensagem contêm
a string {"status": "Hello there"}
.
Para este exemplo, uma assinatura é criada com o desencapsulamento do payload
recurso ativado e publica uma mensagem no mytopic
. Ele usa uma função
chave com um valor de 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 com e sem embalagem.
Mensagem ajustada
O exemplo a seguir mostra uma mensagem encapsulada do Pub/Sub padrão. Nesse caso, a abertura do payload não está ativada.
Publicar | Recebimentos do endpoint de push |
---|---|
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 descompactada com a opção de gravação de metadados
desativada. Nesse caso, os cabeçalhos x-goog-pubsub-*
e os atributos da mensagem
não estão incluídas.
Publicar | Recebimentos do endpoint de push |
---|---|
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 descompactada com metadados de gravação ativados
O exemplo a seguir mostra uma mensagem desencapsulada com a opção de metadados de gravação
ativado. Nesse caso, os cabeçalhos x-goog-pubsub-*
e os atributos da mensagem
estão incluídas.
Publicar | Recebimentos de endpoint de push |
---|---|
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 do Google Cloud, a Google Cloud CLI ou as bibliotecas de cliente.
Console
No console do Google Cloud, acesse a página Assinaturas.
Clique em Criar assinatura.
No campo ID da assinatura, digite um nome.
Para saber como nomear uma assinatura, consulte as 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 desencapsulamento de payload.
(Opcional) Para preservar os metadados das mensagens no cabeçalho da solicitação, selecione Gravar metadados. Você precisa ativar esta 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, execute o seguinte gcloud pubsub subscriptions create
comando:
gcloud pubsub subscriptions create SUBSCRIPTION \ --topic TOPIC \ --push-endpoint=PUSH_ENDPOINT \ --push-no-wrapper
Substitua:
SUBSCRIPTION
: o nome ou o ID da assinatura de pull.TOPIC
: o ID do tópico.PUSH_ENDPOINT
: o URL a ser usado como endpoint dessa 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
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 o Metadados da mensagem do Pub/Sub parax-goog-pubsub-<KEY>:<VAL>
cabeçalhos da solicitação HTTP. escreve a mensagem do Pub/Sub atributos aos 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
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.
Defina um cabeçalho "content-type" na mensagem
Depois de ativar o desempacotamento de payload, o Pub/Sub não
define automaticamente um campo de cabeçalho de tipo de mídia na solicitação. Se você
não definir explicitamente um campo de cabeçalho Content-Type
, o servidor da Web
processando sua solicitação pode definir um valor padrão de
application/octet-stream
ou interpretar a solicitação
de maneira inesperada.
Se você precisa de um cabeçalho Content-Type
, declare-o explicitamente
no momento da publicação para cada mensagem publicada. Para fazer isso, você deve
Ative a opção Metadados de gravação. Esse resultado da ativação da opção Metadados de gravação
é mostrado nos exemplos fornecidos.
A seguir
- Se você tiver problemas com o desempacotamento do payload, consulte Resolver problemas de desempacotamento do payload.