本文档介绍了如何使用 Gmail API 同步客户端。
在大多数应用场景中，让客户端与 Gmail 保持同步非常重要。同步方法有两种：完全同步和部分同步。当客户端首次连接到 Gmail 时，以及在一些其他极少见的情况下，需要进行完全同步。如果您的客户端最近已同步，则部分同步是比完全同步更轻量级的替代方案。您还可以使用推送通知来实时触发部分同步，并且仅在必要时触发，从而避免不必要的轮询。
完全同步
如果您的应用是首次连接到 Gmail，或者无法进行部分同步，则必须执行完整同步。在完全同步操作中，您的应用应检索并存储尽可能多的最新消息或会话，以满足您的需求。例如，如果您的应用显示最近消息的列表，您可能需要检索并缓存足够的消息，以便在用户滚动浏览前几条显示的消息之外的内容时，界面能够快速响应。
请按照以下步骤执行完整同步：
调用
messages.list方法以检索第一页消息 ID。为列表请求返回的每条消息创建
messages.get方法请求的批量请求。如果您的应用显示消息内容，则应在应用首次检索到消息时将
Format设置为format=FULL或format=RAW，并缓存结果，以避免额外的检索操作。如果您要检索之前缓存的消息，则应使用format=MINIMAL来减小响应的大小，因为只有labelIds可能会发生变化。将更新合并到缓存结果中。您的应用应存储最新消息（
list响应中的第一条消息）的historyId，以供将来进行部分同步。
部分同步
如果您的应用最近同步过，则可以使用 history.list 方法执行部分同步，以返回比您在请求中必须指定的 startHistoryId 查询参数更新的所有历史记录。
startHistoryId 查询参数必须设置为最近一条消息的 historyId。如需检索最近一条消息的 historyId，请使用 messages.get 或 messages.list 方法。您还可以在完全同步或部分同步期间设置该值，以供日后使用。
返回的 History 对象包含自所提供的 startHistoryId 时间以来每封邮件的消息 ID 和更改类型，例如添加邮件或修改标签。
限制
历史记录通常至少保留一周，有时会保留更长时间。 不过，记录的可用时间段可能会短得多，并且在极少数情况下，记录可能无法使用。
如果客户端提供的 startHistoryId 超出了历史记录的可用范围，Gmail API 会返回 HTTP 404 错误响应。在这种情况下，您的客户端必须执行完全同步。