คู่มือนี้จะอธิบายวิธี ใช้งาน "การซิงค์ที่เพิ่มขึ้น" ของข้อมูลปฏิทิน เมื่อใช้วิธีนี้ คุณจะซิงค์ข้อมูลคอลเล็กชันปฏิทินทั้งหมดพร้อมกับประหยัดแบนด์วิดท์ได้
เนื้อหา
ภาพรวม
การซิงค์ส่วนเพิ่มประกอบด้วยสองขั้นตอน:
การซิงค์เต็มรูปแบบเริ่มต้นจะดำเนินการเพียงครั้งเดียวในตอนเริ่มต้น เพื่อซิงค์สถานะของไคลเอ็นต์กับสถานะของเซิร์ฟเวอร์อย่างสมบูรณ์ ไคลเอ็นต์จะได้รับโทเค็นการซิงค์ที่ต้องใช้เพื่อคงไว้
ระบบจะซิงค์ส่วนเพิ่มซ้ำๆ และอัปเดตไคลเอ็นต์ให้ทำการเปลี่ยนแปลงทั้งหมดตั้งแต่การซิงค์ครั้งก่อน ทุกครั้ง ไคลเอ็นต์จะระบุโทเค็นการซิงค์ที่ได้มาจากเซิร์ฟเวอร์ก่อนหน้านี้ และจัดเก็บโทเค็นการซิงค์ใหม่จากการตอบกลับ
การซิงค์เต็มรูปแบบเริ่มต้น
การซิงค์แบบเต็มเริ่มต้นเป็นคำขอเดิมสำหรับทรัพยากรทั้งหมดของคอลเล็กชันที่คุณต้องการซิงค์ คุณสามารถเลือกจำกัดคำขอรายการโดยใช้พารามิเตอร์คำขอได้ในกรณีที่คุณต้องการซิงค์ทรัพยากรชุดย่อยที่เฉพาะเจาะจงเท่านั้น
ในการตอบกลับการดำเนินการรายการ คุณจะเห็นช่องที่มีชื่อว่า 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 เพื่อเรียกข้อมูลเหตุการณ์ที่อัปเดต
เราไม่แนะนำวิธีนี้อีกต่อไป เนื่องจากอาจเกิดข้อผิดพลาดเกี่ยวกับการอัปเดตที่พลาดไปได้ (เช่น ในกรณีที่ไม่ได้บังคับใช้ข้อจำกัดในการค้นหา)
นอกจากนี้ยังใช้ได้เฉพาะกับกิจกรรมเท่านั้น