Como receber mensagens usando push

O Cloud Pub/Sub é compatível com entrega de mensagens por push e pull. Para uma visão geral e comparação das assinaturas de pull e de push, consulte a Visão geral do assinante. Este documento descreve a entrega por push. Para ver uma discussão da entrega por pull, consulte o guia do assinante de pull.

Como receber mensagens por push

O servidor do Cloud Pub/Sub envia qualquer mensagem relacionada à sua assinatura ao endereço do webhook configurado. Seu aplicativo de webhook precisa lidar com as mensagens recebidas e retornar um código de status HTTP para indicar o sucesso. Qualquer um dos seguintes códigos de status HTTP é interpretado como bem-sucedido pelo sistema do Cloud Pub/Sub: 200, 201, 202, 204 ou 102. Se o serviço retornar algum outro código, o Cloud Pub/Sub tenta executar a entrega novamente por sete dias (o período padrão de retenção de mensagens). Nesse ponto, a mensagem é excluída.

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

Uma mensagem pendente é aquela que foi entregue ao endpoint de push, mas ainda não foi confirmada.

Para determinar a taxa de entrega ideal para seu sistema (minimizando a possibilidade de sobrecarregá-lo no início), o Cloud Pub/Sub usa um algoritmo de inicialização lenta.

  • O sistema começa enviando uma única mensagem por vez.
  • A cada entrega bem-sucedida, o número de mensagens enviadas simultaneamente é duplicado.
  • A taxa de entrega de mensagens simultâneas pelo sistema continua a duplicar até que ocorra uma falha na entrega ou o sistema atinja um limite de recurso ou cota.
  • O número de solicitações simultâneas ao endpoint será reduzido pela metade a cada falha na entrega, até que o mínimo de uma solicitação por vez seja atingido.

Observe que esse algoritmo pressupõe a existência de mensagens publicadas suficientes na fila para manter essa taxa de transferência. Em última análise, a taxa de envio está intimamente relacionada à taxa de publicação.

O código específico do seu gerenciador depende do seu ambiente. Veja abaixo um exemplo de protocolo para o recebimento de mensagens de push. O campo message.data é codificado em base64.

Solicitação:

POST https://www.example.com/my-push-endpoint
{
  "message": {
    "attributes": {
      "key": "value"
    },
    "data": "SGVsbG8gQ2xvdWQgUHViL1N1YiEgSGVyZSBpcyBteSBtZXNzYWdlIQ==",
    "messageId": "136969346945"
  },
  "subscription": "projects/myproject/subscriptions/mysubscription"
}

Resposta:

204 No Content

Uma resposta com código de status 204 é considerada uma confirmação implícita.

Para ver exemplos completos que podem ser criados e executados em ambientes flexíveis do App Engine, consulte Como gravar e responder mensagens do Cloud Pub/Sub para Python, Node.js, Go, Ruby, PHP e Java.

Como parar e continuar a entrega

Para interromper o envio de solicitações do Cloud Pub/Sub ao endpoint de push, altere a assinatura para um tipo de pull. As mensagens serão acumuladas, mas não serão entregues. Observe que pode levar vários minutos para que essa mudança entre em vigor.

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

Prazo para a confirmação da mensagem

Configure um prazo de confirmação padrão para assinaturas de push. No entanto, ao contrário das assinaturas de pull, o prazo não pode ser estendido para mensagens individuais. O prazo é efetivamente o tempo que o endpoint tem para responder à solicitação de push.

Configurar endpoints HTTP

Para receber mensagens por push, você precisa de um servidor HTTPS acessível publicamente para lidar com solicitações POST. O servidor precisa apresentar um certificado SSL válido assinado por uma autoridade de certificação e roteável por DNS. Você também precisa validar que o domínio é seu (ou que você tem acesso equivalente ao de proprietário ao endpoint). Por fim, você precisa registrar o domínio do endpoint no projeto do GCP. Observe que essas etapas são consideravelmente simplificadas no App Engine, em que os certificados SSL são fornecidos e é possível flexibilizar os requisitos de verificação.

