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:

Acesse o Console do Google Cloud Platform.
Selecione seu projeto.
Abra a barra lateral de navegação no canto superior esquerdo, selecione APIs e serviços e depois Credenciais.
Selecione Verificação de domínio.
Selecione Adicionar domínio.
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:

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies. Java is a registered trademark of Oracle and/or its affiliates.