Синхронизация клиентов с Gmail

В этом документе объясняется, как синхронизировать клиенты с помощью API Gmail.

Для большинства приложений важно поддерживать синхронизацию вашего клиента с Gmail. Существует два метода синхронизации: полная и частичная . Полная синхронизация требуется при первом подключении клиента к Gmail, а также в некоторых других редких случаях. Если ваш клиент недавно синхронизировался, частичная синхронизация является более легкой альтернативой полной синхронизации. Вы также можете использовать push-уведомления для запуска частичной синхронизации в режиме реального времени и только при необходимости, избегая таким образом ненужного опроса.

Полная синхронизация

При первом подключении вашего приложения к Gmail или если частичная синхронизация недоступна, необходимо выполнить полную синхронизацию. В ходе полной синхронизации ваше приложение должно получить и сохранить столько последних сообщений или цепочек переписки, сколько необходимо для ваших целей. Например, если ваше приложение отображает список последних сообщений, вам может потребоваться получить и кэшировать достаточное количество сообщений, чтобы обеспечить адаптивный интерфейс, если пользователь прокрутит страницу дальше первых нескольких отображаемых сообщений.

Для выполнения полной синхронизации выполните следующие действия:

  1. Вызовите метод messages.list , чтобы получить первую страницу идентификаторов сообщений.

  2. Создайте пакетный запрос , содержащий запросы метода messages.get для каждого сообщения, возвращенного запросом списка.

    Если ваше приложение отображает содержимое сообщений, следует установить Format в format=FULL или format=RAW при первом получении сообщения и кэшировать результаты, чтобы избежать дополнительных операций получения. Если вы получаете ранее кэшированное сообщение, следует использовать format=MINIMAL , чтобы уменьшить размер ответа, поскольку могут изменяться только labelIds .

  3. Объедините обновления с кэшированными результатами. Ваше приложение должно хранить historyId самого последнего сообщения (первого сообщения в ответе list ) для будущих частичных синхронизаций.

Частичная синхронизация

Если ваше приложение недавно синхронизировалось, вы можете выполнить частичную синхронизацию, используя метод history.list , чтобы получить все записи истории, более новые, чем значение параметра запроса startHistoryId который необходимо указать в запросе.

Параметр запроса startHistoryId должен быть установлен на historyId последнего сообщения. Чтобы получить historyId последнего сообщения, используйте методы messages.get или messages.list . Вы также можете установить значение во время полной или частичной синхронизации для дальнейшего использования.

Возвращаемый объект History содержит идентификаторы сообщений и тип изменения для каждого сообщения, например, добавление сообщения или изменение меток, с момента, указанного в startHistoryId .

Ограничения

Как правило, исторические записи доступны как минимум за одну неделю, а часто и дольше. Однако период, за который доступны записи, может быть значительно короче, а в редких случаях записи могут быть недоступны.

Если значение startHistoryId предоставленное вашим клиентом, выходит за пределы доступного диапазона записей истории, API Gmail возвращает ошибку HTTP 404 В этом случае вашему клиенту необходимо выполнить полную синхронизацию .