Você também pode proteger mensagens com um token secreto. Consulte Como gravar e responder a mensagens do Cloud Pub/Sub para ver exemplos do App Engine.

Endpoints padrão do App Engine

A maneira mais fácil de começar a usar endpoints de push é com um aplicativo do App Engine hospedado no domínio appspot.com. Caso o aplicativo esteja no mesmo projeto do GCP que a assinatura, não é necessário verificar o domínio. Caso contrário, você precisa verificar e registrar seu domínio (veja abaixo). Recomendamos manter o assinante e o endpoint de push no mesmo projeto sempre que possível. Por exemplo, se você for um editor que quiser enviar mensagens a vários assinantes em diferentes projetos, crie as assinaturas nos mesmos projetos que os endpoints de push.

Veja algumas dicas adicionais para trabalhar com os endpoints do App Engine:

  • Use o prefixo /_ah/push-handlers/ para o caminho de URL do endpoint de push.

    Por exemplo: myapp.appspot.com/_ah/push-handlers/myhandler. Isso permite que o endpoint receba mensagens de push do Cloud Pub/Sub, o que é realizado pelo prefixo /_ah/push-handlers/.

    Não é obrigatório usar o prefixo /_ah/push-handlers/. Mas se você usar algum outro prefixo, precisará configurá-lo para permitir solicitações não autenticadas (não conectadas) e para serem alcançáveis por meio de uma ferramenta como cURL.

  • Solicite o login de administrador para proteger os URLs /_ah/push-handlers/.*.

    Isso evita acesso não autorizado ao endpoint do URL. Para isso, é necessário adicionar a opção login: admin ao app.yaml, como neste exemplo do Python, ou um <security-constraint>, como neste exemplo do Java.

Fazer registro dos endpoints

As etapas a seguir são obrigatórias para endpoints que não forem do App Engine, bem como para endpoints do App Engine que não estejam registrados no mesmo projeto do Cloud que o assinante. Para evitar o tráfego de mensagens de push indesejadas, você precisa estabelecer a propriedade do domínio. Primeiro, você precisa provar que tem acesso administrativo ao domínio. Depois, você precisa permitir que o projeto do GCP gere tráfego para o domínio.

Etapa 1: verifique se você tem acesso ao domínio

Realize o processo de verificação do site com o Search Console. Registre a versão https:// do URL do seu site. Para ver mais detalhes, consulte a documentação de ajuda com a verificação de sites.

Etapa 2: registre seu domínio em APIs e serviços

Além de provar que você tem acesso ao domínio (ou ao URL do endpoint) como usuário, você também precisa permitir que o projeto do GCP que contém a assinatura acesse esse domínio. Esta etapa não funcionará até que você conclua a Etapa 1. Depois de verificar o acesso ao domínio, registre-o no seu projeto:

  1. Acesse o Console do Google Cloud Platform.
  2. Selecione seu projeto.
  3. Abra a barra lateral de navegação no canto superior esquerdo, selecione APIs e serviços e depois Credenciais.
  4. Selecione Verificação de domínio.
  5. Selecione Adicionar domínio.
  6. Preencha o formulário e clique em Adicionar domínio.

Nesse momento, o Console do Google Cloud Platform verifica seu domínio em relação aos que você verificou no Search Console. Assumindo que você verificou corretamente o domínio, a página é atualizada para mostrar sua nova lista de domínios permitidos.

Use agora qualquer um desses domínios para receber mensagens de push. Para fazer isso, é necessário configurá-los como endpoints ao criar uma assinatura do Cloud Pub/Sub. Consulte Como configurar inscrições para ver mais detalhes.

A seguir

Para ver exemplos completos que podem ser criados e executados no ambiente flexível do App Engine, consulte os tutoriais do Cloud Pub/Sub.

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…