Sincronizza le risorse in modo efficiente

Questa guida descrive come implementare la "sincronizzazione incrementale" dei dati del calendario. Con questo metodo, puoi mantenere sincronizzati i dati di tutte le raccolte di calendari e risparmiare larghezza di banda.

Sommario

Panoramica

La sincronizzazione incrementale è composta da due fasi:

  1. La sincronizzazione completa iniziale viene eseguita una volta all'inizio per sincronizzare completamente lo stato del client con quello del server. Il client otterrà un token di sincronizzazione che deve essere persistente.

  2. La sincronizzazione incrementale viene eseguita ripetutamente e aggiorna il client con tutte le modifiche apportate dalla sincronizzazione precedente. Ogni volta, il client fornisce il token di sincronizzazione precedente ottenuto dal server e memorizza il nuovo token di sincronizzazione dalla risposta.

Sincronizzazione completa iniziale

La sincronizzazione completa iniziale è la richiesta originale di tutte le risorse della raccolta da sincronizzare. Se vuoi sincronizzare solo un sottoinsieme specifico di risorse, puoi limitare la richiesta di elenco utilizzando i parametri di richiesta.

Nella risposta all'operazione di elenco, troverai un campo chiamato nextSyncToken che rappresenta un token di sincronizzazione. Dovrai memorizzare il valore di nextSyncToken. Se il set di risultati è troppo grande e la risposta viene paginata, il campo nextSyncToken è presente solo nell'ultima pagina.

Sincronizzazione incrementale

La sincronizzazione incrementale ti consente di recuperare tutte le risorse che sono state modificate dall'ultima richiesta di sincronizzazione. Per farlo, devi eseguire una richiesta di elenco con il token di sincronizzazione più recente specificato nel campo syncToken. Tieni presente che il risultato conterrà sempre le voci eliminate, in modo che i clienti abbiano la possibilità di rimuoverle dallo spazio di archiviazione.

Se un numero elevato di risorse è cambiato dall'ultima richiesta di sincronizzazione incrementale, nel risultato dell'elenco potresti trovare pageToken anziché syncToken. In questi casi, dovrai eseguire la stessa query sull'elenco utilizzata per il recupero della prima pagina nella sincronizzazione incrementale (con lo stesso syncToken), aggiungervi pageToken e eseguire la paginazione di tutte le richieste successive finché non trovi un altro syncToken nell'ultima pagina. Assicurati di conservare questo syncToken per la prossima richiesta di sincronizzazione in futuro.

Di seguito sono riportate alcune query di esempio per una richiesta che richiede la sincronizzazione incrementale paginata:

Query originale

GET /calendars/primary/events?maxResults=10&singleEvents=true&syncToken=CPDAlvWDx70CEPDAlvWDx

// Result contains the following

"nextPageToken":"CiAKGjBpNDd2Nmp2Zml2cXRwYjBpOXA",

Recupero della pagina successiva

GET /calendars/primary/events?maxResults=10&singleEvents=true&syncToken=CPDAlvWDx70CEPDAlvWDx&pageToken=CiAKGjBpNDd2Nmp2Zml2cXRwYjBpOXA

Sincronizzazione completa richiesta dal server

A volte i token di sincronizzazione vengono invalidati dal server per vari motivi, tra cui la scadenza dei token o le modifiche alle ACL correlate. In questi casi, il server risponderà a una richiesta incrementale con un codice di risposta 410. Dovrebbe attivare un azzeramento completo del negozio del cliente e una nuova sincronizzazione completa.

Codice di esempio

Lo snippet di codice di esempio riportato di seguito mostra come utilizzare i token di sincronizzazione con la libreria client Java. La prima volta che viene chiamato il metodo run, viene eseguita una sincronizzazione completa e viene memorizzato il token di sincronizzazione. A ogni esecuzione successiva, verrà caricato il token di sincronizzazione salvato ed eseguita una sincronizzazione incrementale.

  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.");
  }
SyncTokenSample.java

Sincronizzazione precedente

Per le raccolte di eventi, è ancora possibile eseguire la sincronizzazione in modo legacy mantenendo il valore del campo aggiornato da una richiesta di elenco di eventi e utilizzando il campo modifiedSince per recuperare gli eventi aggiornati. Questo approccio non è più consigliato in quanto è più soggetto a errori rispetto agli aggiornamenti mancati (ad esempio se non applica le restrizioni delle query). Inoltre, è disponibile solo per gli eventi.