Überblick
Die Gmail API bietet Server-Push-Benachrichtigungen, mit denen Sie Änderungen an den Gmail-Postfächern überwachen können. Mit dieser Funktion können Sie die Leistung Ihrer Anwendung verbessern. Sie können die zusätzlichen Netzwerk- und Rechenkosten für das Abfragen von Ressourcen vermeiden, um festzustellen, ob sie sich geändert haben. Wenn sich ein Postfach ändert, benachrichtigt die Gmail API Ihre Back-End-Serveranwendung.
Ersteinrichtung von Cloud Pub/Sub
Die Gmail API verwendet die Cloud Pub/Sub API, um Push-Benachrichtigungen zuzustellen. Dies ermöglicht Benachrichtigungen über eine Vielzahl von Methoden, einschließlich Webhooks und Abfragen an einem einzelnen Aboendpunkt.
Voraussetzungen
Für den Rest der Einrichtung müssen Sie die Cloud Pub/Sub-Voraussetzungen erfüllen und dann einen Cloud Pub/Sub-Client einrichten.
Thema erstellen
Erstellen Sie mit dem Cloud Pub/Sub-Client das Thema, an das die Gmail API Benachrichtigungen senden soll. Der Themenname kann ein beliebiger Name sein, den Sie in Ihrem Projekt auswählen (d.h. mit projects/myproject/topics/*, wobei myproject die Projekt-ID ist, die in der Google Developers Console für Ihr Projekt aufgeführt ist).
Aufgrund der Cloud Pub/Sub-Limits für die Themenanzahl empfehlen wir, für alle Gmail API-Push-Benachrichtigungen für Ihre Anwendung ein einzelnes Thema zu verwenden.
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- (von Ihrer App initiiert). So erhält deine Anwendung Benachrichtigungen für Updates.
Veröffentlichungsrechte für Ihr Thema gewähren
Für Cloud Pub/Sub müssen Sie Gmail-Berechtigungen zum Veröffentlichen von Benachrichtigungen zu Ihrem Thema erteilen.
Dazu müssen Sie gmail-api-push@system.gserviceaccount.com die Berechtigung publish erteilen. Verwenden Sie dazu die Berechtigungsoberfläche der Cloud Pub/Sub Developer Console und folgen Sie der Anleitung zur Zugriffssteuerung auf Ressourcenebene.
Updates für das Gmail-Postfach erhalten
Sobald die Ersteinrichtung von Cloud Pub/Sub abgeschlossen ist, konfigurieren Sie Gmail-Konten so, dass Benachrichtigungen für Postfachaktualisierungen gesendet werden.
Anfrage ansehen
Wenn Sie Gmail-Konten so konfigurieren möchten, dass Benachrichtigungen an Ihr Cloud Pub/Sub-Thema gesendet werden, können Sie mit Ihrem Gmail API-Client einfach watch für das Gmail-Postfach des Gmail-Nutzers aufrufen, ä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. So können Sie beispielsweise bei jeder Änderung am Posteingang benachrichtigt werden:
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 ansehen
Wenn die watch-Anfrage erfolgreich ist, erhalten Sie eine Antwort wie diese:
{
historyId: 1234567890
expiration: 1431990098200
}
durch das aktuelle Postfach historyId für den Nutzer. Alle Änderungen nach diesem Datum (historyId) werden an Ihren Kunden gesendet. Wenn Sie Änderungen vor diesem historyId verarbeiten müssen, finden Sie in der Synchronisierungsanleitung weitere Informationen.
Darüber hinaus sollte ein erfolgreicher watch-Aufruf dazu führen, dass sofort eine Benachrichtigung an Ihr Cloud Pub/Sub-Thema gesendet wird.
Wenn Sie beim Aufruf von watch einen Fehler erhalten, sollte in den Details die Ursache des Problems angegeben sein. Das liegt normalerweise bei der Einrichtung des Cloud Pub/Sub-Themas und -Abos. In der Cloud Pub/Sub-Dokumentation können Sie nachlesen, ob die Einrichtung korrekt ist, und Themen- und Aboprobleme beheben.
Briefkasten-Smartwatch wird verlängert
Sie müssen watch mindestens alle sieben Tage noch einmal aufrufen. Andernfalls erhalten Sie keine Benachrichtigungen mehr für den Nutzer. Wir empfehlen, watch einmal pro Tag aufzurufen. Die watch-Antwort enthält auch ein Ablauffeld mit dem Zeitstempel für den Ablauf watch.
Benachrichtigungen erhalten
Bei jeder Postfachaktualisierung, die Ihrem watch entspricht, erhält Ihre Anwendung eine Benachrichtigung, in der die Änderung beschrieben wird.
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 Nutzlast der Gmail-Benachrichtigung 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 Postfach-Verlaufs-ID für den Nutzer enthält:
{"emailAddress": "user@example.com", "historyId": "9876543210"}
Sie können dann history.list verwenden, um die Änderungsdetails für den Nutzer seit seiner letzten bekannten historyId gemäß Synchronisierungsanleitung abzurufen.
Wenn Sie stattdessen ein Pull-Abo konfiguriert haben, finden Sie in den Codebeispielen im Pull-Leitfaden für Cloud Pub/Sub-Abonnenten weitere Informationen zum Empfangen von Nachrichten.
Auf Benachrichtigungen reagieren
Alle Benachrichtigungen müssen bestätigt werden. Wenn Sie die Push-Bereitstellung eines Webhooks verwenden, wird die Benachrichtigung durch eine erfolgreiche Antwort (z.B. HTTP 200) bestätigt.
Wenn Sie die Pull-Zustellung (REST Pull, RPC Pull oder RPC StreamingPull) verwenden, müssen Sie anschließend einen Bestätigungsaufruf (REST oder RPC) senden. Weitere Informationen zum asynchronen oder synchronen Bestätigen von Nachrichten mit den offiziellen RPC-basierten Clientbibliotheken finden Sie in den Codebeispielen im Pull-Leitfaden für Cloud Pub/Sub-Abonnenten.
Wenn die Benachrichtigungen nicht bestätigt werden (z.B. wenn Ihr Webhook-Callback einen Fehler zurückgibt oder das Zeitlimit überschritten wird), wiederholt Cloud Pub/Sub die Benachrichtigung zu einem späteren Zeitpunkt.
Postfach-Updates beenden
Wenn Sie keine Benachrichtigungen mehr für ein Postfach erhalten möchten, rufen Sie stop auf. Alle neuen Benachrichtigungen sollten dann innerhalb weniger Minuten eingestellt werden.
Beschränkungen
Maximale Benachrichtigungsrate
Jeder beobachtete Gmail-Nutzer hat eine maximale Benachrichtigungsrate von 1 Ereignis pro Sekunde. Alle Nutzerbenachrichtigungen über dieser Rate werden verworfen. Gehen Sie beim Umgang mit Benachrichtigungen vorsichtig vor, damit keine weitere Benachrichtigung ausgelöst und eine Benachrichtigungsschleife gestartet wird.
Zuverlässigkeit
Normalerweise sollten alle Benachrichtigungen zuverlässig innerhalb weniger Sekunden gesendet werden. In extremen Situationen können Benachrichtigungen jedoch verzögert oder verworfen werden.
Achten Sie darauf, diese Möglichkeit angemessen zu nutzen, damit die Anwendung auch dann synchronisiert wird, wenn keine Push-Nachrichten empfangen werden. Beispiel: Sie können history.list nach einem Zeitraum ohne Benachrichtigungen für einen Nutzer regelmäßig aufrufen.
Einschränkungen bei Cloud Pub/Sub
Für die Cloud Pub/Sub API gelten außerdem bestimmte Einschränkungen, die in der Dokumentation zu pricing und quotas genauer beschrieben werden.