Clients mit Gmail synchronisieren

In diesem Dokument wird erläutert, wie Sie Clients mit der Gmail API synchronisieren.

Die Synchronisierung Ihres Clients mit Gmail ist für die meisten App-Szenarien wichtig. Es gibt zwei Synchronisierungsmethoden: Vollsynchronisierung und Teilsynchronisierung. Eine vollständige Synchronisierung ist erforderlich, wenn Ihr Client zum ersten Mal eine Verbindung zu Gmail herstellt, und in einigen anderen seltenen Fällen. Wenn Ihr Kunde vor Kurzem synchronisiert hat, ist die teilweise Synchronisierung eine ressourcenschonendere Alternative zur vollständigen Synchronisierung. Sie können auch Push-Benachrichtigungen verwenden, um die Teilsynchronisierung in Echtzeit und nur bei Bedarf auszulösen und so unnötiges Polling zu vermeiden.

Vollständige Synchronisierung

Wenn Ihre App zum ersten Mal eine Verbindung zu Gmail herstellt oder die teilweise Synchronisierung nicht verfügbar ist, müssen Sie eine vollständige Synchronisierung durchführen. Bei einer vollständigen Synchronisierung sollte Ihre App so viele der neuesten Nachrichten oder Threads wie für Ihren Zweck erforderlich abrufen und speichern. Wenn in Ihrer App beispielsweise eine Liste der letzten Nachrichten angezeigt wird, sollten Sie genügend Nachrichten abrufen und im Cache speichern, um eine reaktionsschnelle Benutzeroberfläche zu ermöglichen, wenn der Nutzer über die ersten angezeigten Nachrichten hinaus scrollt.

So führst du eine vollständige Synchronisierung durch:

  1. Rufen Sie die Methode messages.list auf, um die erste Seite mit Nachrichten-IDs abzurufen.

  2. Erstellen Sie eine Batchanfrage mit messages.get-Methodenanfragen für jede der von der Listenanfrage zurückgegebenen Nachrichten.

    Wenn in Ihrer App Nachrichteninhalte angezeigt werden, sollten Sie Format beim ersten Abrufen einer Nachricht durch Ihre App auf format=FULL oder format=RAW festlegen und die Ergebnisse im Cache speichern, um zusätzliche Abrufvorgänge zu vermeiden. Wenn Sie eine zuvor im Cache gespeicherte Nachricht abrufen, sollten Sie format=MINIMAL verwenden, um die Größe der Antwort zu reduzieren, da sich nur die labelIds ändern kann.

  3. Führen Sie die Aktualisierungen in Ihre im Cache gespeicherten Ergebnisse ein. Ihre App sollte die historyId der letzten Nachricht (der ersten Nachricht in der list-Antwort) für zukünftige partielle Synchronisierungen speichern.

Teilsynchronisierung

Wenn Ihre App vor Kurzem synchronisiert wurde, können Sie eine teilweise Synchronisierung mit der Methode history.list durchführen, um alle Verlaufsdatensätze zurückzugeben, die neuer als der Abfrageparameter startHistoryId sind, den Sie in Ihrer Anfrage angeben müssen.

Der Abfrageparameter startHistoryId muss auf die historyId einer aktuellen Nachricht gesetzt werden. Verwenden Sie die Methoden messages.get oder messages.list, um die historyId einer aktuellen Nachricht abzurufen. Sie können den Wert auch während einer vollständigen oder teilweisen Synchronisierung für die zukünftige Verwendung festlegen.

Das zurückgegebene History-Objekt enthält Nachrichten-IDs und den Typ der Änderung für jede Nachricht, z. B. „Nachricht hinzugefügt“ oder „Labels geändert“, seit dem Zeitpunkt des angegebenen startHistoryId.

Beschränkungen

Verlaufsaufzeichnungen sind in der Regel mindestens eine Woche und oft auch länger verfügbar. Der Zeitraum, für den Aufzeichnungen verfügbar sind, kann jedoch deutlich kürzer sein. In seltenen Fällen sind Aufzeichnungen möglicherweise nicht verfügbar.

Wenn der von Ihrem Client bereitgestellte startHistoryId außerhalb des verfügbaren Bereichs von Verlaufsdatensätzen liegt, gibt die Gmail API eine HTTP 404-Fehlerantwort zurück. In diesem Fall muss Ihr Kunde eine vollständige Synchronisierung durchführen.