Sincronizzare i client con Gmail

Questo documento spiega come sincronizzare i client utilizzando l'API Gmail.

Mantenere sincronizzato il client con Gmail è importante per la maggior parte degli scenari delle app. Esistono due metodi di sincronizzazione: la sincronizzazione completa e la sincronizzazione parziale. La sincronizzazione completa è necessaria la prima volta che il client si connette a Gmail e in alcuni altri rari scenari. Se il client è stato sincronizzato di recente, la sincronizzazione parziale è un'alternativa più leggera a una sincronizzazione completa. Puoi anche utilizzare le notifiche push per attivare la sincronizzazione parziale in tempo reale e solo quando necessario, evitando così il polling inutile.

Sincronizzazione completa

La prima volta che la tua app si connette a Gmail o se la sincronizzazione parziale non è disponibile, devi eseguire una sincronizzazione completa. In un'operazione di sincronizzazione completa, l'app deve recuperare e archiviare il maggior numero possibile di messaggi o thread più recenti necessari per lo scopo. Ad esempio, se la tua app mostra un elenco di messaggi recenti, potresti voler recuperare e memorizzare nella cache un numero sufficiente di messaggi per consentire un'interfaccia reattiva se l'utente scorre oltre i primi messaggi visualizzati.

Per eseguire una sincronizzazione completa:

  1. Chiama il metodo messages.list per recuperare la prima pagina di ID messaggio.

  2. Crea una richiesta batch di messages.get richieste di metodo per ciascuno dei messaggi restituiti dalla richiesta di elenco.

    Se la tua app mostra i contenuti dei messaggi, devi impostare Format su format=FULL o format=RAW la prima volta che la tua app recupera un messaggio e memorizza nella cache i risultati per evitare ulteriori operazioni di recupero. Se stai recuperando un messaggio memorizzato nella cache in precedenza, devi utilizzare format=MINIMAL per ridurre le dimensioni della risposta, poiché solo labelIds potrebbe cambiare.

  3. Unisci gli aggiornamenti ai risultati memorizzati nella cache. La tua app deve memorizzare historyId dell'ultimo messaggio (il primo messaggio nella risposta list) per le sincronizzazioni parziali future.

Sincronizzazione parziale

Se la tua app è stata sincronizzata di recente, puoi eseguire una sincronizzazione parziale utilizzando il metodo history.list per restituire tutti i record della cronologia più recenti del parametro di query startHistoryId che devi specificare nella richiesta.

Il parametro di query startHistoryId deve essere impostato sul valore historyId di un messaggio recente. Per recuperare l'historyId di un messaggio recente, utilizza i metodi messages.get o messages.list. Puoi anche impostare il valore durante una sincronizzazione completa o parziale per un utilizzo futuro.

L'oggetto History restituito include gli ID messaggio e il tipo di modifica per ogni messaggio, ad esempio messaggio aggiunto o etichette modificate, a partire dal momento del startHistoryId fornito.

Limitazioni

I record della cronologia sono in genere disponibili per almeno una settimana e spesso più a lungo. Tuttavia, il periodo di tempo per il quale i record sono disponibili potrebbe essere notevolmente inferiore e, in alcuni rari casi, i record potrebbero non essere disponibili.

Se il valore startHistoryId fornito dal client non rientra nell'intervallo disponibile dei record della cronologia, l'API Gmail restituisce una risposta di errore HTTP 404. In questo caso, il tuo cliente deve eseguire una sincronizzazione completa.