本指南將說明如何實作日曆資料的「增量同步處理」。使用這個方法,您可以讓所有日曆集合的資料保持同步,同時節省頻寬。
目錄
總覽
漸進式同步處理包含兩個階段:
系統會在最一開始時執行一次初始完整同步作業,以便將用戶端狀態與伺服器狀態完全同步。用戶端會取得需要保留的同步處理權杖。
系統會重複執行增量同步處理,並更新用戶端自上次同步處理後發生的所有變更。每次用戶端都會提供從伺服器取得的先前同步處理符記,並儲存回應中的新同步處理符記。
初始完整同步處理
初始完整同步處理作業是針對要同步處理的集合,對所有資源提出的原始要求。如果您只想同步處理特定的資源子集,可以選擇使用要求參數限制清單要求。
在清單作業的回應中,您會看到名為 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 用戶端程式庫。第一次呼叫執行方法時,系統會執行完整同步處理作業並儲存同步處理權杖。在每次後續執行時,它會載入已儲存的同步權杖,並執行遞增同步處理作業。
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
欄位擷取更新的事件。我們不再建議採用這種做法,因為在遺漏更新方面,這種做法更容易發生錯誤 (例如,如果未強制執行查詢限制)。此外,這項功能僅適用於事件。