Mantenere sincronizzato il client con Gmail è importante per la maggior parte degli scenari di applicazioni. Esistono due scenari generali: sincronizzazione completa e sincronizzazione parziale. La sincronizzazione completa è necessaria la prima volta che il client si connette a Gmail e in alcuni altri rari casi. Se il tuo client ha eseguito la sincronizzazione di recente, la sincronizzazione parziale è un'alternativa più leggera a una sincronizzazione completa. Puoi inoltre utilizzare le notifiche push per attivare una sincronizzazione parziale in tempo reale e solo quando necessario, evitando così polling inutili.
Sommario
Sincronizzazione completa
La prima volta che l'applicazione si connette a Gmail o se non è disponibile una sincronizzazione parziale, devi eseguire una sincronizzazione completa. In un'operazione di sincronizzazione completa, l'applicazione deve recuperare e archiviare tutti i messaggi o i thread più recenti necessari per il tuo scopo. Ad esempio, se la tua applicazione visualizza un elenco di messaggi recenti, potresti voler recuperare e memorizzare nella cache un numero sufficiente di messaggi per consentire un'interfaccia adattabile se l'utente scorre oltre i primi messaggi visualizzati. La procedura generale per eseguire un'operazione di sincronizzazione completa è la seguente:
- Chiama
messages.list
per recuperare la prima pagina degli ID messaggio. - Crea una richiesta batch di richieste
messages.get
per ciascuno dei messaggi restituiti dalla richiesta di elenco. Se l'applicazione visualizza contenuti di messaggi, devi utilizzareformat=FULL
oformat=RAW
la prima volta che l'applicazione recupera un messaggio e memorizza i risultati nella cache per evitare ulteriori operazioni di recupero. Se stai recuperando un messaggio memorizzato nella cache, devi utilizzareformat=MINIMAL
per ridurre le dimensioni della risposta, poiché sololabelIds
può cambiare. - Unisci gli aggiornamenti nei risultati memorizzati nella cache. L'applicazione deve archiviare l'elemento
historyId
del messaggio più recente (il primo messaggio nella rispostalist
) per una futura sincronizzazione parziale.
Sincronizzazione parziale
Se la tua applicazione è stata sincronizzata di recente, puoi eseguire una sincronizzazione parziale utilizzando il metodo history.list
per restituire tutti i record della cronologia più recenti rispetto al valore startHistoryId
specificato nella richiesta. I record della cronologia forniscono gli ID messaggio e il tipo di modifica per ciascun messaggio, ad esempio quello aggiunto o eliminato o le etichette modificate dal momento dell'startHistoryId
. Puoi ottenere e archiviare il historyId
dei messaggi più recenti di una sincronizzazione completa o parziale per fornire come startHistoryId
le future operazioni di sincronizzazione parziale.
Limitazioni
I record della cronologia sono in genere disponibili per almeno una settimana e spesso per più tempo. Tuttavia, il periodo di tempo per cui sono disponibili i record potrebbe essere notevolmente inferiore e in rari casi i record potrebbero non essere disponibili. Se
il startHistoryId
fornito dal tuo client non rientra nell'intervallo disponibile
di record della cronologia, l'API restituisce una risposta di errore HTTP 404
. In questo caso, il client deve eseguire una sincronizzazione completa come descritto nella sezione precedente.