Enviar inscrições

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

Na entrega de push, o Pub/Sub inicia solicitações ao aplicativo do assinante para entregar 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 em 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 Cloud Functions, Cloud Run e Google Kubernetes Engine.

Antes de começar

Antes de ler este documento, certifique-se de que você esteja familiarizado com o seguinte:

Fluxo de trabalho da assinatura de push

Em uma assinatura de push, um servidor Pub/Sub inicia uma solicitação ao 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 de push
Figura 3. Fluxo de trabalho para uma assinatura push

Aqui está uma breve descrição do fluxo de trabalho que referencia a Figura 3:

  1. O servidor do Pub/Sub envia cada mensagem como uma solicitação HTTPS ao 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 de falha 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 de push

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

Como os endpoints de push recebem as mensagens

Quando o Pub/Sub entrega uma mensagem a um endpoint de push, é possível enviá-la encapsulada ou desencapsulada. Por padrão, as mensagens são encapsuladas.

  • Resumo. 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 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 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 push

Se uma assinatura de push usar autenticação, o serviço Pub/Sub assinará um JWT e o enviará 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 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 push enviar muitas confirmações negativas, o Pub/Sub poderá começar a entregar mensagens usando uma espera push. Quando o Pub/Sub usa uma espera push, ele para de entregar mensagens por um período predeterminado. Esse período pode variar de 100 milissegundos a 60 segundos. Depois desse tempo, o Pub/Sub começa a entregar as mensagens novamente.

A espera por push usa um algoritmo de espera exponencial (em inglês) para determinar o atraso que o Pub/Sub usa entre o envio de mensagens. Esse tempo é 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 entrega mensagens a cada 30 a 60 segundos.

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

  • Não é possível ativar ou desativar a retirada de retorno nem modificar os valores usados para calcular o atraso.
  • Enviar acionadores de espera para as seguintes ações:
    • Quando uma confirmação negativa é recebida.
    • Quando o prazo de confirmação de uma mensagem expira.
  • A retirada push se aplica a todas as mensagens em uma assinatura (global).

Taxa de envio

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

Quando um assinante confirma mensagens, a janela aumenta exponencialmente. Para assinaturas em que os assinantes reconhecem mais de 99% das mensagens e, em média, menos de um segundo de latência de solicitação de push, a janela de push precisa se expandir o suficiente para acompanhar qualquer capacidade de publicação.

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

Após 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 inferior 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 quotas e limites de recursos.

A seguir

  • Crie uma assinatura de push para seu tópico.

  • Crie ou modifique uma assinatura com a CLI gcloud.

  • Crie ou modifique uma assinatura com APIs REST.

  • Crie ou modifique uma assinatura com APIs RPC.