In diesem Dokument wird erläutert, wie Sie Push-Benachrichtigungen mit 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 Sie Benachrichtigungen über verschiedene Methoden empfangen, darunter Webhooks und Polling an einem einzelnen Abo-Endpunkt.
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 zu Ihrem Thema zu veröffentlichen.
Gewähren Sie dazu publish-Berechtigungen für gmail-api-push@system.gserviceaccount.com. 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 Sie die erste Cloud Pub/Sub-Einrichtung abgeschlossen haben, konfigurieren Sie Gmail-Konten, um Benachrichtigungen für 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. Das ist ähnlich wie bei 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 sich etwas im Posteingang ändert:
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 Hilfeartikel Clients mit Gmail 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 erneuern
Sie müssen die Methode watch mindestens einmal alle 7 Tage aufrufen, da Sie sonst keine Updates mehr für den Nutzer erhalten.
Wir empfehlen, watch einmal pro Tag 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 dem letzten bekannten
historyId abzurufen, wie unter Clients mit Gmail 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 Cloud Pub/Sub-Pull-Abos weitere Informationen zum Empfangen von Nachrichten.
Auf Benachrichtigungen reagieren
Sie müssen alle Benachrichtigungen bestätigen. Wenn Sie die Push-Übermittlung per 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-Streaming-Pull) verwenden, müssen Sie Nachrichten mit der REST- oder RPC-Bestätigungsmethode bestätigen. Weitere Informationen zum Bestätigen von Nachrichten mit den offiziellen RPC-basierten Clientbibliotheken asynchron oder synchron 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 ein 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. Der Dienst verwirft alle Nutzerbenachrichtigungen, die diese Rate überschreiten. Achten Sie beim Verarbeiten von Benachrichtigungen darauf, dass Sie keine weitere Benachrichtigung auslösen, da dies zu einer Benachrichtigungsschleife führen kann.
Zuverlässigkeit
Normalerweise stellt Cloud Pub/Sub Benachrichtigungen innerhalb weniger Sekunden zu. In seltenen Fällen kann es jedoch vorkommen, dass Benachrichtigungen verzögert oder verworfen werden. Gehen Sie mit dieser Möglichkeit sorgfältig um, damit die Anwendung weiterhin synchronisiert wird, auch wenn Ihre App keine Push-Benachrichtigungen empfängt. Rufen Sie beispielsweise nach einem Zeitraum ohne Benachrichtigungen für einen Nutzer regelmäßig die Methode history.list auf.
Cloud Pub/Sub-Einschränkungen
Die Cloud Pub/Sub API hat auch eigene Einschränkungen, die in der Preisdokumentation und der Dokumentation zu Kontingenten beschrieben werden.