Эта страница переведена с помощью Cloud Translation API.

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 также имеет свои ограничения, подробно описанные в документации по ценам и квотам .