Notificações push

Visão geral

A API Gmail fornece notificações push do servidor que permitem monitorar mudanças nas caixas de e-mails do Gmail. Você pode usar esse recurso para melhorar o desempenho do seu aplicativo. Isso permite eliminar os custos extras de rede e computação envolvidos na sondagem de recursos para determinar se eles mudaram. Sempre que uma caixa de e-mails muda, a API Gmail notifica o aplicativo do servidor de back-end.

Configuração inicial do Cloud Pub/Sub

A API Gmail usa a API Cloud Pub/Sub para enviar notificações push. Isso permite a notificação por vários métodos, incluindo webhooks e sondagem em um único endpoint de assinatura.

Pré-requisitos

Para concluir o restante desta configuração, verifique se você atende aos pré-requisitos do Cloud Pub/Sub e configure um cliente do Cloud Pub/Sub.

Criar um tópico

Usando seu cliente do Cloud Pub/Sub, crie o tópico para que a API Gmail envie notificações. O nome do tópico pode ser qualquer nome que você escolher no seu projeto (por exemplo, projects/myproject/topics/*, em que myproject é o ID do projeto listado para seu projeto no Google Developers Console).

Crie uma assinatura

Siga o Guia de assinantes do Cloud Pub/Sub para configurar uma assinatura do tópico que você criou. Configure o tipo de assinatura para ser um push de webhook (ou seja, um callback HTTP POST) ou pull (ou seja, iniciado pelo seu app). É assim que seu aplicativo vai receber notificações de atualizações.

Conceder direitos de publicação no tópico

O Cloud Pub/Sub exige que você conceda privilégios ao Gmail para publicar notificações no seu tópico.

Para isso, conceda privilégios de publish a gmail-api-push@system.gserviceaccount.com. Para isso, use a interface de permissões do console de desenvolvedores do Cloud Pub/Sub seguindo as instruções de controle de acesso no nível do recurso.

Receber atualizações da caixa de e-mails do Gmail

Depois que a configuração inicial do Cloud Pub/Sub for concluída, configure as contas do Gmail para enviar notificações sobre atualizações da caixa de e-mail.

Pedido de assistir

Para configurar contas do Gmail para enviar notificações ao seu tópico do Cloud Pub/Sub, basta usar o cliente da API Gmail para chamar watch na caixa de e-mails do usuário do Gmail, assim como qualquer outra chamada da API Gmail. Para fazer isso, forneça o nome do tópico criado acima e outras opções na solicitação watch, como labels para filtrar. Por exemplo, para receber uma notificação sempre que uma mudança for feita na Caixa de entrada:

Protocolo

POST "https://www.googleapis.com/gmail/v1/users/me/watch"
Content-type: application/json

{
  topicName: "projects/myproject/topics/mytopic",
  labelIds: ["INBOX"],
  labelFilterBehavior: "INCLUDE",
}

Python

request = {
  'labelIds': ['INBOX'],
  'topicName': 'projects/myproject/topics/mytopic',
  'labelFilterBehavior': 'INCLUDE'
}
gmail.users().watch(userId='me', body=request).execute()

Assistir resposta

Se a solicitação watch for bem-sucedida, você vai receber uma resposta como esta:

{
  historyId: 1234567890
  expiration: 1431990098200
}

com a caixa de correio atual historyId do usuário. Todas as mudanças feitas depois dessa data historyId serão notificadas ao cliente. Se você precisar processar mudanças antes desse historyId, consulte o guia de sincronização.

Além disso, uma chamada watch bem-sucedida deve fazer com que uma notificação seja enviada imediatamente ao seu tópico do Cloud Pub/Sub.

Se você receber um erro da chamada watch, os detalhes vão explicar a origem do problema, que geralmente está na configuração do tópico e da assinatura do Cloud Pub/Sub. Consulte a documentação do Cloud Pub/Sub para confirmar se a configuração está correta e receber ajuda para depurar problemas de tópicos e assinaturas.

Renovar o acompanhamento da caixa de e-mails

É necessário chamar watch pelo menos a cada 7 dias. Caso contrário, você vai parar de receber atualizações para o usuário. Recomendamos chamar watch uma vez por dia. A resposta watch também tem um campo de expiração com o carimbo de data/hora da expiração watch.

Como receber notificações

Sempre que houver uma atualização na caixa de correio que corresponda ao seu watch, o aplicativo vai receber uma mensagem de notificação descrevendo a mudança.

Se você tiver configurado uma assinatura por push, uma notificação de webhook para seu servidor vai obedecer a um PubsubMessage:

POST https://yourserver.example.com/yourUrl
Content-type: application/json

{
  message:
  {
    // This is the actual notification data, as base64url-encoded JSON.
    data: "eyJlbWFpbEFkZHJlc3MiOiAidXNlckBleGFtcGxlLmNvbSIsICJoaXN0b3J5SWQiOiAiMTIzNDU2Nzg5MCJ9",

    // This is a Cloud Pub/Sub message id, unrelated to Gmail messages.
    "messageId": "2070443601311540",

    // This is the publish time of the message.
    "publishTime": "2021-02-26T19:13:55.749Z",
  }

  subscription: "projects/myproject/subscriptions/mysubscription"
}

O corpo HTTP POST é JSON, e o payload real da notificação do Gmail está no campo message.data. O campo message.data é uma string codificada em base64url que é decodificada em um objeto JSON contendo o endereço de e-mail e o novo ID do histórico da caixa de correio do usuário:

{"emailAddress": "user@example.com", "historyId": "9876543210"}

Em seguida, use history.list para receber os detalhes da mudança do usuário desde o último historyId conhecido , conforme o guia de sincronização.

Por exemplo, para usar history.list e identificar mudanças que ocorreram entre a chamada inicial de watch e o recebimento da mensagem de notificação compartilhada no exemplo anterior, transmita 1234567890 como startHistoryId para history.list. Depois,9876543210 pode ser mantido como o historyId conhecido mais recente para casos de uso futuros.

Se você tiver configurado uma assinatura de extração, consulte os exemplos de código no Guia de extração do assinante do Cloud Pub/Sub para mais detalhes sobre como receber mensagens.

Responder a notificações

Todas as notificações precisam ser confirmadas. Se você usar o envio por push de webhook, responder com sucesso (por exemplo, HTTP 200) vai confirmar o recebimento da notificação.

Se você estiver usando a entrega por pull (REST Pull, RPC Pull ou RPC StreamingPull), faça uma chamada de confirmação (REST ou RPC). Consulte as amostras de código no Guia de pull do assinante do Cloud Pub/Sub para mais detalhes sobre como confirmar o recebimento de mensagens de forma assíncrona ou síncrona usando as bibliotecas de cliente oficiais baseadas em RPC.

Se as notificações não forem confirmadas (por exemplo, se o callback do webhook retornar um erro ou atingir o tempo limite), o Cloud Pub/Sub vai tentar de novo mais tarde.

Como interromper as atualizações da caixa de correio

Para parar de receber atualizações em uma caixa de correio, chame stop e todas as novas notificações serão interrompidas em alguns minutos.

Limitações

Taxa máxima de notificação

Cada usuário do Gmail monitorado tem uma taxa máxima de notificação de um evento por segundo. Todas as notificações acima dessa taxa serão descartadas. Tenha cuidado ao processar notificações para não acionar outra e, assim, iniciar um loop de notificações.

Confiabilidade

Normalmente, todas as notificações são entregues de forma confiável em alguns segundos. No entanto, em algumas situações extremas, elas podem ser atrasadas ou descartadas. Lide com essa possibilidade de maneira adequada para que o aplicativo ainda seja sincronizado mesmo que nenhuma mensagem push seja recebida. Por exemplo, volte a chamar periodicamente history.list depois de um período sem notificações para um usuário.

Limitações do Cloud Pub/Sub

A API Cloud Pub/Sub também tem limitações próprias, detalhadas na documentação de preços e cotas.