Ten przewodnik zawiera informacje na temat wdrażania „przyrostowej synchronizacji” danych kalendarza. Ta metoda pozwala synchronizować dane wszystkich kolekcji kalendarzy i jednocześnie oszczędzać przepustowość.
Spis treści
Opis
Synchronizacja przyrostowa składa się z 2 etapów:
W celu pełnej synchronizacji stanu klienta ze stanem serwera przeprowadzana jest pierwsza pełna synchronizacja. Klient otrzyma token synchronizacji, który musi zostać zachowany.
Synchronizacja przyrostowa jest wykonywana wielokrotnie i aktualizuje klienta o wszystkie zmiany, które pojawiły się od czasu poprzedniej synchronizacji. Za każdym razem klient podaje poprzedni token synchronizacji uzyskany z serwera i zapisuje nowy token z odpowiedzi.
Pierwsza pełna synchronizacja
Wstępna pełna synchronizacja to pierwotne żądanie dotyczące wszystkich zasobów w kolekcji, które chcesz zsynchronizować. Jeśli chcesz zsynchronizować tylko określony podzbiór zasobów, możesz opcjonalnie ograniczyć żądanie listy za pomocą parametrów żądania.
W odpowiedzi na operację wyświetlania listy znajdziesz pole nextSyncToken
, które reprezentuje token synchronizacji. Musisz zapisać wartość nextSyncToken
. Jeśli zbiór wyników jest za duży, a odpowiedź zostanie podzielona na strony, pole nextSyncToken
znajduje się tylko na ostatniej stronie.
Synchronizacja przyrostowa
Synchronizacja przyrostowa umożliwia pobranie wszystkich zasobów, które zostały zmodyfikowane od czasu ostatniego żądania synchronizacji. W tym celu musisz wysłać żądanie listy z najnowszym tokenem synchronizacji określonym w polu syncToken
.
Pamiętaj, że wynik zawsze będzie zawierał usunięte wpisy, aby klienty mogły usunąć je z pamięci masowej.
Jeśli od ostatniego żądania synchronizacji przyrostowej zmieniła się duża liczba zasobów, w wyniku listy możesz zobaczyć pageToken
zamiast syncToken
. W takich przypadkach musisz wykonać dokładnie to samo zapytanie dotyczące listy, które zostało użyte do pobrania pierwszej strony w ramach synchronizacji przyrostowej (z dokładnie taką samą wartością elementu syncToken
), dołącz do niej parametr pageToken
i przedziel wszystkie kolejne żądania na strony, aż znajdziesz kolejny element syncToken
na ostatniej stronie. Zapisz syncToken
przy następnym żądaniu synchronizacji.
Oto przykładowe zapytania dotyczące zgłoszenia wymagającego przyrostowej synchronizacji z podziałem na strony:
Pierwotne zapytanie
GET /calendars/primary/events?maxResults=10&singleEvents=true&syncToken=CPDAlvWDx70CEPDAlvWDx
// Result contains the following
"nextPageToken":"CiAKGjBpNDd2Nmp2Zml2cXRwYjBpOXA",
Pobieranie następnej strony
GET /calendars/primary/events?maxResults=10&singleEvents=true&syncToken=CPDAlvWDx70CEPDAlvWDx&pageToken=CiAKGjBpNDd2Nmp2Zml2cXRwYjBpOXA
Serwer wymaga pełnej synchronizacji
Czasami tokeny synchronizacji są unieważniane przez serwer z różnych powodów, takich jak wygaśnięcie tokena lub zmiany na powiązanych listach kontroli dostępu (ACL).
W takich przypadkach serwer odpowiada na żądanie przyrostowe, podając kod odpowiedzi 410
. Powinno to spowodować całkowite wyczyszczenie magazynu klienta i nową pełną synchronizację.
Przykładowy kod
Fragment kodu poniżej pokazuje, jak używać tokenów synchronizacji w bibliotece klienta Java. Przy pierwszym wywołaniu metoda uruchamiania wykona pełną synchronizację i zapisze token synchronizacji. Przy każdym kolejnym uruchomieniu wczyta zapisany token synchronizacji i wykonasz synchronizację przyrostową.
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."); }
Starsza wersja synchronizacji
W przypadku kolekcji zdarzeń nadal możesz przeprowadzać synchronizację w starszy sposób, zachowując wartość zaktualizowanego pola z żądania listy zdarzeń, a potem używając pola modifiedSince
do pobrania zaktualizowanych zdarzeń.
To podejście nie jest już zalecane, ponieważ jest bardziej podatne na błędy w przypadku pominiętych aktualizacji (np. gdy nie wymusza ograniczeń dotyczących zapytań).
Jest też dostępna tylko w przypadku wydarzeń.