将客户端与 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 错误响应。在这种情况下，您的客户端必须执行完整同步（如上一部分所述）。