推送通知

概览

Gmail API 提供服务器推送通知，让您可以监视 Gmail 邮箱的更改。您可以使用此功能来提升应用性能。这样一来，您就不必轮询资源来确定它们是否已更改，从而省去额外的网络和计算费用。 每当邮箱发生变化时，Gmail API 都会通知您的后端服务器应用。

初始 Cloud Pub/Sub 设置

Gmail API 使用 Cloud Pub/Sub API 来传送推送通知。这样，您就可以通过各种方法接收通知，包括通过单个订阅端点上的 Webhook 和轮询接收通知。

前提条件

为了完成此设置的其余部分，请确保您满足 Cloud Pub/Sub 前提条件，然后设置 Cloud Pub/Sub 客户端。

创建主题

使用 Cloud Pub/Sub 客户端创建主题，Gmail API 应向该主题发送通知。主题名称可以是您在项目下选择的任何名称（即与 projects/myproject/topics/* 匹配，其中 myproject 是 Google Developers Console 中为您的项目列出的项目 ID）。

创建订阅

按照 Cloud Pub/Sub 订阅者指南设置对您创建的主题的订阅。将订阅类型配置为 Webhook 推送（即 HTTP POST 回调）或拉取（即由您的应用发起）。您的应用将通过这种方式接收更新通知。

针对您的主题授予发布权限

Cloud Pub/Sub 要求您授予 Gmail 向您的主题发布通知的权限。

为此，您需要向 gmail-api-push@system.gserviceaccount.com 授予 publish 权限。您可以使用 Cloud Pub/Sub 开发者控制台权限界面，按照资源级访问权限控制说明执行此操作。

接收 Gmail 邮箱更新

完成初始 Cloud Pub/Sub 设置后，配置 Gmail 账号以发送邮箱更新通知。

观看请求

如需将 Gmail 账号配置为向您的 Cloud Pub/Sub 主题发送通知，只需使用 Gmail API 客户端在 Gmail 用户邮箱上调用 watch，这与任何其他 Gmail API 调用类似。为此，请在 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 文档，确认设置是否正确，并获取有关调试主题和订阅问题的帮助。

续订邮箱手表

您必须至少每 7 天重新调用一次 watch，否则您将无法再接收用户的更新。我们建议每天调用 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 对象，其中包含用户的电子邮件地址和新的邮箱历史记录 ID：

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

然后，您可以按照同步指南中的说明，使用 history.list 获取自用户上次已知 historyId 以来的更改详情。

例如，如需使用 history.list 来识别初始 watch 调用与接收到上一个示例中共享的通知消息之间发生的更改，请将 1234567890 作为 startHistoryId 传递给 history.list。之后，9876543210 可作为上次已知的 historyId 持久保存，以供日后使用。

如果您配置的是拉取订阅，请参阅 Cloud Pub/Sub 订阅者拉取指南中的代码示例，详细了解如何接收消息。

回复通知

所有通知都需要确认。如果您使用网络钩子推送传递，则成功响应（例如 HTTP 200）将确认通知。

如果使用拉取传送（REST 拉取、RPC 拉取或 RPC StreamingPull），则必须跟进确认调用（REST 或 RPC）。如需详细了解如何使用基于官方 RPC 的客户端库异步或同步确认消息，请参阅 Cloud Pub/Sub 订阅者拉取指南中的代码示例。

如果通知未得到确认（例如，您的 Webhook 回调返回错误或超时），Cloud Pub/Sub 将在稍后重试通知。

停止邮箱更新

如需停止接收邮箱更新，请调用 stop，所有新通知应会在几分钟内停止。

限制

通知速率上限

每个受监控的 Gmail 用户的通知速率上限为每秒 1 个事件。任何高于此速率的用户通知都将被舍弃。处理通知时请务必小心，以免触发其他通知，从而启动通知循环。

可靠性

通常情况下，所有通知都应在几秒钟内可靠地送达；不过，在某些极端情况下，通知可能会延迟或丢失。 请务必妥善处理这种情况，以便即使未收到推送消息，应用仍能同步。例如，在一段时间内没有用户通知后，回退到定期调用 history.list。

Cloud Pub/Sub 限制

Cloud Pub/Sub API 也有自己的限制，具体详情请参阅其价格和配额文档。