将客户端与 Gmail 同步

在大多数应用场景中，让客户端与 Gmail 保持同步非常重要。总体而言，同步分为两种情况：完全同步和部分同步。当客户端首次连接到 Gmail 时，以及在一些其他极少见的情况下，需要进行完全同步。如果您的客户端最近已同步，那么部分同步是一种比完全同步更轻量级的替代方案。您还可以使用推送通知来实时触发部分同步，并且仅在必要时触发，从而避免不必要的轮询。

目录

完全同步

当应用首次连接到 Gmail 时，或者当部分同步不可用时，您必须执行完整同步。在完全同步操作中，应用应检索并存储尽可能多的最新消息或会话，以满足您的需求。例如，如果您的应用显示最近消息的列表，您可能希望检索并缓存足够的消息，以便在用户滚动浏览前几条显示的消息之外的消息时，实现响应迅速的界面。执行完整同步操作的一般流程如下：

1. 调用 messages.list 可检索第一页消息 ID。
2. 为列表请求返回的每条消息创建 messages.get 请求的批量请求。如果您的应用显示消息内容，则应在首次检索消息时使用 format=FULL 或 format=RAW，并缓存结果以避免额外的检索操作。如果您要检索之前缓存的消息，则应使用 format=MINIMAL 来减小响应的大小，因为只有 labelIds 可能会发生变化。
3. 将更新合并到缓存结果中。您的应用应存储最新消息（list 响应中的第一条消息）的 historyId，以便将来进行部分同步。

部分同步

如果您的应用最近已同步，则可以使用 history.list 方法执行部分同步，以返回比您在请求中指定的 startHistoryId 新的所有历史记录。历史记录会提供每条消息的消息 ID 和更改类型，例如自 startHistoryId 以来添加、删除的消息或修改的标签。您可以获取并存储完整同步或部分同步中最新消息的 historyId，以作为未来部分同步操作的 startHistoryId 提供。

限制

历史记录通常至少保留一周，有时甚至更长时间。不过，记录的可用时间段可能会短得多，并且在极少数情况下，记录有时可能无法使用。如果客户端提供的 startHistoryId 超出历史记录的可用范围，API 会返回 HTTP 404 错误响应。在这种情况下，您的客户端必须执行上一部分中所述的完整同步。