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.