In diesem Dokument wird beschrieben, wie Sie Push-Benachrichtigungen in der Gmail API verwalten.
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. Dadurch werden die zusätzlichen Netzwerk- und Rechenkosten für das Abrufen von Ressourcen vermieden, um festzustellen, ob sie sich geändert haben. Immer 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 können Benachrichtigungen über verschiedene Methoden wie Webhooks und Polling an einem einzigen Abo-Endpunkt empfangen werden.
Vorbereitung
Um diese Einrichtung abzuschließen, müssen Sie die Cloud Pub/Sub-Voraussetzungen 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 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 unter Cloud Pub/Sub-Abo-Typ, um ein Abo für das von Ihnen erstellte Thema einzurichten. Konfigurieren Sie den Abotyp entweder als Webhook-Push (d. h. als HTTP-POST-Callback) oder als Pull (d. h. als von Ihrer App initiierte Aktion). So erhält Ihre Anwendung Benachrichtigungen für Updates.
Veröffentlichungsrechte für das Thema gewähren
Für Cloud Pub/Sub müssen Sie Gmail die Berechtigung erteilen, Benachrichtigungen in Ihrem Thema zu veröffentlichen.
Dazu müssen Sie publish-Berechtigungen für gmail-api-push@system.gserviceaccount.com erteilen. Dazu können Sie die Cloud Pub/Sub-Berechtigungen in der Google Cloud Console verwenden. Folgen Sie dazu dieser Anleitung zur Zugriffssteuerung.
Die Konfiguration für das Teilen mit eingeschränkten Domains Ihrer Organisation verhindert möglicherweise, dass Sie Veröffentlichungsberechtigungen erteilen. Um dieses Problem zu beheben, können Sie eine Ausnahme für dieses Dienstkonto konfigurieren.
Updates zum Gmail-Posteingang erhalten
Nachdem die erste Einrichtung von Cloud Pub/Sub abgeschlossen ist, konfigurieren Sie Gmail-Konten, um Benachrichtigungen über Postfachaktualisierungen zu senden.
Smartwatch-Anfrage
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 Methode watch für das Gmail-Nutzerpostfach auf. Dies entspricht jedem anderen Gmail API-Aufruf. Geben Sie den Namen des erstellten Themas und alle anderen Optionen in Ihrer watch-Anfrage an, z. B. labels zum Filtern. Mit der folgenden Anfrage werden Sie beispielsweise benachrichtigt, wenn Änderungen am Posteingang vorgenommen 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 die folgende:
{ historyId: 1234567890 expiration: 1431990098200 }
Die Antwort enthält das aktuelle historyId-Objekt für das Postfach des Nutzers. Ihr Kunde erhält nach dem historyId Benachrichtigungen über alle Änderungen. Wenn Sie Änderungen vor diesem historyId verarbeiten müssen, lesen Sie den Abschnitt Clients mit der Gmail API synchronisieren.
Außerdem wird bei einem erfolgreichen watch-Aufruf sofort eine Benachrichtigung an Ihr Cloud Pub/Sub-Thema gesendet.
Wenn Sie einen Fehler vom watch-Aufruf erhalten, sollten die Details die Quelle des Problems erläutern. Das Problem liegt in der Regel an der Einrichtung des Cloud Pub/Sub-Themas und ‑Abos. In der Cloud Pub/Sub-Dokumentation finden Sie Informationen zur korrekten Einrichtung und zur Fehlerbehebung bei Problemen mit Themen und Abos.
Postfachüberwachung verlängern
Sie müssen watch mindestens einmal alle 7 Tage aufrufen, da Sie sonst keine Updates mehr für den Nutzer erhalten. Wir empfehlen, watch einmal täglich aufzurufen. Die Antwort der Methode watch enthält auch das Feld expiration mit dem Zeitstempel für den Ablauf von watch.
Benachrichtigungen erhalten
Immer wenn eine Postfachaktualisierung erfolgt, die mit Ihrem watch übereinstimmt, erhält Ihre Anwendung eine Benachrichtigung mit einer Beschreibung der Änderung.
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 eigentliche Gmail-Benachrichtigungsnutzlast befindet sich im Feld message.data. Das Feld message.data ist ein Base64URL-codierter String, der in ein JSON-Objekt mit der E-Mail-Adresse und der neuen Postfachverlaufs-ID für den Nutzer decodiert wird:
{"emailAddress": "user@example.com", "historyId": "9876543210"}
Anschließend können Sie die Methode history.list verwenden, um die Änderungsdetails für den Nutzer seit seinem letzten bekannten
historyId abzurufen, wie unter Clients mit der Gmail API synchronisieren beschrieben.
Verwenden Sie beispielsweise die Methode history.list, um Änderungen zu ermitteln, die zwischen Ihrer ursprünglichen watch-Anfrage und dem Empfang der im vorherigen Beispiel gezeigten Benachrichtigung aufgetreten sind. Übergeben Sie 1234567890 als startHistoryId an history.list. Anschließend können Sie 9876543210 als zuletzt bekannte historyId für zukünftige Anwendungsfälle speichern.
Wenn Sie stattdessen ein Pull-Abo konfiguriert haben, finden Sie in der Anleitung zu Pull-Abos 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 per Webhook verwenden, wird die Benachrichtigung durch eine erfolgreiche Antwort (z. B. HTTP 200) bestätigt.
Wenn Sie Pull-Zustellung verwenden (REST-Pull, RPC-Pull oder RPC-StreamingPull), müssen Sie einen Bestätigungsaufruf (REST oder RPC) ausführen. Weitere Informationen zum Bestätigen von Nachrichten entweder asynchron oder synchron mit den offiziellen RPC-basierten Clientbibliotheken finden Sie in den Codebeispielen in der Cloud Pub/Sub-Anleitung zu Pull-Abos.
Wenn Sie die Benachrichtigungen nicht bestätigen (z. B. wenn Ihr Webhook-Callback einen Fehler zurückgibt oder das Zeitlimit überschritten wird), 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 Methode stop auf. Alle neuen Benachrichtigungen sollten innerhalb weniger Minuten eingestellt werden.
Beschränkungen
Für die Arbeit mit Server-Push-Benachrichtigungen gelten die folgenden Einschränkungen:
Maximale Benachrichtigungsrate
Für jeden überwachten Gmail-Nutzer gilt eine maximale Benachrichtigungsrate von einem Ereignis pro Sekunde. Alle Nutzerbenachrichtigungen, 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
Normalerweise werden alle Benachrichtigungen innerhalb weniger Sekunden zuverlässig zugestellt. In einigen extremen Situationen kann es jedoch vorkommen, dass Benachrichtigungen verzögert 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. Rufen Sie beispielsweise die Methode history.list regelmäßig auf, nachdem ein Nutzer längere Zeit keine Benachrichtigungen erhalten hat.
Cloud Pub/Sub-Einschränkungen
Die Cloud Pub/Sub API unterliegt eigenen Einschränkungen, die in der Preisdokumentation und der Dokumentation zu Kontingenten beschrieben werden.