במדריך הזה מוסבר איך להטמיע סנכרון מצטבר של נתוני לוח שנה. בשיטה הזו אפשר לשמור על סנכרון של הנתונים בכל אוספי היומנים, תוך חיסכון ברוחב הפס.
תוכן העניינים
סקירה כללית
סנכרון מצטבר מורכב משני שלבים:
סנכרון מלא ראשוני: מתבצע פעם אחת בהתחלה כדי לסנכרן באופן מלא את מצב הלקוח עם מצב השרת. הלקוח מקבל טוקן סנכרון שהוא חייב לשמור.
סנכרון מצטבר: מתבצע שוב ושוב כדי לעדכן את הלקוח בכל השינויים שבוצעו מאז הסנכרון הקודם. בכל פעם, הלקוח מספק את טוקן הסנכרון הקודם שהתקבל מהשרת ושומר את טוקן הסנכרון החדש מהתגובה.
סנכרון מלא ראשוני
הסנכרון המלא הראשוני הוא הבקשה המקורית לכל המשאבים של האוסף שרוצים לסנכרן. אם רוצים לסנכרן רק קבוצת משנה ספציפית של משאבים, אפשר להגביל את בקשת הרשימה באמצעות פרמטרים של בקשות.
בתשובה לפעולת הרשימה, התשובה מכילה שדה בשם nextSyncToken שמייצג אסימון סנכרון. חובה לשמור את הערך של nextSyncToken. אם קבוצת התוצאות גדולה מדי והתשובה מחולקת לדפים, השדה nextSyncToken מופיע רק בדף האחרון.
סנכרון מצטבר
סינכרון מצטבר מאפשר לאחזר את כל המשאבים שעברו שינוי מאז בקשת הסינכרון האחרונה. כדי לעשות את זה, שולחים בקשת רשימה עם אסימון הסנכרון האחרון שצוין בשדה syncToken.
חשוב לזכור שהתוצאה תמיד מכילה רשומות שנמחקו, כך שהלקוחות יכולים להסיר אותן מהאחסון.
במקרים שבהם מספר גדול של משאבים השתנו מאז הבקשה האחרונה לסנכרון מצטבר, יכול להיות שתופיע pageToken במקום syncToken בתוצאת הרשימה. במקרים כאלה, צריך להריץ את אותה שאילתת רשימה ששימשה לאחזור הדף הראשון בסנכרון המצטבר (עם אותו syncToken), לצרף אליה את pageToken ולעבור בין הבקשות הבאות עד שמוצאים עוד syncToken בדף האחרון. מאחסנים את syncToken לבקשת הסנכרון הבאה.
בדוגמאות הבאות מוצג סנכרון מצטבר עם חלוקה לדפים:
השאילתה המקורית
GET /calendars/primary/events?maxResults=10&singleEvents=true&syncToken=CPDAlvWDx70CEPDAlvWDx
התוצאה מכילה את הפרטים הבאים:
{
"nextPageToken": "CiAKGjBpNDd2Nmp2Zml2cXRwYjBpOXA"
}
שליפת הדף הבא
GET /calendars/primary/events?maxResults=10&singleEvents=true&syncToken=CPDAlvWDx70CEPDAlvWDx&pageToken=CiAKGjBpNDd2Nmp2Zml2cXRwYjBpOXA
השרת דורש סנכרון מלא
לפעמים השרת מבטל את התוקף של טוקנים לסנכרון בגלל תפוגה של הטוקן או שינויים ברשימות בקרת גישה (ACL) שקשורות אליו. במקרים כאלה, השרת מגיב לבקשה מצטברת עם קוד סטטוס של HTTP 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."); }
סנכרון מדור קודם
כדי לבצע סנכרון מדור קודם של אירועים, צריך לשמור את הערך של השדה updated מבקשה של רשימת אירועים, ואז להשתמש בשדה updatedMin כדי לאחזר אירועים מעודכנים. הגישה הזו לא מומלצת יותר כי היא נוטה יותר לשגיאות (לדוגמה, היא לא אוכפת הגבלות על שאילתות) והיא זמינה רק לאירועים.