Ü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 lassen sich die zusätzlichen Netzwerk- und Rechenkosten vermeiden, die durch das Abfragen von Ressourcen entstehen, um festzustellen, ob sie sich geändert haben. Jedes Mal, 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 sind Benachrichtigungen über verschiedene Methoden möglich, einschließlich Webhooks und Abfragen an einem einzigen Aboendpunkt.
Vorbereitung
Damit Sie die restliche Einrichtung abschließen können, müssen Sie die Voraussetzungen für Cloud Pub/Sub 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 beliebig sein. 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 dem Cloud Pub/Sub-Abonnentenleitfaden, um ein Abo für das von Ihnen erstellte Thema einzurichten. Konfigurieren Sie den Abotyp entweder als Webhook-Push (d.h. HTTP-POST-Callback) oder als Pull (d.h. von Ihrer App initiiert). So erhält Ihre Anwendung Benachrichtigungen zu Updates.
Veröffentlichungsrechte für das Thema gewähren
Für Cloud Pub/Sub müssen Sie Gmail-Berechtigungen erteilen, um Benachrichtigungen in Ihrem Thema zu veröffentlichen.
Dazu müssen Sie gmail-api-push@system.gserviceaccount.com publish-Berechtigungen gewähren. Sie können dies über die Berechtigungsoberfläche der Cloud Pub/Sub-Entwicklerkonsole tun. Folgen Sie dazu der Anleitung zur Zugriffssteuerung auf Ressourcenebene.
Updates für den Gmail-Posteingang erhalten
Nachdem die Ersteinrichtung von Cloud Pub/Sub abgeschlossen ist, konfigurieren Sie Gmail-Konten so, dass Benachrichtigungen bei Postfachaktualisierungen gesendet werden.
Wiedergabeanfrage
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 auf 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, nach dem gefiltert werden soll. So werden Sie beispielsweise immer benachrichtigt, 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 Smartwatch
Wenn die watch-Anfrage erfolgreich ist, erhalten Sie eine Antwort wie diese:
{
historyId: 1234567890
expiration: 1431990098200
}
mit dem aktuellen Postfach historyId des Nutzers. Alle Änderungen nach dem historyId werden an Ihren Kunden gesendet. Wenn Sie Änderungen vor diesem Datum historyId verarbeiten müssen, lesen Sie den Synchronisierungsleitfaden.
Außerdem sollte bei einem erfolgreichen watch-Aufruf sofort eine Benachrichtigung an Ihr Cloud Pub/Sub-Thema gesendet werden.
Wenn Sie beim watch-Aufruf einen Fehler erhalten, sollten die Details die Ursache des Problems erläutern. In der Regel liegt das Problem bei der Einrichtung des Cloud Pub/Sub-Themas und des Abos. In der Cloud Pub/Sub-Dokumentation finden Sie Informationen dazu, ob die Einrichtung korrekt ist, und Hilfe bei der Fehlerbehebung bei Problemen mit Themen und Abos.
Postfachbenachrichtigung verlängern
Du musst watch mindestens alle 7 Tage noch einmal aufrufen, da du sonst keine Updates mehr für den Nutzer erhältst. Wir empfehlen, watch einmal täglich anzurufen. Die watch-Antwort enthält außerdem ein Ablaufdatum mit dem Zeitstempel für das Ablaufdatum des watch.
Benachrichtigungen erhalten
Wenn ein Posteingang aktualisiert wird, der mit Ihrer watch übereinstimmt, wird Ihre Anwendung über die Änderung benachrichtigt.
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 tatsächliche 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 Mailbox-Verlaufs-ID für den Nutzer enthält:
{"emailAddress": "user@example.com", "historyId": "9876543210"}
Mit history.list können Sie dann die Änderungsdetails für den Nutzer ab seiner letzten bekannten Verlaufs-ID abrufen, wie im Synchronisierungsleitfaden beschrieben.
Wenn Sie stattdessen ein Pull-Abo konfiguriert haben, finden Sie in den Codebeispielen im Leitfaden zum Pull-Abonnieren von Cloud Pub/Sub weitere Informationen zum Empfangen von Nachrichten.
Auf Benachrichtigungen reagieren
Alle Benachrichtigungen müssen bestätigt werden. Wenn Sie die Push-Übermittlung mit Webhooks verwenden, wird die Benachrichtigung durch eine erfolgreiche Antwort (z.B. HTTP 200) bestätigt.
Wenn du die Pull-Zustellung verwendest (REST Pull, RPC Pull oder RPC StreamingPull), musst du einen Bestätigungsaufruf (REST oder RPC) senden. Weitere Informationen zum Bestätigen von Nachrichten entweder asynchron oder synchron mithilfe der offiziellen RPC-basierten Clientbibliotheken finden Sie in den Codebeispielen im Leitfaden zum Abrufen von Cloud Pub/Sub-Nachrichten.
Wenn die Benachrichtigungen nicht bestätigt werden (z.B. wenn Ihr Webhook-Callback einen Fehler zurückgibt oder die Zeitüberschreitung erreicht), versucht Cloud Pub/Sub, die Benachrichtigung zu einem späteren Zeitpunkt noch einmal zu senden.
Postfachupdates beenden
Wenn Sie keine Updates mehr für eine Mailbox erhalten möchten, wählen Sie stop. Alle neuen Benachrichtigungen sollten dann innerhalb weniger Minuten eingestellt werden.
Beschränkungen
Maximale Benachrichtigungsrate
Für jeden beobachteten Gmail-Nutzer gilt eine maximale Benachrichtigungsrate von 1 Ereignis pro Sekunde. Alle Nutzerbenachrichtigungen, die diese Rate überschreiten, werden gelöscht. Achten Sie beim Umgang mit Benachrichtigungen darauf, dass Sie keine weitere Benachrichtigung auslösen und dadurch eine Benachrichtigungsschleife starten.
Zuverlässigkeit
Normalerweise sollten alle Benachrichtigungen innerhalb weniger Sekunden zuverlässig zugestellt werden. In einigen extremen Situationen können Benachrichtigungen jedoch verzögert oder verworfen werden.
Achten Sie darauf, dass diese Möglichkeit ordnungsgemäß verarbeitet wird, damit die Anwendung auch dann synchronisiert wird, wenn keine Push-Nachrichten empfangen werden. Beispiel: Nach einem Zeitraum ohne Benachrichtigungen für einen Nutzer kann auf das regelmäßige Aufrufen von history.list zurückgegriffen werden.
Einschränkungen von Cloud Pub/Sub
Die Cloud Pub/Sub API hat auch eigene Einschränkungen, die in der Dokumentation zu Preisen und Kontingenten beschrieben sind.