Übersicht
Die Gmail API bietet Server-Push-Benachrichtigungen, mit denen Sie auf Änderungen an Gmail-Postfächern achten können. Sie können dieses Feature verwenden, um die Leistung Ihrer Anwendung zu verbessern. Auf diese Weise können Sie die zusätzlichen Netzwerk- und Computing-Kosten eliminieren, die mit Abfrageressourcen verbunden sind, um festzustellen, ob sie sich geändert haben. Jedes Mal, wenn sich ein Postfach ändert, benachrichtigt die Gmail API die Back-End-Serveranwendung.
Ersteinrichtung von Cloud Pub/Sub
Die Gmail API verwendet die Cloud Pub/Sub API, um Push-Benachrichtigungen zu senden. Benachrichtigungen sind über verschiedene Methoden möglich, einschließlich Webhooks und Abfragen an einem einzigen Aboendpunkt.
Voraussetzungen
Für den Rest dieser Einrichtung müssen Sie die Cloud Pub/Sub-Voraussetzungen erfüllen und anschließend einen Cloud Pub/Sub-Client einrichten.
Thema erstellen
Erstellen Sie das Thema an Ihren Cloud Pub/Sub-Client, an das die Gmail API Benachrichtigungen senden soll. Der Themenname kann ein beliebiger Name sein, den Sie unter 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).
Wir empfehlen, aufgrund von Cloud Pub/Sub-Limits für die Anzahl der Themen ein einzelnes Thema für alle Gmail API-Push-Benachrichtigungen für Ihre Anwendung zu verwenden.
Abo erstellen
Folgen Sie der Anleitung zum Cloud Pub/Sub-Abo, um ein Abo für das von Ihnen erstellte Thema einzurichten. Konfigurieren Sie den Abotyp entweder als Webhook-Push (z.B. HTTP POST-Callback) oder per Pull (d.h. durch Ihre App initiiert). So erhält Ihre Anwendung Benachrichtigungen über Updates.
Veröffentlichungsrechte für Ihr Thema erteilen
Für Cloud Pub/Sub müssen Sie Gmail-Berechtigungen gewähren, um Benachrichtigungen zu Ihrem Thema zu veröffentlichen.
Dazu müssen Sie gmail-api-push@system.gserviceaccount.com publish-Berechtigungen gewähren. Dazu können Sie die Berechtigungsoberfläche für Cloud Pub/Sub Developer Console gemäß der Anleitung zur Zugriffssteuerung auf Ressourcenebene verwenden.
Aktuelle Informationen zum Gmail-Postfach
Nachdem die Ersteinrichtung von Cloud Pub/Sub abgeschlossen ist, konfigurieren Sie Gmail-Konten so, dass Benachrichtigungen über Postfachaktualisierungen gesendet werden.
Anfrage ansehen
Wenn Sie Gmail-Konten zum Senden von Benachrichtigungen an Ihr Cloud Pub/Sub-Thema konfigurieren möchten, rufen Sie mit Ihrem Gmail API-Client einfach watch im 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 denen gefiltert werden soll. So können Sie beispielsweise festlegen, dass Sie bei jeder Änderung im 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"],
}
Python
request = {
'labelIds': ['INBOX'],
'topicName': 'projects/myproject/topics/mytopic'
}
gmail.users().watch(userId='me', body=request).execute()
Antwort ansehen
Wenn die Anfrage watch erfolgreich war, erhalten Sie eine Antwort wie diese:
{
historyId: 1234567890
expiration: 1431990098200
}
mit dem aktuellen Postfach historyId für den Nutzer. Alle Änderungen nach diesem historyId werden Ihrem Client benachrichtigt. Wenn Sie Änderungen vor diesem historyId verarbeiten müssen, lesen Sie die Synchronisierungsanleitung.
Außerdem sollte ein erfolgreicher watch-Aufruf bewirken, dass sofort eine Benachrichtigung an Ihr Cloud Pub/Sub-Thema gesendet wird.
Wenn Sie eine Fehlermeldung vom watch-Aufruf erhalten, sollten Sie in den Details die Ursache des Problems erklären. In der Regel ist das das Cloud Pub/Sub-Thema und -Abo. In der Cloud Pub/Sub-Dokumentation können Sie nachlesen, ob die Einrichtung korrekt ist, und Hilfe bei der Behebung von Problemen mit Themen und Abos erhalten.
Verlängerte Postfachuhr
Sie müssen watch mindestens alle 7 Tage noch einmal aufrufen, sonst werden Sie keine Updates mehr für den Nutzer erhalten. Wir empfehlen, watch einmal täglich aufzurufen. Die Antwort watch hat auch ein Ablauffeld mit dem Zeitstempel für den Ablauf (watch).
Benachrichtigungen erhalten
Jedes Mal, wenn ein Postfach aktualisiert wird, das mit watch übereinstimmt, 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 dem 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, das die E-Mail-Adresse und die neue Postfachverlaufs-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 dem letzten bekannten Verlaufs-ID gemäß dem Synchronisierungsleitfaden abzurufen.
Wenn Sie stattdessen ein Pull-Abo konfiguriert haben, finden Sie in den Codebeispielen in der Cloud Pub/Sub-Pull-Anleitung für Abonnenten weitere Informationen zum Empfang von Nachrichten.
Auf Benachrichtigungen reagieren
Du musst alle Benachrichtigungen bestätigen. Wenn Sie die Webhook-Zustellung mit Webhooks verwenden, wird die Benachrichtigung erfolgreich beantwortet, z.B. mit HTTP 200.
Wenn Sie die Pull-Zustellung (REST Pull, RPC Pull oder RPC StreamingPull) verwenden, müssen Sie einen nachfolgenden Aufruf zur Bestätigung (REST oder RPC) ausführen. Weitere Informationen zur Bestätigung von Nachrichten asynchron oder synchron mithilfe der offiziellen RPC-basierten Clientbibliotheken finden Sie in den Codebeispielen in der Cloud Pub/Sub-Pull-Anleitung für Abonnenten.
Wenn die Benachrichtigungen nicht bestätigt werden (z.B. wenn der Webhook-Callback einen Fehler zurückgibt oder eine Zeitüberschreitung auftritt), versucht Cloud Pub/Sub die Benachrichtigung später noch einmal.
Updates für Postfach beenden
Wenn Sie keine Updates mehr in einem Postfach erhalten möchten, rufen Sie stop auf. Alle neuen Benachrichtigungen sollten innerhalb weniger Minuten beendet werden.
Beschränkungen
Maximale Benachrichtigungsrate
Jeder überwachte Gmail-Nutzer hat eine maximale Benachrichtigungsrate von 1 Ereignis/Sekunde. Alle Nutzerbenachrichtigungen über dieser Rate werden gelöscht. Seien Sie bei der Verarbeitung von Benachrichtigungen vorsichtig, damit Sie keine weitere Benachrichtigung auslösen und so eine Benachrichtigungsschleife starten.
Zuverlässigkeit
Normalerweise sollten alle Benachrichtigungen binnen weniger Sekunden zuverlässig zugestellt werden. In einigen extremen Situationen können Benachrichtigungen jedoch verzögert oder gelöscht werden.
Achten Sie darauf, dass diese Möglichkeit reibungslos verarbeitet wird, damit die Anwendung auch dann synchronisiert wird, wenn keine Push-Nachrichten empfangen werden. Ein Beispiel dafür wäre, wenn history.list nach einem bestimmten Zeitraum ohne Benachrichtigungen für einen Nutzer regelmäßig aufgerufen wird.
Cloud Pub/Sub-Einschränkungen
Für die Cloud Pub/Sub API gelten außerdem eigene Einschränkungen, die in der jeweiligen Dokumentation zu Preisen und Kontingenten genauer erläutert werden.