Übersicht
Die Gmail API bietet Server-Push-Benachrichtigungen, über die Sie auf Änderungen an Ihren Gmail-Postfächern achten können. Mit dieser Funktion können Sie die Leistung Ihrer Anwendung verbessern. So können Sie die zusätzlichen Netzwerk- und Rechenkosten vermeiden, die durch das Abrufen von Ressourcen entstehen, um festzustellen, ob sie sich geändert haben. Immer wenn sich ein Postfach ändert, benachrichtigt die Gmail API Ihre Backend-Serveranwendung.
Erste Cloud Pub/Sub-Einrichtung
Die Gmail API verwendet die Cloud Pub/Sub API, um Push-Benachrichtigungen zu senden. So können Benachrichtigungen über verschiedene Methoden erfolgen, z. B. über Webhooks und Polling an einem einzelnen Abo-Endpunkt.
Vorbereitung
Damit Sie die restliche Einrichtung abschließen können, müssen Sie die Cloud Pub/Sub-Voraussetzungen erfüllen und dann einen Cloud Pub/Sub-Client einrichten.
Thema erstellen
Erstellen Sie mit Ihrem Cloud Pub/Sub-Client das Thema, an das die Gmail API Benachrichtigungen senden soll. Der Themenname kann ein beliebiger Name sein, den Sie für Ihr Projekt auswählen (d.h. er muss mit projects/myproject/topics/* übereinstimmen, wobei myproject die Projekt-ID ist, die für Ihr Projekt in der Google Developers Console aufgeführt ist).
Abo erstellen
Folgen Sie der Cloud Pub/Sub-Abonnentenanleitung, um ein Abo für das von Ihnen erstellte Thema einzurichten. Konfigurieren Sie den Abotyp als Webhook-Push (d.h. HTTP-POST-Callback) oder Pull (d.h. von Ihrer App initiiert). So erhält Ihre Anwendung Benachrichtigungen für Updates.
Veröffentlichungsrechte für das Thema gewähren
Für Cloud Pub/Sub müssen Sie Gmail die Berechtigung erteilen, Benachrichtigungen in Ihrem Thema zu veröffentlichen.
Dazu müssen Sie gmail-api-push@system.gserviceaccount.com die Berechtigungen für publish gewähren. Dazu können Sie die Cloud Pub/Sub Developer Console-Berechtigungen verwenden und der Anleitung zur Zugriffssteuerung auf Ressourcenebene folgen.
Gmail-Posteingangsaktualisierungen erhalten
Nachdem die erste Einrichtung von Cloud Pub/Sub abgeschlossen ist, konfigurieren Sie Gmail-Konten so, dass Benachrichtigungen für Postfachaktualisierungen gesendet werden.
Anfrage zum Ansehen
Wenn Sie Gmail-Konten so konfigurieren möchten, dass Benachrichtigungen an Ihr Cloud Pub/Sub-Thema gesendet werden, rufen Sie einfach mit Ihrem Gmail API-Client watch für das Gmail-Nutzerpostfach auf, ähnlich wie bei jedem anderen Gmail API-Aufruf.
Geben Sie dazu den oben erstellten Themennamen und alle anderen Optionen in Ihrer watch-Anfrage an, z. B. labels zum Filtern. Wenn Sie beispielsweise jedes Mal benachrichtigt werden möchten, wenn eine Änderung am Posteingang vorgenommen wird:
Protokoll
POST "https://www.googleapis.com/gmail/v1/users/me/watch"
Content-type: application/json
{
topicName: "projects/myproject/topics/mytopic",
labelIds: ["INBOX"],
labelFilterBehavior: "INCLUDE",
}
Python
request = {
'labelIds': ['INBOX'],
'topicName': 'projects/myproject/topics/mytopic',
'labelFilterBehavior': 'INCLUDE'
}
gmail.users().watch(userId='me', body=request).execute()
Antwort auf der Smartwatch ansehen
Wenn die watch-Anfrage erfolgreich ist, erhalten Sie eine Antwort wie diese:
{
historyId: 1234567890
expiration: 1431990098200
}
mit dem aktuellen Postfach historyId für den Nutzer. Alle Änderungen nach dem historyId werden Ihrem Kunden mitgeteilt. Wenn Sie Änderungen vor diesem Datum historyId verarbeiten müssen, lesen Sie die Synchronisierungsanleitung.
Außerdem sollte ein erfolgreicher watch-Aufruf dazu führen, dass sofort eine Benachrichtigung an Ihr Cloud Pub/Sub-Thema gesendet wird.
Wenn Sie einen Fehler vom watch-Aufruf erhalten, sollten die Details die Quelle des Problems erläutern. Das Problem liegt in der Regel bei der Einrichtung des Cloud Pub/Sub-Themas und des Abos. In der Cloud Pub/Sub-Dokumentation finden Sie Informationen zur korrekten Einrichtung und zur Fehlerbehebung bei Problemen mit Themen und Abos.
Postfachüberwachung erneuern
Sie müssen watch mindestens alle 7 Tage noch einmal aufrufen, da Sie sonst keine Updates mehr für den Nutzer erhalten. Wir empfehlen, watch einmal pro Tag aufzurufen. Die watch-Antwort enthält auch ein Ablaufdatum mit dem Zeitstempel für den Ablauf von watch.
Benachrichtigungen erhalten
Immer wenn eine Postfachaktualisierung erfolgt, die mit Ihrem watch übereinstimmt, erhält Ihre Anwendung eine Benachrichtigung mit einer Beschreibung der Änderung.
Wenn Sie ein Push-Abo konfiguriert haben, entspricht eine Webhook-Benachrichtigung an Ihren Server einem PubsubMessage:
POST https://yourserver.example.com/yourUrl
Content-type: application/json
{
message:
{
// This is the actual notification data, as base64url-encoded JSON.
data: "eyJlbWFpbEFkZHJlc3MiOiAidXNlckBleGFtcGxlLmNvbSIsICJoaXN0b3J5SWQiOiAiMTIzNDU2Nzg5MCJ9",
// This is a Cloud Pub/Sub message id, unrelated to Gmail messages.
"messageId": "2070443601311540",
// This is the publish time of the message.
"publishTime": "2021-02-26T19:13:55.749Z",
}
subscription: "projects/myproject/subscriptions/mysubscription"
}
Der HTTP-POST-Text ist JSON und die eigentliche Gmail-Benachrichtigungsnutzlast befindet sich im Feld message.data. Das Feld message.data ist ein base64url-codierter String, der in ein JSON-Objekt decodiert wird, das die E-Mail-Adresse und die neue Verlaufs-ID des Postfachs für den Nutzer enthält:
{"emailAddress": "user@example.com", "historyId": "9876543210"}
Anschließend können Sie history.list verwenden, um die Änderungsdetails für den Nutzer seit seiner letzten bekannten historyId abzurufen, wie im Synchronisierungsleitfaden beschrieben.
Wenn Sie beispielsweise history.list verwenden möchten, um Änderungen zu ermitteln, die zwischen Ihrem ursprünglichen watch-Aufruf und dem Empfang der im vorherigen Beispiel gezeigten Benachrichtigung aufgetreten sind, übergeben Sie 1234567890 als startHistoryId an history.list.
Anschließend kann 9876543210 als zuletzt bekannte historyId für zukünftige Anwendungsfälle gespeichert werden.
Wenn Sie stattdessen ein Pull-Abo konfiguriert haben, finden Sie weitere Informationen zum Empfangen von Nachrichten in den Codebeispielen im Cloud Pub/Sub Subscriber Pull Guide.
Auf Benachrichtigungen reagieren
Alle Benachrichtigungen müssen bestätigt werden. Wenn Sie die Push-Zustellung per Webhook verwenden, wird die Benachrichtigung durch eine erfolgreiche Antwort (z.B. HTTP 200) bestätigt.
Wenn Sie die Pull-Übermittlung verwenden (REST Pull, RPC Pull oder RPC StreamingPull), müssen Sie mit einem Bestätigungsaufruf (REST oder RPC) nachziehen. Weitere Informationen zum asynchronen oder synchronen Bestätigen von Nachrichten mit den offiziellen RPC-basierten Clientbibliotheken finden Sie in den Codebeispielen im Cloud Pub/Sub-Abonnenten-Pull-Leitfaden.
Wenn die Benachrichtigungen nicht bestätigt werden (z.B. wenn Ihr Webhook-Callback einen Fehler zurückgibt oder ein Zeitlimit überschritten wird), versucht Cloud Pub/Sub, die Benachrichtigung zu einem späteren Zeitpunkt noch einmal zu senden.
Postfachaktualisierungen beenden
Wenn Sie keine Updates mehr zu einem Postfach erhalten möchten, rufen Sie stop an. Alle neuen Benachrichtigungen sollten innerhalb weniger Minuten eingestellt werden.
Beschränkungen
Maximale Benachrichtigungsrate
Für jeden überwachten Gmail-Nutzer gilt eine maximale Benachrichtigungsrate von 1 Ereignis pro Sekunde. Alle Benachrichtigungen über dieser Rate werden verworfen. Gehen Sie beim Verarbeiten von Benachrichtigungen vorsichtig vor, damit Sie keine weitere Benachrichtigung auslösen und so eine Benachrichtigungsschleife starten.
Zuverlässigkeit
Normalerweise sollten alle Benachrichtigungen innerhalb weniger Sekunden zuverlässig zugestellt werden. In einigen extremen Situationen können sich Benachrichtigungen jedoch verzögern oder verworfen werden.
Achten Sie darauf, dass diese Möglichkeit ordnungsgemäß behandelt wird, damit die Anwendung auch dann synchronisiert wird, wenn keine Push-Nachrichten empfangen werden. Beispiel: Wenn ein Nutzer eine Weile keine Benachrichtigungen erhalten hat, kann die App beispielsweise regelmäßig history.list aufrufen.
Cloud Pub/Sub-Einschränkungen
Die Cloud Pub/Sub API hat auch eigene Einschränkungen, die in der Preisdokumentation und Kontingentdokumentation beschrieben werden.