Enviar inscrições

Este documento apresenta uma visão geral de uma assinatura push, o fluxo de trabalho dela e as propriedades associadas.

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

As assinaturas push minimizam as dependências de bibliotecas de cliente específicas do Pub/Sub e mecanismos de autenticação. Elas também funcionam bem com tecnologias de serviço sem servidor e de dimensionamento 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ê conhece os seguintes tópicos:

Fluxo de trabalho da assinatura de push

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

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

Fluxo de mensagens para uma assinatura de push
Figura 3. Fluxo de trabalho para uma inscrição de 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 do 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 de push determinam como você grava mensagens na assinatura. Para mais informações, consulte Propriedades da assinatura.

Como os endpoints push recebem mensagens

Quando o Pub/Sub entrega uma mensagem para um endpoint de push, é possível enviar a mensagem embrulhada ou desembrulhada. Por padrão, as mensagens são enviadas em grupo.

  • Concluído. O Pub/Sub envia a mensagem no corpo JSON de uma solicitação POST.
  • Desencapsulado. 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 JSON POST 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 vários 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 push

Se uma assinatura de 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.

Interromper 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 enviar 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 de tempo. Esse período pode variar de 100 milissegundos a 60 segundos. Após esse período, o Pub/Sub começa a entregar mensagens novamente.

A espera 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.

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 vai enviar mensagens a cada 30 a 60 segundos.

Observe as seguintes considerações sobre o push backoff:

  • O push backoff não pode ser ativado ou desativado. Também não é possível modificar os valores usados para calcular o atraso.
  • Acione os gatilhos de desistência nas seguintes ações:
    • Quando uma confirmação negativa é recebida.
    • Quando o prazo de confirmação de uma mensagem expira.
  • O push backoff se aplica a todas as mensagens de 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 dígito.

Quando um assinante confirma as mensagens, a janela aumenta exponencialmente. Para assinaturas em que os assinantes confirmam mais de 99% das mensagens e têm uma latência média de push de menos de um segundo, a janela de push precisa ser expandida o suficiente para acompanhar o volume 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 vai 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