Notificações Push

Informações gerais

A API Gmail fornece notificações push do servidor que permitem que você monitore alterações nas caixas de e-mails do Gmail. Use esse recurso para melhorar o desempenho do aplicativo. Isso permite eliminar a rede extra e os custos de computação envolvidos com os recursos de pesquisa para determinar se eles mudaram. Sempre que uma caixa de e-mails é alterada, 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 entregar notificações push. Isso permite a notificação por meio de vários métodos, incluindo webhooks e pesquisas 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, em seguida, configure um cliente do Cloud Pub/Sub.

Crie um tópico

Usando seu cliente do Cloud Pub/Sub, crie o tópico para o qual a API Gmail deve enviar notificações. O nome do tópico pode ser qualquer nome que você escolher no projeto (ou seja, projects/myproject/topics/* correspondente, em que myproject é o ID do projeto listado para seu 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 quanto ao número de tópicos.

Crie uma assinatura

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

Conceder direitos de publicação no tópico

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

Para fazer isso, conceda privilégios de publish para gmail-api-push@system.gserviceaccount.com. Isso pode ser feito usando a interface de permissões do Play Console do Cloud Pub/Sub seguindo as instruções de controle de acesso no nível do recurso.

Receber atualizações na 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 de atualizações da caixa de e-mails.

Solicitação para assistir

Para configurar contas do Gmail para enviar notificações ao 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, da mesma forma que em qualquer outra chamada da API Gmail. Para fazer isso, forneça o nome do tópico criado acima e quaisquer outras opções na solicitação watch, como labels para filtrar. Por exemplo, para ser notificado sempre que uma alteração 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:

{
  historyId: 1234567890
  expiration: 1431990098200
}

com a caixa de e-mails atual historyId para o usuário. Todas as mudanças depois disso historyId vão ser notificadas ao seu cliente. Se você precisar processar mudanças antes dessa historyId, consulte o guia de sincronização.

Além disso, uma chamada watch bem-sucedida faz 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 precisarão explicar a origem do problema, que normalmente 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 com a depuração de problemas de tópicos e assinaturas.

Renovação do relógio da caixa de e-mails

É necessário chamar o watch novamente pelo menos a cada sete dias. Caso contrário, você deixará 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 de watch.

Como receber notificações

Sempre que ocorrer uma atualização de caixa de e-mails que corresponda à watch, seu aplicativo receberá uma mensagem de notificação descrevendo a mudança.

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

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

Em seguida, você pode usar history.list para conferir os detalhes da mudança do usuário desde o último histórico conhecido de acordo com 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

Você precisa confirmar todas as notificações. Se você usar a entrega por push do webhook, a resposta será bem-sucedida (por exemplo, HTTP 200) e confirmará a notificação.

Se estiver usando entrega de pull (REST Pull, RPC Pull ou RPC StreamingPull), você precisa fazer o acompanhamento com uma chamada de confirmação (REST ou RPC). Consulte as amostras de código no Guia de extração do assinante do Cloud Pub/Sub para mais detalhes sobre como confirmar mensagens de maneira 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 tentará novamente.

Como interromper atualizações da caixa de e-mails

Para deixar de receber atualizações em uma caixa de e-mails, chame stop. Todas as novas notificações deverão ser interrompidas em alguns minutos.

Limitações

Taxa máxima de notificações

Cada usuário do Gmail em observação tem uma taxa máxima de notificações 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 notificação e, assim, iniciar um loop de notificações.

Confiabilidade

Normalmente, todas as notificações precisam ser entregues de maneira confiável em alguns segundos. No entanto, em algumas situações extremas, elas podem ser atrasadas ou descartadas. Lide com essa possibilidade da maneira correta para que o aplicativo ainda seja sincronizado mesmo que nenhuma mensagem de push seja recebida. Por exemplo, volte a chamar history.list periodicamente 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 as próprias limitações, especificamente detalhadas na documentação de pricing e quotas.