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

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

Обзор

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

Первоначальная настройка облачной системы публикации/подписки

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 для отправки уведомлений об обновлениях почтового ящика.

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

Чтобы настроить отправку уведомлений в тему Cloud Pub/Sub для учетных записей Gmail, используйте клиент 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",
}

Python

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-уведомления, уведомление веб-хука на ваш сервер будет соответствовать типу 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: &quot;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 для дальнейшего использования.

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

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

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

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

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

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

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

Ограничения

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

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

Надежность

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

Ограничения облачной публикации/подписки

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