Enviar inscrições

Este documento oferece uma visão geral de uma assinatura por push, do fluxo de trabalho dela e das propriedades associadas.

Na entrega de push, o Pub/Sub inicia solicitações para o aplicativo do seu assinante enviar mensagens. As mensagens são entregues a um servidor endereçável publicamente ou a um webhook, como uma solicitação POST HTTPS.

As assinaturas de push minimizam as dependências de bibliotecas de cliente e mecanismos de autenticação específicos do Pub/Sub. Elas também funcionam bem com tecnologias de serviço sem servidor e de escalonamento automático, como as Funções do Cloud Run, o Cloud Run e o Google Kubernetes Engine.

Antes de começar

Antes de ler este documento, confira se você está familiarizado com o seguinte:

Fluxo de trabalho da assinatura por push

Em uma assinatura por push, um servidor do Pub/Sub inicia uma solicitação para o cliente assinante para entregar mensagens.

A imagem a seguir mostra o fluxo de trabalho entre um cliente assinante e uma assinatura de push.

Fluxo de mensagens para uma assinatura por push
Figura 3. Fluxo de trabalho de uma assinatura por push

Confira uma breve descrição do fluxo de trabalho que faz referência à Figura 3:

  1. O servidor do Pub/Sub envia cada mensagem como uma solicitação HTTPS para o cliente assinante em um endpoint pré-configurado. Essa solicitação é mostrada como um PushRequest na imagem.
  2. O endpoint confirma a mensagem com um código de status de sucesso HTTP. Uma resposta sem sucesso indica que o Pub/Sub precisa reenviar as mensagens. Essa resposta é mostrada como um PushResponse na imagem.
  3. O Pub/Sub ajusta dinamicamente a taxa de solicitações de push com base na frequência em que recebe respostas bem-sucedidas.

Propriedades de uma assinatura por push

As propriedades configuradas para uma assinatura por push determinam como você grava mensagens na assinatura. Para mais informações, consulte Propriedades da assinatura.

Como os endpoints de push recebem mensagens

Quando o Pub/Sub entrega uma mensagem a um endpoint de push, você pode enviá-la encapsulada ou não encapsulada. Por padrão, as mensagens são enviadas encapsuladas.

  • Encapsulada. O Pub/Sub envia a mensagem no corpo JSON de uma solicitação POST.
  • Não encapsulada. O Pub/Sub envia os dados brutos da mensagem diretamente como o corpo HTTP.

Os exemplos a seguir mostram um corpo encapsulado de uma solicitação POST JSON para um endpoint de push que contém a string Hello there no campo message.data.

O corpo de uma solicitação POST é um objeto JSON. Os dados da mensagem estão no campo message.data e são codificados em base64.

Exemplo de uma solicitação com os valores mínimos

  {
      "message": {
          "data": "SGVsbG8gQ2xvdWQgUHViL1N1YiEgSGVyZSBpcyBteSBtZXNzYWdlIQ==",
          "messageId": "2070443601311540",
          "message_id": "2070443601311540",
          "publishTime": "2021-02-26T19:13:55.749Z",
          "publish_time": "2021-02-26T19:13:55.749Z"
      },
    "subscription": "projects/myproject/subscriptions/mysubscription"
  }

Exemplo de uma solicitação com os valores máximos

Este exemplo mostra os valores máximos atuais, que podem mudar com o tempo. Além disso, o mapa de atributos pode conter uma variedade de valores.

  {
      "deliveryAttempt": 5,
      "message": {
          "attributes": {
              "key": "value"
          },
          "data": "SGVsbG8gQ2xvdWQgUHViL1N1YiEgSGVyZSBpcyBteSBtZXNzYWdlIQ==",
          "messageId": "2070443601311540",
          "message_id": "2070443601311540",
          "orderingKey": "key",
          "publishTime": "2021-02-26T19:13:55.749Z",
          "publish_time": "2021-02-26T19:13:55.749Z"
      },
    "subscription": "projects/myproject/subscriptions/mysubscription"
}

