Sincroniza recursos de forma eficiente

En esta guía, se describe cómo implementar la sincronización incremental de datos del calendario. Con este método, puedes mantener sincronizados los datos de todas las colecciones del calendario y ahorrar ancho de banda.

Contenido

Descripción general

La sincronización incremental consta de dos etapas:

  1. Sincronización completa inicial: Se realiza una vez al principio para sincronizar por completo el estado del cliente con el estado del servidor. El cliente obtiene un token de sincronización que debe conservar.

  2. Sincronización incremental: Se realiza de forma repetida para actualizar el cliente con todos los cambios realizados desde la sincronización anterior. Cada vez, el cliente proporciona el token de sincronización anterior obtenido del servidor y almacena el token de sincronización nuevo de la respuesta.

Sincronización completa inicial

La sincronización completa inicial es la solicitud original de todos los recursos de la colección que deseas sincronizar. De manera opcional, puedes restringir la solicitud de lista con parámetros de solicitud si solo deseas sincronizar un subconjunto específico de recursos.

En la respuesta a la operación de lista, la respuesta contiene un campo llamado nextSyncToken que representa un token de sincronización. Debes almacenar el valor de nextSyncToken. Si el conjunto de resultados es demasiado grande y la respuesta está paginada, el nextSyncToken campo solo está presente en la última página.

Sincronización incremental

La sincronización incremental te permite recuperar todos los recursos que se modificaron desde la última solicitud de sincronización. Para ello, realiza una solicitud de lista con el token de sincronización más reciente especificado en el campo syncToken. Ten en cuenta que el resultado siempre contiene entradas borradas, por lo que los clientes pueden quitarlas del almacenamiento.

En los casos en que se haya cambiado una gran cantidad de recursos desde la última solicitud de sincronización incremental, es posible que encuentres un pageToken en lugar de un syncToken en el resultado de la lista. En estos casos, realiza la misma consulta de lista que se usó para recuperar la primera página en la sincronización incremental (con el mismo syncToken), agrega el pageToken y pagina las solicitudes posteriores hasta que encuentres otro syncToken en la última página. Almacena este syncToken para la próxima solicitud de sincronización.

En los siguientes ejemplos, se muestra una sincronización incremental paginada:

Consulta original

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

El resultado contiene lo siguiente:

{
  "nextPageToken": "CiAKGjBpNDd2Nmp2Zml2cXRwYjBpOXA"
}

Recuperación de la página siguiente

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

Sincronización completa requerida por el servidor

A veces, el servidor invalida los tokens de sincronización debido al vencimiento del token o a cambios en las ACL relacionadas. En esos casos, el servidor responde a una solicitud incremental con el código de estado HTTP 410. Cuando esto sucede, borra el almacenamiento del cliente y realiza una nueva sincronización completa.

Código de muestra

En el siguiente ejemplo, se muestra cómo usar tokens de sincronización con la biblioteca cliente de Java. La primera vez que se llama al método run(), se realiza una sincronización completa y se almacena el token de sincronización. En cada ejecución posterior, se carga el token de sincronización guardado y se realiza una sincronización incremental.

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

Sincronización de legado

Para las colecciones de eventos, puedes realizar la sincronización de legado guardando el valor del campo updated de una solicitud de lista de eventos y, luego, usando el updatedMin campo para recuperar los eventos actualizados. Este enfoque ya no se recomienda porque es más propenso a errores (por ejemplo, no aplica restricciones de consulta) y solo está disponible para eventos.