Notificações Push

Visão geral

A API Gmail oferece 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 aplicativo. Ele permite eliminar os custos extras de rede e computação envolvidos na pesquisa de recursos para determinar se eles mudaram. Sempre que uma caixa de e-mails muda, a API Gmail notifica seu aplicativo de servidor de back-end.

Observação:para notificações em dispositivos do usuário (ou seja, apps instalados, dispositivos móveis ou navegadores), o guia de sincronização baseado em pesquisa ainda é a abordagem recomendada para recuperar as atualizações.

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 pesquisa em um único endpoint de assinatura.

Pré-requisitos

Para concluir o restante da configuração, siga os 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 o qual a API Gmail vai enviar notificações. O nome do tópico pode ser qualquer nome escolhido no projeto (por exemplo, projects/myproject/topics/*, em que myproject é o ID do projeto listado para o projeto no Google Developers Console).

Recomendamos que você use um único tópico para todas as notificações push da API Gmail no seu aplicativo devido aos limites do Cloud Pub/Sub no número de tópicos.

Crie uma assinatura

Siga o Guia do assinante 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 fazer isso, conceda privilégios publish a [e-mail]. Para fazer isso, use a interface de permissões do console do desenvolvedor do Cloud Pub/Sub seguindo as instruções de controle de acesso no nível do recurso.

Como receber atualizações da caixa de entrada do Gmail

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

Solicitação de exibição

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, semelhante a 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 notificações 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ê receberá uma resposta como esta:

{
  historyId: 1234567890
  expiration: 1431990098200
}

com a caixa de e-mails historyId atual do usuário. Todas as mudanças após historyId serão notificadas ao seu cliente. Se você precisar processar mudanças antes desta 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 para receber ajuda com problemas de depuração de tópicos e assinaturas.

Como renovar a verificação da caixa de e-mails

Você precisa chamar watch pelo menos a cada sete dias. Caso contrário, você vai parar de receber atualizações do 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 para a expiração da watch.

Como receber notificações

Sempre que uma atualização de caixa de correio correspondente ao watch ocorrer, o app vai receber uma mensagem de notificação descrevendo a mudança.

Se você tiver configurado uma assinatura push, uma notificação de webhook para seu servidor vai se conformar 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 do POST HTTP é JSON, e o payload da notificação do Gmail está no campo message.data. Esse campo message.data é uma string codificada em base64url que é decodificada para um objeto JSON contendo o endereço de e-mail e o novo ID do histórico de caixa de correio do usuário:

{"emailAddress": "[e-mail]", "historyId": "9876543210"}

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

Se você tiver configurado uma assinatura de pull, consulte os exemplos de código no guia de pull do assinante do Cloud Pub/Sub para mais detalhes sobre o recebimento de mensagens.

Como responder a notificações

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

Se você estiver usando a entrega por pull (REST Pull, RPC Pull ou RPC StreamingPull), é necessário fazer uma chamada de confirmação (REST ou RPC). Consulte os exemplos de código no guia de pull do assinante do Cloud Pub/Sub para mais detalhes sobre como confirmar 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 expirar), o Cloud Pub/Sub vai tentar novamente mais tarde.

Como interromper as atualizações da caixa de correio

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

Limitações

Taxa máxima de notificação

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

Confiabilidade

Normalmente, todas as notificações são enviadas de forma confiável em alguns segundos. No entanto, em algumas situações extremas, as notificações podem ser atrasadas ou descartadas. Processe essa possibilidade corretamente para que o app continue sincronizado mesmo que nenhuma mensagem push seja recebida. Por exemplo, volte a chamar periodicamente history.list após 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, detalhadas na documentação de preços e cotas.