Este guia descreve como implementar a "sincronização incremental" de dados da agenda. Com esse método, é possível manter os dados de todas as coleções de agendas sincronizados e economizar largura de banda.
Conteúdo
Informações gerais
A sincronização incremental consiste em dois estágios:
A sincronização completa inicial é realizada uma vez bem no início para sincronizar totalmente o estado do cliente com o do servidor. O cliente receberá um token de sincronização que precisa ser mantido.
A sincronização incremental é realizada repetidamente e atualiza o cliente com todas as mudanças que aconteceram desde a sincronização anterior. Sempre que o cliente fornece o token de sincronização anterior do servidor, ele armazena o novo da resposta.
Sincronização completa inicial
A sincronização completa inicial é a solicitação original para todos os recursos da coleção que você quer sincronizar. Também é possível restringir a solicitação de lista usando parâmetros de solicitação se quiser apenas sincronizar um subconjunto específico de recursos.
Na resposta à operação de lista, você vai encontrar um campo chamado nextSyncToken
, que representa um token de sincronização. Você vai precisar armazenar o valor de
nextSyncToken
. Se o conjunto de resultados for muito grande e a resposta for paginada, o campo nextSyncToken
vai aparecer apenas na última página.
Sincronização incremental
A sincronização incremental permite recuperar todos os recursos que foram
modificados desde a última solicitação de sincronização. Para fazer isso, é necessário executar uma solicitação de
lista com seu token de sincronização mais recente especificado no campo syncToken
.
Lembre-se de que o resultado sempre conterá entradas excluídas, para que os
clientes tenham a chance de removê-las do armazenamento.
Nos casos em que um grande número de recursos foi alterado desde a última
solicitação de sincronização incremental, você pode encontrar um pageToken
em vez de uma syncToken
no resultado da lista. Nesses casos, é necessário executar exatamente a mesma
consulta de lista que foi usada para recuperar a primeira página na sincronização incremental
(com o mesmo syncToken
), anexar pageToken
a ela e
paginar em todas as solicitações a seguir até encontrar outro syncToken
na última página. Armazene esse syncToken
para a próxima solicitação de
sincronização no futuro.
Confira alguns exemplos de consultas de um caso que exigem sincronização paginada incremental:
Consulta original
GET /calendars/primary/events?maxResults=10&singleEvents=true&syncToken=CPDAlvWDx70CEPDAlvWDx
// Result contains the following
"nextPageToken":"CiAKGjBpNDd2Nmp2Zml2cXRwYjBpOXA",
Como recuperar a próxima página
GET /calendars/primary/events?maxResults=10&singleEvents=true&syncToken=CPDAlvWDx70CEPDAlvWDx&pageToken=CiAKGjBpNDd2Nmp2Zml2cXRwYjBpOXA
Sincronização completa exigida pelo servidor
Às vezes, os tokens de sincronização são invalidados pelo servidor por vários motivos,
incluindo expiração do token ou alterações nas ACLs relacionadas.
Nesses casos, o servidor responderá a uma solicitação incremental com um
código de resposta 410
. Isso aciona uma exclusão permanente do armazenamento do cliente e uma nova sincronização completa.
Exemplo de código
O snippet de exemplo de código abaixo demonstra como usar tokens de sincronização com a biblioteca de cliente Java. Na primeira vez que o método de execução for chamado, ele vai realizar uma sincronização completa e armazenar o token de sincronização. Em cada execução subsequente, ele carrega o token de sincronização salvo e executa uma sincronização 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."); }
Sincronização legada
Para coleções de eventos, ainda é possível fazer a sincronização da maneira legada, preservando o valor do campo atualizado de uma solicitação de lista de eventos e usando o campo modifiedSince
para recuperar eventos atualizados.
Essa abordagem não é mais recomendada, porque é mais propensa a erros em relação
a atualizações perdidas (por exemplo, se não aplicar restrições de consulta).
Além disso, ele está disponível apenas para eventos.