Para receber mensagens de assinaturas de push, use um webhook e processe as solicitações POST que o Pub/Sub envia para o endpoint de push. Para mais informações sobre como processar essas solicitações POST no App Engine, consulte Como gravar e responder a mensagens do Pub/Sub.

Depois de receber uma solicitação por push, retorne um código de status HTTP. Para confirmar a mensagem, retorne um dos seguintes códigos de status:

  • 102
  • 200
  • 201
  • 202
  • 204

Para enviar uma confirmação negativa para a mensagem, retorne qualquer outro código de status. Se você enviar uma confirmação negativa ou o prazo de confirmação expirar, o Pub/Sub reenviará a mensagem. Não é possível modificar o prazo de confirmação de mensagens individuais recebidas de assinaturas de push.

Autenticação para assinaturas de push

Se uma assinatura por push usa a autenticação, o serviço Pub/Sub assina um JWT e o envia no cabeçalho de autorização da solicitação de push.

Para mais informações sobre como configurar a autenticação, consulte Autenticar solicitações de push.

Parar e retomar a entrega de mensagens

Para interromper temporariamente o envio de solicitações do Pub/Sub para o endpoint de push, altere a assinatura para pull. A mudança pode levar vários minutos para entrar em vigor.

Para retomar a entrega por push, defina o URL para um endpoint válido novamente. Caso queira interromper a entrega permanentemente, exclua a assinatura.

Espera de push

Se um assinante de push enviar muitas confirmações negativas, o Pub/Sub poderá começar a entregar mensagens usando uma espera de push. Quando o Pub/Sub usa uma espera de push, ele interrompe a entrega de mensagens por um período predeterminado. Esse período pode variar de 100 milissegundos a 60 segundos. Após o tempo decorrido, o Pub/Sub começa a entregar mensagens novamente.

A espera exponencial de push usa um algoritmo de espera exponencial para determinar o atraso que o Pub/Sub usa entre o envio de mensagens. Esse período é calculado com base no número de confirmações negativas enviadas pelos assinantes de push.

Por exemplo, se um assinante de push receber cinco mensagens por segundo e enviar uma confirmação negativa por segundo, o Pub/Sub entregará mensagens aproximadamente a cada 500 milissegundos. Ou, se o assinante de push enviar cinco confirmações negativas por segundo, o Pub/Sub entregará mensagens a cada 30 a 60 segundos.

Observe as seguintes considerações sobre a espera de push:

  • A espera de push não pode ser ativada ou desativada. Também não é possível modificar os valores usados para calcular o atraso.
  • A espera de push é acionada nas seguintes ações:
    • Quando uma confirmação negativa é recebida.
    • Quando o prazo de confirmação de uma mensagem expira.
  • A espera de push se aplica a todas as mensagens em uma assinatura (global).

Taxa de envio

O Pub/Sub ajusta o número de solicitações push simultâneas usando um algoritmo de inicialização lenta. O número máximo permitido de solicitações push simultâneas é a janela push. A janela push aumenta em qualquer entrega bem-sucedida e diminui em caso de falha. O sistema começa com um tamanho de janela pequeno de um único dígito.

Quando um assinante reconhece as mensagens, a janela aumenta exponencialmente. Para assinaturas em que os assinantes confirmam mais de 99% das mensagens e conseguem, em média, menos de um segundo de latência da solicitação de push, a janela push precisa ser expandida o suficiente para acompanhar qualquer capacidade de processamento de publicação.

A latência da solicitação de push inclui o seguinte:

Depois de 3.000 mensagens pendentes por região, a janela aumenta linearmente para evitar que o endpoint de push receba muitas mensagens. Se a latência média exceder um segundo ou o assinante confirmar menos de 99% das solicitações, a janela diminuirá para o limite mínimo de 3.000 mensagens pendentes.

Para mais informações sobre as métricas que podem ser usadas para monitorar a entrega por push, consulte Como monitorar assinaturas de push.

Cotas e limites

As assinaturas de push estão sujeitas a um conjunto de cotas e limites de recursos.

A seguir