Garder votre client synchronisé avec Gmail est important pour la plupart des scénarios d'application. Il existe deux scénarios de synchronisation globaux: synchronisation complète et synchronisation partielle. Une synchronisation complète est nécessaire la première fois que votre client se connecte à Gmail, et dans certains autres rares scénarios. Si votre client s'est récemment synchronisé, la synchronisation partielle est une alternative plus légère à la synchronisation complète. Vous pouvez également utiliser les notifications push pour déclencher une synchronisation partielle en temps réel et uniquement si nécessaire, évitant ainsi des interrogations inutiles.
Sommaire
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 threads les plus récents que nécessaire. 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 responsive si l'utilisateur fait défiler la page au-delà des premiers messages affichés. La procédure générale pour effectuer une opération de synchronisation complète est la suivante:
- Appelez
messages.list
pour récupérer la première page des ID de message. - Créez une requête groupée de requêtes
messages.get
pour chacun des messages renvoyés par la requête "list". Si votre application affiche le contenu des messages, vous devez utiliserformat=FULL
ouformat=RAW
la première fois qu'elle récupère un message et met 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, vous devez utiliserformat=MINIMAL
pour réduire la taille de la réponse, car seullabelIds
peut changer. - 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éponselist
) pour une synchronisation partielle ultérieure.
Synchronisation partielle
Si votre application s'est récemment synchronisée, vous pouvez effectuer une synchronisation partielle à l'aide de la méthode history.list
pour renvoyer tous les enregistrements d'historique plus récents que le startHistoryId
que vous spécifiez dans votre requête. Les enregistrements d'historique fournissent les ID des messages et le type de modification pour chaque message (par exemple, les messages ajoutés, supprimés ou libellés modifiés depuis la date de startHistoryId
). Vous pouvez obtenir et stocker le historyId
du message le plus récent d'une synchronisation complète ou partielle pour le fournir en tant que startHistoryId
pour les futures opérations de synchronisation partielle.
Limites
Les enregistrements d'historique sont généralement disponibles pendant au moins une semaine, voire plus longtemps. Cependant, la période pendant laquelle les enregistrements sont disponibles peut être beaucoup plus courte et les enregistrements peuvent parfois être indisponibles dans de rares cas. Si la valeur startHistoryId
fournie par votre client se trouve en dehors de la plage disponible d'enregistrements d'historique, l'API renvoie une réponse d'erreur HTTP 404
. Dans ce cas, votre client doit effectuer une synchronisation complète, comme décrit dans la section précédente.