Push-Benachrichtigungen in der Gmail API konfigurieren

In diesem Dokument wird erläutert, wie Push-Benachrichtigungen in der Gmail API verwaltet werden.

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. Sie macht die zusätzlichen Netzwerk- und Rechenkosten für das Abrufen von Ressourcen überflüssig, um festzustellen, ob sie sich geändert haben. Immer wenn sich ein Postfach ändert, benachrichtigt die Gmail API Ihre Backend-Serveranwendung.

Hinweis: Für Benachrichtigungen an Geräte im Besitz von Nutzern (z. B. installierte Apps, Mobilgeräte oder Browser) ist die Anleitung Synchronisieren von Clients mit der Gmail API weiterhin der empfohlene Ansatz zum Abrufen von Updates.

Erste Cloud Pub/Sub-Einrichtung

Die Gmail API verwendet die Cloud Pub/Sub API, um Push Benachrichtigungen zu senden. So können Benachrichtigungen mit verschiedenen Methoden gesendet werden, darunter Webhooks und Abrufe an einem einzelnen Abo-Endpunkt.

Vorbereitung

Führen Sie die Cloud Pub/Sub Voraussetzungen aus und richten Sie dann einen Cloud Pub/Sub-Client ein.

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 (z. B. passend zu projects/myproject/topics/*, wobei myproject die Projekt-ID ist, die für Ihr Projekt in der Google Cloud Console aufgeführt ist).

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 Abo-Typ entweder als Webhook-Push (d. h. ein HTTP-POST-Callback) oder als Pull (d. h. von Ihrer App initiiert). So erhält Ihre Anwendung Benachrichtigungen zu Updates.

Veröffentlichungsrechte für Ihr Thema gewähren

In Cloud Pub/Sub müssen Sie Gmail Berechtigungen gewähren, um Benachrichtigungen in Ihrem Thema zu veröffentlichen.

Gewähren Sie dazu die Berechtigung publish für [e-mail]. Sie können dies in der Cloud Pub/Sub-Berechtigungskonsole in der Google Cloud Console tun. Folgen Sie dazu dieser Anleitung zur Zugriffssteuerung.

Die eingeschränkte Domain -Freigabe -Konfiguration Ihrer Organisation verhindert möglicherweise, dass Sie Veröffentlichungsberechtigungen gewähren. Um dieses Problem zu beheben, können Sie eine Ausnahme für dieses Dienstkonto konfigurieren.

Gmail-Postfach-Updates erhalten

Nachdem die erste Cloud Pub/Sub-Einrichtung abgeschlossen ist, konfigurieren Sie Gmail-Konten so, dass Benachrichtigungen für Postfach-Updates gesendet werden.

Anfrage beobachten

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 die watch Methode für das Gmail-Nutzerpostfach auf. Dies ähnelt jedem anderen Gmail API-Aufruf. Geben Sie in Ihrer watch Anfrage den von Ihnen erstellten Themennamen und alle anderen Optionen an, z. B. labels zum Filtern. Mit der folgenden Anfrage werden Sie beispielsweise 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 beobachten

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

{ historyId: 1234567890 expiration: 1431990098200 }

Die Antwort enthält das aktuelle Postfach historyId für den Nutzer. Ihr Client erhält Benachrichtigungen für alle Änderungen nach dieser historyId. Wenn Sie Änderungen vor dieser historyId verarbeiten müssen, lesen Sie den Leitfaden Synchronisieren von Clients mit der Gmail API.

Außerdem wird bei einem erfolgreichen watch-Aufruf sofort eine Benachrichtigung an Ihr Cloud Pub/Sub-Thema gesendet.

Wenn Sie eine Fehlermeldung vom watch-Aufruf erhalten, sollten die Details die Ursache des Problems erläutern. In der Regel liegt ein Problem mit der Einrichtung des Cloud Pub/Sub-Themas und des Abos vor. In der Cloud Pub/Sub Dokumentation finden Sie Informationen dazu, wie Sie überprüfen können, ob die Einrichtung korrekt ist, und wie Sie Probleme mit Themen und Abos beheben können.

Postfach-Überwachung erneuern

Sie müssen watch mindestens einmal alle 7 Tage aufrufen, sonst erhalten Sie keine Updates mehr für den Nutzer. Wir empfehlen, watch einmal pro Tag aufzurufen. Die Antwort der Methode watch enthält auch das expiration Feld mit dem Zeitstempel für den Ablauf von watch.

Benachrichtigungen erhalten

Immer wenn ein Postfach-Update erfolgt, das mit Ihrer watch-Konfiguration ü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 einer 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 Postfach-Verlaufs-ID für den Nutzer enthält:

{"emailAddress": "[e-mail]", "historyId": "9876543210"}

Anschließend können Sie die history.list Methode verwenden, um die Details der Änderungen für den Nutzer seit seiner letzten bekannten historyIdabzurufen, wie im Leitfaden Synchronisieren von Clients mit der Gmail API beschrieben.

Verwenden Sie beispielsweise die history.list Methode, um Änderungen zu ermitteln, die zwischen Ihrer ersten watchAnfrage und dem dem Empfang der Benachrichtigung im vorherigen Beispiel aufgetreten sind. Übergeben Sie 1234567890 als startHistoryId an history.list. Anschließend können Sie 9876543210 als letzte bekannte historyId für zukünftige Anwendungsfälle speichern.

Wenn Sie stattdessen ein Pull-Abo konfiguriert haben, finden Sie in der Anleitung zu Cloud Pub/Sub's Pull-Abos weitere Informationen zum Empfangen von Nachrichten.

Auf Benachrichtigungen reagieren

Alle Benachrichtigungen müssen bestätigt werden. Wenn Sie die Webhook-Push Zustellung verwenden, wird die Benachrichtigung durch eine erfolgreiche Antwort (z. B. HTTP 200) bestätigt.

Wenn Sie die Pull-Zustellung verwenden (REST Pull, RPC Pull, oder RPC StreamingPull), müssen Sie einen Bestätigungsaufruf ausführen (REST oder RPC). In den Codebeispielen in der Anleitung zu Cloud Pub/Sub-Pull-Abos finden Sie weitere Informationen zum Bestätigen von Nachrichten entweder asynchron oder synchron mit den offiziellen RPC-basierten Clientbibliotheken.

Wenn Sie die Benachrichtigungen nicht bestätigen (z. B. wenn Ihr Webhook-Callback einen Fehler zurückgibt oder eine Zeitüberschreitung auftritt), versucht Cloud Pub/Sub, die Benachrichtigung zu einem späteren Zeitpunkt noch einmal zu senden.

Postfach-Updates beenden

Wenn Sie keine Updates mehr zu einem Postfach erhalten möchten, rufen Sie die stop Methode auf. Alle neuen Benachrichtigungen sollten innerhalb weniger Minuten beendet werden.

Beschränkungen

Die folgenden Beschränkungen gelten für die Arbeit mit Server-Push-Benachrichtigungen:

Maximale Benachrichtigungsrate

Für jeden überwachten Gmail-Nutzer gilt eine maximale Benachrichtigungsrate von einem Ereignis pro Sekunde. Alle Benachrichtigungen, die diese Rate überschreiten, werden verworfen. Achten Sie beim Verarbeiten von Benachrichtigungen darauf, keine weitere Benachrichtigung auszulösen, da dies zu einer Benachrichtigungsschleife führen kann.

Zuverlässigkeit

In der Regel werden alle Benachrichtigungen innerhalb weniger Sekunden zuverlässig zugestellt. In einigen extremen Fällen können sich Benachrichtigungen jedoch verzögern oder verworfen werden. Gehen Sie mit dieser Möglichkeit sorgfältig um, damit die Anwendung auch dann synchronisiert wird, wenn keine Push-Nachrichten empfangen werden. Sie können beispielsweise nach einer bestimmten Zeit ohne Benachrichtigungen für einen Nutzer regelmäßig die Methode history.list aufrufen.

Cloud Pub/Sub-Beschränkungen

Die Cloud Pub/Sub API unterliegt auch eigenen Beschränkungen, die in der Dokumentation zu Preisen und Kontingenten beschrieben werden.