במדריך הזה נסביר איך מטמיעים 'סנכרון מצטבר' של נתוני יומן. השיטה הזו מאפשרת לשמור על סנכרון הנתונים של כל האוספים ביומן תוך חיסכון ברוחב הפס.
תוכן עניינים
סקירה כללית
סנכרון מצטבר מורכב משני שלבים:
סנכרון מלא ראשוני מתבצע פעם אחת בהתחלה, כדי לסנכרן באופן מלא את המצב של הלקוח עם המצב של השרת. הלקוח יקבל טוקן סנכרון שהוא צריך לשמור.
סנכרון מצטבר מתבצע שוב ושוב ומעדכן את הלקוח בכל השינויים שהתרחשו מאז הסנכרון הקודם. בכל פעם, הלקוח מספק את אסימון הסנכרון הקודם שקיבל מהשרת ושומר את אסימון הסנכרון החדש מהתגובה.
סנכרון מלא ראשוני
הסנכרון המלא הראשוני הוא הבקשה המקורית לכל המשאבים של האוסף שרוצים לסנכרן. אם רוצים לסנכרן רק קבוצת משנה ספציפית של משאבים, אפשר להגביל את בקשת הרשימה באמצעות פרמטרים של בקשות.
בתגובה לפעולה של הרשימה, יופיע השדה 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 כדי לאחזר אירועים מעודכנים.
הגישה הזו כבר לא מומלצת כי היא נוטה יותר לשגיאות בנוגע לעדכונים שהוחמצו (לדוגמה, אם לא נאכפות הגבלות על שאילתות).
בנוסף, היא זמינה רק לאירועים.