Ce guide explique comment mettre en œuvre une "synchronisation incrémentielle" des données d'agenda. Cette méthode vous permet de synchroniser les données de toutes les collections d'agendas tout en économisant la bande passante.
Sommaire
Présentation
La synchronisation incrémentielle comprend deux étapes:
La synchronisation complète initiale est effectuée une fois au début afin de synchroniser complètement l'état du client avec celui du serveur. Le client obtient un jeton de synchronisation qu'il doit conserver.
La synchronisation incrémentielle est effectuée à plusieurs reprises et met à jour le client avec toutes les modifications survenues depuis la précédente synchronisation. Chaque fois, le client fournit l'ancien jeton de synchronisation obtenu auprès du serveur et stocke le nouveau jeton de synchronisation à partir de la réponse.
Synchronisation complète initiale
La synchronisation complète initiale correspond à la requête d'origine pour toutes les ressources de la collection que vous souhaitez synchroniser. Vous pouvez éventuellement restreindre la requête de liste à l'aide des paramètres de requête si vous ne souhaitez synchroniser qu'un sous-ensemble spécifique de ressources.
En réponse à l'opération de liste, vous trouverez un champ nommé nextSyncToken représentant un jeton de synchronisation. Vous devez stocker la valeur de nextSyncToken. Si l'ensemble de résultats est trop volumineux et que la réponse est paginée, le champ nextSyncToken n'est présent que sur la toute dernière page.
Synchronisation incrémentielle
La synchronisation incrémentielle vous permet de récupérer toutes les ressources qui ont été modifiées depuis la dernière requête de synchronisation. Pour ce faire, vous devez effectuer une requête de liste avec votre dernier jeton de synchronisation spécifié dans le champ syncToken.
N'oubliez pas que le résultat contiendra toujours les entrées supprimées, afin que les clients puissent les retirer de l'espace de stockage.
Dans les cas où un grand nombre de ressources a changé depuis la dernière requête de synchronisation incrémentielle, un résultat pageToken peut s'afficher à la place de syncToken dans le résultat de la liste. Dans ce cas, vous devez exécuter exactement la même requête de liste que celle utilisée pour extraire la première page de la synchronisation incrémentielle (avec exactement le même syncToken), y ajouter pageToken et paginer toutes les requêtes suivantes jusqu'à ce qu'un autre syncToken soit trouvé sur la dernière page. Veillez à stocker cet élément syncToken pour la prochaine requête de synchronisation.
Voici des exemples de requêtes pour un cas nécessitant une synchronisation paginée incrémentielle:
Requête initiale
GET /calendars/primary/events?maxResults=10&singleEvents=true&syncToken=CPDAlvWDx70CEPDAlvWDx
// Result contains the following
"nextPageToken":"CiAKGjBpNDd2Nmp2Zml2cXRwYjBpOXA",
Récupération de la page suivante
GET /calendars/primary/events?maxResults=10&singleEvents=true&syncToken=CPDAlvWDx70CEPDAlvWDx&pageToken=CiAKGjBpNDd2Nmp2Zml2cXRwYjBpOXA
Synchronisation complète requise par le serveur
Les jetons de synchronisation sont parfois invalidés par le serveur pour diverses raisons, y compris l'expiration du jeton ou des modifications des LCA associées.
Dans ce cas, le serveur répond à une requête incrémentielle avec le code de réponse 410. Cela devrait déclencher l'effacement complet du magasin du client et une nouvelle synchronisation complète.
Exemple de code
L'extrait de code ci-dessous montre comment utiliser des jetons de synchronisation avec la bibliothèque cliente Java. La première fois que la méthode d'exécution est appelée, elle effectue une synchronisation complète et stocke le jeton de synchronisation. Lors de chaque exécution ultérieure, il charge le jeton de synchronisation enregistré et effectue une synchronisation incrémentielle.
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.");
}
Ancienne synchronisation
Pour les collections d'événements, il est toujours possible d'effectuer la synchronisation à l'ancienne méthode en conservant la valeur du champ mis à jour dans une requête de liste d'événements, puis en utilisant le champ modifiedSince pour récupérer les événements mis à jour.
Cette approche n'est plus recommandée, car elle est plus sujette aux erreurs concernant les mises à jour manquées (par exemple, si les restrictions de requête ne sont pas appliquées).
De plus, elle n'est disponible que pour les événements.