本指南介绍了如何实现日历数据的“增量同步”。使用此方法,您可以让所有日历集合的数据保持同步,同时节省带宽。
目录
概览
增量同步包含两个阶段:
系统会在开头执行一次初始完整同步,以便将客户端状态与服务器状态完全同步。客户端将获得需要保留的同步令牌。
增量同步会反复执行,并使用自上次同步以来发生的所有更改更新客户端。每次,客户端都会提供从服务器获取的上一个同步令牌,并存储响应中的新同步令牌。
初始完整同步
初始完整同步是指对您要同步的集合中的所有资源发出的原始请求。如果您只想同步特定子集的资源,可以视需要使用请求参数限制列表请求。
在列出操作的响应中,您会看到一个名为 nextSyncToken
的字段,该字段表示同步令牌。您需要存储 nextSyncToken
的值。如果结果集过大,并且响应分页,则 nextSyncToken
字段仅出现在最后一页上。
增量同步
借助增量同步,您可以检索自上次同步请求以来修改的所有资源。为此,您需要在 syncToken
字段中指定最新的同步令牌,然后执行列表请求。请注意,结果始终会包含已删除的条目,以便客户端有机会将其从存储空间中移除。
如果自上次增量同步请求后有大量资源发生了更改,您可能会在列表结果中看到 pageToken
,而不是 syncToken
。在这些情况下,您需要执行与在增量同步中检索第一页时完全相同的列表查询(使用完全相同的 syncToken
),将 pageToken
附加到该查询,并按页面浏览所有后续请求,直到在最后一页上找到另一个 syncToken
。请务必存储此 syncToken
,以备日后进行下一次同步请求。
以下是需要增量分页同步的支持请求的查询示例:
原始查询
GET /calendars/primary/events?maxResults=10&singleEvents=true&syncToken=CPDAlvWDx70CEPDAlvWDx
// Result contains the following
"nextPageToken":"CiAKGjBpNDd2Nmp2Zml2cXRwYjBpOXA",
正在检索下一页
GET /calendars/primary/events?maxResults=10&singleEvents=true&syncToken=CPDAlvWDx70CEPDAlvWDx&pageToken=CiAKGjBpNDd2Nmp2Zml2cXRwYjBpOXA
服务器要求完全同步
有时,服务器会因各种原因(包括令牌过期或相关 ACL 发生变化)而使同步令牌失效。在这种情况下,服务器会使用响应代码 410
响应增量请求。这应会触发客户端存储空间的完整擦除以及新的完整同步。
示例代码
以下代码段示例演示了如何将同步令牌与 Java 客户端库搭配使用。第一次调用 run 方法时,它会执行完整同步并存储同步令牌。在后续每次执行时,它都会加载已保存的同步令牌并执行增量同步。
private static void run() throws IOException { // Construct the {@link Calendar.Events.List} request, but don't execute it yet. Calendar.Events.List request = client.events().list("primary"); // Load the sync token stored from the last execution, if any. String syncToken = syncSettingsDataStore.get(SYNC_TOKEN_KEY); if (syncToken == null) { System.out.println("Performing full sync."); // Set the filters you want to use during the full sync. Sync tokens aren't compatible with // most filters, but you may want to limit your full sync to only a certain date range. // In this example we are only syncing events up to a year old. Date oneYearAgo = Utils.getRelativeDate(java.util.Calendar.YEAR, -1); request.setTimeMin(new DateTime(oneYearAgo, TimeZone.getTimeZone("UTC"))); } else { System.out.println("Performing incremental sync."); request.setSyncToken(syncToken); } // Retrieve the events, one page at a time. String pageToken = null; Events events = null; do { request.setPageToken(pageToken); try { events = request.execute(); } catch (GoogleJsonResponseException e) { if (e.getStatusCode() == 410) { // A 410 status code, "Gone", indicates that the sync token is invalid. System.out.println("Invalid sync token, clearing event store and re-syncing."); syncSettingsDataStore.delete(SYNC_TOKEN_KEY); eventDataStore.clear(); run(); } else { throw e; } } List<Event> items = events.getItems(); if (items.size() == 0) { System.out.println("No new events to sync."); } else { for (Event event : items) { syncEvent(event); } } pageToken = events.getNextPageToken(); } while (pageToken != null); // Store the sync token from the last request to be used during the next execution. syncSettingsDataStore.set(SYNC_TOKEN_KEY, events.getNextSyncToken()); System.out.println("Sync complete."); }
旧版同步
对于事件集合,您仍然可以通过以下方式以旧版方式进行同步:保留事件列表请求中更新字段的值,然后使用 modifiedSince
字段检索更新后的事件。我们不再建议采用这种方法,因为它更容易出现错过更新的问题(例如,未强制执行查询限制)。此外,它仅适用于事件。