Push-уведомления, 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).

Мы рекомендуем использовать одну тему для всех push-уведомлений API Gmail для вашего приложения из-за ограничений Cloud Pub/Sub на количество тем.

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

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

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

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

Для этого вам необходимо предоставить права publish на [e-mail] . Это можно сделать с помощью интерфейса разрешений консоли разработчика 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 , ваше приложение получит уведомление с описанием изменения.

Если вы настроили принудительную подписку, уведомление веб-перехватчика на вашем сервере будет соответствовать 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": "[e-mail]", "historyId": "9876543210"}

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

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

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

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

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

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

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

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

Ограничения

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

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

Надежность

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

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

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