Push-Benachrichtigungen

Übersicht

Die Gmail API bietet Server-Push-Benachrichtigungen, mit denen Sie auf Änderungen an Gmail-Postfächern achten können. Mit dieser Funktion können Sie die Leistung Ihrer Anwendung verbessern. Sie können die zusätzlichen Netzwerk- und Rechenkosten für Abfrageressourcen eliminieren, um festzustellen, ob sie sich geändert haben. Jedes Mal, 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 zu senden. Dies ermöglicht Benachrichtigungen über verschiedene Methoden, einschließlich Webhooks und Abfragen auf einem einzelnen Aboendpunkt.

Voraussetzungen

Achten Sie darauf, dass Sie die Cloud Pub/Sub-Voraussetzungen erfüllen und dann einen Cloud Pub/Sub-Client einrichten, um den Rest dieser Einrichtung abzuschließen.

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 in Ihrem Projekt auswählen, z.B. projects/myproject/topics/*, wobei myproject die Projekt-ID ist, die für Ihr Projekt in der Google Developers Console aufgeführt ist.

Aufgrund der Cloud Pub/Sub-Limits für die Anzahl der Themen empfehlen wir, für alle Gmail API-Push-Benachrichtigungen 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 (z.B. HTTP POST-Callback) oder Pull (d.h. durch Ihre Anwendung initiiert). So erhält deine App Benachrichtigungen über Updates.

Veröffentlichungsrechte für dein Thema gewähren

Für Cloud Pub/Sub müssen Sie Gmail-Berechtigungen erteilen, um Benachrichtigungen zu Ihrem Thema zu veröffentlichen.

Dazu müssen Sie gmail-api-push@system.gserviceaccount.com Berechtigungen vom Typ publish gewähren. Dazu können Sie die Cloud Pub/Sub-Entwicklerkonsolenberechtigungskonsole verwenden (siehe Zugriffssteuerung auf Ressourcenebene).

Gmail-Postfach aktualisieren

Wenn 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, rufen Sie mit Ihrem Gmail API-Client einfach watch() im Gmail-Nutzerpostfach auf. 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 über jede Ä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"],
}

Python

request = {
  'labelIds': ['INBOX'],
  'topicName': 'projects/myproject/topics/mytopic'
}
gmail.users().watch(userId='me', body=request).execute()

Antwort ansehen

Wenn die Anfrage watch() erfolgreich ist, erhalten Sie eine Antwort wie die folgende:

{
  historyId: 1234567890
  expiration: 1431990098200
}

mit dem aktuellen Postfach historyId für den Nutzer. Alle Änderungen nach diesem historyId werden Ihrem Kunden mitgeteilt. Wenn Sie Änderungen vor diesem historyId verarbeiten müssen, lesen Sie die Anleitung zur Synchronisierung.

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 einen Fehler beim Aufruf von watch() erhalten, sollten die Details die Ursache des Problems erklären. Dies ist in der Regel auf die Einrichtung des Cloud Pub/Sub-Themas und -Abos zurückzuführen. In der Cloud Pub/Sub-Dokumentation erfahren Sie, ob die Einrichtung korrekt ist und wie Sie Probleme mit dem Thema und dem Abo beheben können.

Postfachuhr wird verlängert

Sie müssen watch() mindestens alle 7 Tage zurückrufen. Andernfalls erhalten Sie keine Updates mehr für den Nutzer. Wir empfehlen, watch() einmal täglich aufzurufen. Die Antwort watch() hat auch ein Feld mit dem Zeitstempel für den Ablauf von watch.

Benachrichtigungen erhalten

Wenn ein Postfach aktualisiert wird, das mit Ihrem 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 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-Textkörper 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 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 seiner letzten bekannten historyId gemäß dem Synchronisierungsleitfaden abzurufen.

Wenn Sie stattdessen ein Pull-Abo konfiguriert haben, finden Sie in den Codebeispielen im Cloud Pub/Sub-Pull-Leitfaden für Abonnenten weitere Informationen zum Empfangen von Nachrichten.

Auf Benachrichtigungen reagieren

Alle Benachrichtigungen müssen bestätigt werden. Wenn Sie die Push-Zustellung mit Webhook 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 einen Bestätigungsaufruf (REST oder RPC) senden. Weitere Informationen zur Bestätigung von Nachrichten asynchron oder synchron mithilfe der offiziellen RPC-basierten Clientbibliotheken finden Sie in den Codebeispielen im Pull-Leitfaden für Abonnenten von Cloud Pub/Sub.

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.

Postfach-Updates beenden

Wenn Sie keine Updates mehr in einem Postfach empfangen möchten, rufen Sie stop() auf. Alle neuen Benachrichtigungen sollten innerhalb weniger Minuten beendet 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. Seien Sie vorsichtig, wenn Sie Benachrichtigungen verwalten, damit Sie keine weitere Benachrichtigung auslösen und dadurch eine Benachrichtigungsschleife starten.

Zuverlässigkeit

Normalerweise sollten alle Benachrichtigungen innerhalb weniger Sekunden zugestellt werden. In einigen extremen Situationen können Benachrichtigungen jedoch verzögert oder verworfen werden. Achten Sie darauf, dass diese Möglichkeit reibungslos funktioniert, damit die Anwendung auch dann synchronisiert wird, wenn keine Push-Nachrichten empfangen werden. Sie können beispielsweise auf einen regelmäßigen Aufruf von history.list() nach einem Zeitraum ohne Benachrichtigungen für einen Nutzer zurückgreifen.

Cloud Pub/Sub-Einschränkungen

Für die Cloud Pub/Sub API gelten außerdem eigene Einschränkungen, die in der Dokumentation zu Preisen und Kontingenten genauer beschrieben werden.