使用 Gmail API 配置推送通知

本文档介绍了如何使用 Gmail API 管理推送通知。

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 Cloud 控制台中列出的项目 ID）。

创建订阅

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

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

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

为此，请向 gmail-api-push@system.gserviceaccount.com 授予 publish 权限。您可以在 Google Cloud 控制台中使用 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 之前处理更改，请参阅将客户端与 Gmail 同步。

此外，成功的 watch 调用会立即向您的 Cloud Pub/Sub 主题发送通知。

如果您收到来自 watch 调用的错误，详细信息应说明问题的来源。这通常是 Cloud Pub/Sub 主题和订阅设置方面的问题。请参阅 Cloud Pub/Sub 文档，确认设置是否正确，并获取有关调试主题和订阅问题的帮助。

续订邮箱监控

您必须至少每 7 天调用一次 watch 方法，否则您将无法再接收用户的更新。 我们建议每天调用 watch 一次。watch 方法响应还具有一个 expiration 字段，其中包含 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 以来所做的更改的详细信息，如将客户端与 Gmail 同步中所述。

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

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

有关通知的操作

您必须确认所有通知。如果您使用 webhook 推送传送，则成功响应（例如，HTTP 200）表示已确认通知。

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

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

停止接收邮箱更新

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

限制

使用服务器推送通知时存在以下限制：

通知速率上限

每个受监控的 Gmail 用户的通知速率上限为每秒一个事件。如果用户通知的发送速率超过该速率，服务会舍弃这些通知。处理通知时，请注意不要触发另一个通知，否则可能会导致通知循环。

可靠性

通常，Cloud Pub/Sub 会在几秒钟内传送通知。不过，在极少数情况下，通知可能会延迟或丢失。妥善处理这种可能性，以便即使应用未收到推送消息，仍能进行同步。例如，在一段时间内没有收到用户通知后，回退到定期调用 history.list 方法。

Cloud Pub/Sub 限制

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