Sincronizzare i client con Gmail

Questo documento spiega come sincronizzare i client con 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 prima volta che il client si connette a Gmail e in rari scenari, devi eseguire una sincronizzazione completa. Se il tuo cliente ha eseguito la sincronizzazione di recente, la sincronizzazione parziale è un'alternativa leggera a una sincronizzazione completa. Puoi anche utilizzare le notifiche push per attivare la sincronizzazione parziale in tempo reale e solo quando necessario, evitando il polling non necessario.

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, puoi 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, imposta il parametro 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, utilizza format=minimal per ridurre le dimensioni della risposta, poiché potrebbe cambiare solo labelIds.

  3. Unisci gli aggiornamenti ai risultati memorizzati nella cache. La tua app deve memorizzare historyId del messaggio più recente (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 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 in cui è stato fornito startHistoryId.

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 più breve e, in 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 cliente deve eseguire una sincronizzazione completa.