Synchroniser des clients avec Gmail

Ce document explique comment synchroniser les clients avec l'API Gmail.

Il est important de synchroniser votre client avec Gmail pour la plupart des scénarios d'application. Il existe deux méthodes de synchronisation : la synchronisation complète et la synchronisation partielle. Vous devez effectuer une synchronisation complète la première fois que votre client se connecte à Gmail et dans de rares cas. Si votre client a été synchronisé récemment, la synchronisation partielle est une alternative légère à une synchronisation complète. Vous pouvez également utiliser des notifications push pour déclencher une synchronisation partielle en temps réel et uniquement lorsque cela est nécessaire, ce qui évite les sondages inutiles.

Synchronisation complète

La première fois que votre application se connecte à Gmail, ou si la synchronisation partielle n'est pas disponible, vous devez effectuer une synchronisation complète. Lors d'une opération de synchronisation complète, votre application doit récupérer et stocker autant de messages ou de fils de discussion récents que nécessaire pour votre objectif. Par exemple, si votre application affiche une liste de messages récents, vous pouvez récupérer et mettre en cache suffisamment de messages pour permettre une interface réactive si l'utilisateur fait défiler la page au-delà des premiers messages affichés.

Pour effectuer une synchronisation complète, procédez comme suit :

1. Appelez la méthode messages.list pour récupérer la première page d'ID de messages.

2. Créez une requête par lot de messages.get requêtes de méthode pour chacun des messages renvoyés par la requête de liste.

   Si votre application affiche le contenu des messages, définissez le paramètre format sur format=full ou format=raw la première fois que votre application récupère un message, et mettez en cache les résultats pour éviter des opérations de récupération supplémentaires. Si vous récupérez un message précédemment mis en cache, utilisez format=minimal pour réduire la taille de la réponse, car seul labelIds peut changer.

3. Fusionnez les mises à jour dans vos résultats mis en cache. Votre application doit stocker le historyId du message le plus récent (le premier message de la réponse list) pour les futures synchronisations partielles.

Synchronisation partielle

Si votre application a été synchronisée récemment, vous pouvez effectuer une synchronisation partielle à l'aide de la méthode history.list pour renvoyer tous les enregistrements de l'historique plus récents que le paramètre de requête startHistoryId que vous devez spécifier dans votre requête.

Le paramètre de requête startHistoryId doit être défini sur le historyId d'un message récent. Pour récupérer le historyId d'un message récent, utilisez les méthodes messages.get ou messages.list. Vous pouvez également définir la valeur lors d'une synchronisation complète ou partielle pour une utilisation ultérieure.

L'objet History renvoyé inclut les ID des messages et le type de modification pour chaque message (par exemple, message ajouté ou libellés modifiés) depuis l'heure de startHistoryId fournie.

Limites

Les enregistrements de l'historique sont généralement disponibles pendant au moins une semaine, et souvent plus longtemps. Toutefois, la période pour laquelle les enregistrements sont disponibles peut être beaucoup plus courte, et il est possible que les enregistrements ne soient pas disponibles dans de rares cas.

Si le startHistoryId fourni par votre client se trouve en dehors de la plage disponible des enregistrements de l'historique, l'API Gmail renvoie une réponse d'erreur HTTP 404. Dans ce cas, votre client doit effectuer une synchronisation complète.