このガイドでは、カレンダー データの「増分同期」を実装する方法について説明します。この方法を使用すると、帯域幅を節約しながら、すべてのカレンダー コレクションのデータの同期を維持できます。
目次
概要
増分同期は次の 2 つのステージで構成されます。
クライアントの状態をサーバーの状態と完全に同期させるため、最初の完全同期は最初に 1 回実行されます。クライアントは、保持する必要がある同期トークンを取得します。
増分同期は繰り返し実行され、前回の同期以降に発生したすべての変更でクライアントを更新します。毎回、クライアントはサーバーから取得した以前の同期トークンを提供し、レスポンスから新しい同期トークンを保存します。
最初の完全同期
最初の完全同期は、同期するコレクションのすべてのリソースに対する元のリクエストです。特定のリソースのサブセットのみを同期する場合は、必要に応じてリクエスト パラメータを使用してリスト リクエストを制限できます。
list オペレーションのレスポンスには、同期トークンを表す nextSyncToken というフィールドがあります。nextSyncToken の値は保存する必要があります。結果セットが大きすぎてレスポンスがページ分割された場合、nextSyncToken フィールドは最後のページにのみ存在します。
増分同期
増分同期では、最後の同期リクエスト以降に変更されたすべてのリソースを取得できます。これを行うには、syncToken フィールドに指定した最新の同期トークンを使用してリスト リクエストを実行する必要があります。クライアントがストレージから削除できるように、結果には削除されたエントリが常に含まれていることに注意してください。
最後の増分同期リクエスト以降に多数のリソースが変更された場合、リストの結果に syncToken ではなく pageToken が表示されることがあります。このような場合は、増分同期の最初のページの取得に使用したのとまったく同じリストクエリを実行する必要があります（まったく同じ 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 フィールドを使用して更新されたイベントを取得することで、以前の方法で同期を行うことができます。この方法は、更新の欠落を伴いエラーが発生しやすいため、非推奨になりました（クエリの制限を適用しない場合など）。また、使用できるのはイベントに対してのみです。