Configurar notificações push na API Gmail

Este documento explica como gerenciar notificações push na API Gmail.

A API Gmail fornece notificações push de servidor que permitem monitorar mudanças nas caixas de e-mails do Gmail. Use esse recurso para melhorar a performance do aplicativo. Ele elimina os custos extras de rede e computação de recursos de pesquisa 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 entregar notificações push. Isso permite notificações usando vários métodos, incluindo webhooks e pesquisas em um único endpoint de assinatura.

Pré-requisitos

Para concluir essa configuração, atenda aos pré-requisitos do Cloud Pub/Sub e, em seguida, configure um cliente do Cloud Pub/Sub.

Criar um tópico

Usando o 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 seu projeto (por exemplo, correspondente a projects/myproject/topics/*, em que myproject é o ID do projeto listado para seu projeto no console do Google Cloud).

Crie uma assinatura

Para configurar uma assinatura para o tópico criado, siga o guia de tipo de assinatura do Cloud Pub/Sub . Configure o tipo de assinatura para ser um push de webhook (ou seja, um callback HTTP POST) ou um pull (ou seja, iniciado pelo seu app). É assim que o aplicativo recebe notificações de atualizações.

Conceder direitos de publicação no tópico

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

Para fazer isso, conceda permissões publish a gmail-api-push@system.gserviceaccount.com. Você pode fazer isso usando o Cloud Pub/Sub permissions console no console do Google Cloud seguindo estas controle de acesso instructions.

A configuração de compartilhamento restrito do domínio da sua organização pode impedir que você conceda permissões de publicação. Para resolver isso, você pode configurar uma exceção para essa conta de serviço.

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

Solicitação de observação

Para configurar contas do Gmail para enviar notificações ao tópico do Cloud Pub/Sub, use o cliente da API Gmail para chamar o watch método na caixa de e-mails do usuário do Gmail. Isso é semelhante a qualquer outra chamada de API do Gmail. Forneça o nome do tópico criado e outras opções na solicitação watch, como labels para filtrar. Por exemplo, use a solicitação a seguir para ser notificado sempre que uma mudança for feita na caixa de entrada:

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

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

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

Resposta de observação

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

{ historyId: 1234567890 expiration: 1431990098200 }

A resposta contém o historyId atual da caixa de e-mails do usuário. O cliente recebe notificações de todas as mudanças após esse historyId. Se você precisar processar mudanças anteriores a esse historyId, consulte Sincronizar clientes com a API Gmail.

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

Se você receber um erro da chamada watch, os detalhes vão explicar a origem do problema. Normalmente, esse é um problema com a 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 na depuração de problemas de tópico e assinatura.

Renovar a observação da caixa de e-mails

Você precisa chamar watch pelo menos uma vez a cada sete dias ou vai parar de receber atualizações do usuário. Recomendamos chamar watch uma vez por dia. A resposta do método watch também tem um expiration campo com o carimbo de data/hora da expiração watch.

Receber notificações

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

Se você configurou uma assinatura push, uma notificação de webhook para o servidor está 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 HTTP POST é JSON, e o payload de 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 e-mails do usuário:

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

Em seguida, você pode usar o history.list método para receber os detalhes da mudança do usuário desde o último historyId, conforme descrito em Sincronizar clientes com a API Gmail.

Por exemplo, use o history.list método para identificar as mudanças que ocorreram entre a solicitação watch inicial e o recebimento da mensagem de notificação compartilhada no exemplo anterior. Transmita 1234567890 como o startHistoryId para history.list. Depois, você pode manter 9876543210 como o último historyId conhecido para casos de uso futuros.

Se você configurou uma assinatura pull, consulte os exemplos de código no guia de assinaturas pull 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 a entrega push de webhook, responder com sucesso (por exemplo, HTTP 200) confirma a notificação.

Se você usar a entrega pull (REST Pull, RPC Pull, ou RPC StreamingPull), siga com uma chamada de confirmação (REST ou RPC). Consulte os exemplos de código no guia de assinaturas pull pull 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 você não confirmar as notificações (por exemplo, se o callback do webhook retornar um erro ou expirar), o Cloud Pub/Sub vai tentar novamente a notificação mais tarde.

Parar atualizações da caixa de e-mails

Para parar de receber atualizações em uma caixa de e-mails, chame o stop método. Todas as novas notificações vão parar em alguns minutos.

Limitações

Confira a seguir as limitações do trabalho com notificações push do servidor:

Taxa máxima de notificação

Cada usuário do Gmail observado tem uma taxa máxima de notificação de um evento por segundo. Todas as notificações de usuário que excederem essa taxa serão descartadas. Ao processar notificações, tenha cuidado para não acionar outra notificação, o que pode iniciar um loop de notificação.

Confiabilidade

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