Sincronizar clientes com o Gmail

Este documento explica como sincronizar clientes usando a API Gmail.

Manter seu cliente sincronizado com o Gmail é importante para a maioria dos cenários de apps. Há dois métodos de sincronização: completa e parcial. A sincronização completa é necessária na primeira vez que o cliente se conecta ao Gmail e em alguns outros cenários raros. Se o cliente tiver sincronizado recentemente, a sincronização parcial será uma alternativa mais leve à sincronização completa. Você também pode usar notificações push para acionar a sincronização parcial em tempo real e somente quando necessário, evitando a sondagem desnecessária.

Sincronização completa

Na primeira vez que seu app se conecta ao Gmail ou se a sincronização parcial não estiver disponível, você precisa fazer uma sincronização completa. Em uma operação de sincronização completa, o app precisa recuperar e armazenar o máximo possível das mensagens ou conversas mais recentes necessárias para a finalidade. Por exemplo, se o app mostrar uma lista de mensagens recentes, talvez seja interessante recuperar e armazenar em cache mensagens suficientes para permitir uma interface responsiva se o usuário rolar além das primeiras mensagens exibidas.

Siga estas etapas para fazer uma sincronização completa:

  1. Chame o método messages.list para recuperar a primeira página de IDs de mensagens.

  2. Crie uma solicitação em lote de solicitações de método messages.get para cada uma das mensagens retornadas pela solicitação de lista.

    Se o app mostrar o conteúdo das mensagens, defina Format como format=FULL ou format=RAW na primeira vez que o app recuperar uma mensagem e armazene os resultados em cache para evitar outras operações de recuperação. Se você estiver recuperando uma mensagem armazenada em cache, use format=MINIMAL para reduzir o tamanho da resposta, já que apenas o labelIds pode mudar.

  3. Mescle as atualizações aos resultados armazenados em cache. O app precisa armazenar o historyId da mensagem mais recente (a primeira mensagem na resposta list) para sincronizações parciais futuras.

Sincronização parcial

Se o app tiver sido sincronizado recentemente, você poderá fazer uma sincronização parcial usando o método history.list para retornar todos os registros de histórico mais recentes que o parâmetro de consulta startHistoryId especificado na solicitação.

O parâmetro de consulta startHistoryId precisa ser definido como o historyId de uma mensagem recente. Para recuperar o historyId de uma mensagem recente, use os métodos messages.get ou messages.list. Você também pode definir o valor durante uma sincronização completa ou parcial para uso futuro.

O objeto History retornado inclui IDs de mensagens e o tipo de mudança de cada mensagem, como mensagem adicionada ou marcadores modificados, desde o momento do startHistoryId fornecido.

Limitações

Os registros de histórico geralmente ficam disponíveis por pelo menos uma semana e, muitas vezes, por mais tempo. No entanto, o período em que os registros ficam disponíveis pode ser significativamente menor, e eles podem ficar indisponíveis em casos raros.

Se o startHistoryId fornecido pelo cliente estiver fora do intervalo disponível de registros de histórico, a API Gmail vai retornar uma resposta de erro HTTP 404. Nesse caso, o cliente precisa fazer uma sincronização completa.