Push-уведомления

Обзор

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

Первоначальная настройка Cloud Pub/Sub

API Gmail использует API Cloud Pub/Sub для доставки push-уведомлений. Это позволяет отправлять уведомления различными способами, включая веб-перехваты и опросы на одной конечной точке подписки.

Предпосылки

Чтобы завершить остальную часть настройки, убедитесь, что вы выполнили предварительные условия Cloud Pub/Sub, а затем настройте клиент Cloud Pub/Sub .

Создать тему

Используя клиент Cloud Pub/Sub, создайте тему , в которую API Gmail будет отправлять уведомления. Название темы может быть любым, выбранным вами в рамках вашего проекта (например, в формате projects/myproject/topics/* , где myproject — это идентификатор вашего проекта, указанный в консоли разработчика Google).

Создать подписку

Следуйте руководству для подписчиков Cloud Pub/Sub , чтобы настроить подписку на созданную вами тему. Выберите тип подписки: push-уведомление через веб-перехват (т.е. обратный вызов HTTP POST) или pull-уведомление (т.е. инициированное вашим приложением). Таким образом, ваше приложение будет получать уведомления об обновлениях.

Предоставьте права на публикацию по вашей теме

Cloud Pub/Sub требует предоставления прав Gmail для публикации уведомлений по вашей теме.

Для этого необходимо предоставить права publish для gmail-api-push@system.gserviceaccount.com . Это можно сделать через интерфейс управления разрешениями в консоли разработчика Cloud Pub/Sub, следуя инструкциям по управлению доступом на уровне ресурсов .

Получение обновлений почтового ящика Gmail

После завершения первоначальной настройки Cloud Pub/Sub настройте учетные записи Gmail для отправки уведомлений об обновлениях почтового ящика.

Запрос на просмотр

Чтобы настроить учётные записи Gmail для отправки уведомлений в тему Cloud Pub/Sub, просто используйте API-клиент Gmail для вызова функции watch для почтового ящика пользователя Gmail, как и для любого другого вызова API Gmail. Для этого укажите название темы, созданной выше, и любые другие параметры в запросе watch , например, labels для фильтрации. Например, чтобы получать уведомления обо всех изменениях в папке «Входящие»:

Протокол 

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()

Смотреть ответ

Если запрос watch будет успешным, вы получите ответ следующего вида:

{
  historyId: 1234567890
  expiration: 1431990098200
}

с текущим historyId почтового ящика пользователя. Все изменения после этого historyId будут уведомлены вашему клиенту. Если вам нужно обработать изменения до этого historyId , обратитесь к руководству по синхронизации .

Кроме того, успешный вызов watch должен привести к немедленной отправке уведомления в вашу тему Cloud Pub/Sub.

Если вы получили сообщение об ошибке при вызове watch , необходимо указать причину проблемы. Обычно она связана с настройкой темы и подписки Cloud Pub/Sub. Чтобы убедиться в правильности настройки и получить помощь по устранению проблем с темой и подпиской, обратитесь к документации Cloud Pub/Sub.

Обновление наблюдения за почтовым ящиком

Вам необходимо повторно вызывать watch как минимум каждые 7 дней, иначе вы перестанете получать обновления для пользователя. Мы рекомендуем вызывать watch один раз в день. В ответе watch также есть поле с указанием даты истечения срока watch .

Получение уведомлений

Всякий раз, когда происходит обновление почтового ящика, совпадающее с вашими watch , ваше приложение получит уведомление с описанием изменения.

Если вы настроили push-подписку, уведомление webhook на ваш сервер будет соответствовать 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"
}

Тело HTTP-запроса POST представляет собой JSON-код, а фактическая полезная нагрузка уведомления Gmail находится в поле message.data . Это поле message.data представляет собой строку в кодировке base64url, которая декодируется в JSON-объект, содержащий адрес электронной почты и новый идентификатор истории почтового ящика пользователя:

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

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

Например, чтобы использовать history.list для отслеживания изменений, произошедших между первым вызовом watch и получением уведомления, представленного в предыдущем примере, передайте 1234567890 в качестве startHistoryId в history.list . После этого значение 9876543210 можно сохранить как последний известный historyId для использования в будущем.

Если вместо этого вы настроили подписку по запросу, обратитесь к примерам кода в руководстве Cloud Pub/Sub Subscriber Pull для получения более подробной информации о получении сообщений.

Ответ на уведомления

Все уведомления должны быть подтверждены. Если вы используете push-доставку через webhook, то успешный ответ (например, HTTP 200) будет означать подтверждение получения уведомления.

При использовании доставки методом pull ( REST Pull , RPC Pull или RPC StreamingPull ) необходимо выполнить последующий вызов подтверждения ( REST или RPC ). Подробнее об асинхронном и синхронном подтверждении сообщений с использованием официальных клиентских библиотек на основе RPC см. примеры кода в руководстве Cloud Pub/Sub Subscriber Pull.

Если уведомления не подтверждены (например, обратный вызов webhook возвращает ошибку или истекает время ожидания), Cloud Pub/Sub повторит попытку отправки уведомления позднее.

Остановка обновлений почтового ящика

Чтобы прекратить получение обновлений на почтовый ящик, позвоните по номеру stop , и все новые уведомления прекратятся в течение нескольких минут.

Ограничения

Максимальная частота уведомлений

Для каждого отслеживаемого пользователя Gmail максимальная частота уведомлений составляет 1 событие в секунду. Любые уведомления, превышающие эту частоту, будут удалены. Будьте осторожны при работе с уведомлениями, чтобы не вызвать другие уведомления и не запустить цикл уведомлений.

Надежность

Обычно все уведомления должны доставляться стабильно в течение нескольких секунд, однако в некоторых экстремальных ситуациях уведомления могут задерживаться или отсутствовать. Убедитесь, что эта возможность корректно обрабатывается, чтобы приложение продолжало синхронизироваться даже при отсутствии push-уведомлений. Например, можно периодически вызывать history.list после определённого периода отсутствия уведомлений для пользователя.

Ограничения Cloud Pub/Sub

API Cloud Pub/Sub также имеет свои ограничения, подробно описанные в документации по ценам и квотам .