Method: users.watch

Push-Benachrichtigungen für das angegebene Nutzerpostfach einrichten oder aktualisieren. Weitere Informationen finden Sie unter Push-Benachrichtigungen in der Gmail API konfigurieren.

HTTP-Anfrage

POST https://gmail.googleapis.com/gmail/v1/users/{userId}/watch

Die URL verwendet die Syntax der gRPC-Transcodierung.

Pfadparameter

Parameter
userId

string

Die E-Mail-Adresse des Nutzers. Mit dem Sonderwert me kann der authentifizierte Nutzer angegeben werden.

Anfragetext

Der Anfragetext enthält Daten mit folgender Struktur:

JSON-Darstellung 
{
  "labelIds": [
    string
  ],
  "labelFilterAction": enum (LabelFilterAction),
  "labelFilterBehavior": enum (LabelFilterAction),
  "topicName": string
}
Felder
labelIds[]

string

Liste der Label-IDs, für die Benachrichtigungen eingeschränkt werden sollen. Wenn nichts angegeben ist, werden standardmäßig alle Änderungen per Push-Benachrichtigung gesendet. Wenn dieser Parameter angegeben ist, wird festgelegt, welche Labels erforderlich sind, damit eine Push-Benachrichtigung generiert wird.
labelFilterAction
(deprecated)

enum (LabelFilterAction)

Filterverhalten der angegebenen labelIds list. Dieses Feld ist veraltet, da es in einigen Fällen zu falschem Verhalten geführt hat. Verwenden Sie stattdessen labelFilterBehavior.
labelFilterBehavior

enum (LabelFilterAction)

Filterverhalten der angegebenen labelIds list. Dieses Feld ersetzt labelFilterAction. Wenn es festgelegt ist, wird labelFilterAction ignoriert.
topicName

string

Vollständiger Name eines Google Cloud Pub/Sub API-Themas, in dem die Ereignisse veröffentlicht werden sollen. Dieser Themenname muss bereits in Cloud Pub/Sub vorhanden sein und Sie müssen Gmail bereits die Berechtigung zum Veröffentlichen in diesem Thema erteilt haben. Beispiel: „projects/my-project-identifier/topics/my-topic-name“ (mit dem Cloud Pub/Sub-Themenbenennungsformat „v1“).

Der Teil „my-project-identifier“ muss genau mit Ihrer Google-Entwicklerprojekt-ID übereinstimmen (der ID, mit der diese Überwachungsanfrage ausgeführt wird).

Antworttext

Antwort auf die Push-Benachrichtigungsüberwachung.

Bei Erfolg enthält der Antworttext Daten mit der folgenden Struktur:

JSON-Darstellung 
{
  "historyId": string,
  "expiration": string
}
Felder
historyId

string

Die ID des aktuellen Verlaufseintrags des Postfachs.
expiration

string (int64 format)

Zeitpunkt, zu dem Gmail keine Benachrichtigungen mehr für Postfachaktualisierungen sendet (Epochen-Millis). Rufen Sie vor diesem Zeitpunkt noch einmal watch auf, um die Überwachung zu verlängern.

Autorisierungsbereiche

Erfordert einen der folgenden OAuth-Bereiche:

  • https://mail.google.com/
  • https://www.googleapis.com/auth/gmail.modify
  • https://www.googleapis.com/auth/gmail.readonly
  • https://www.googleapis.com/auth/gmail.metadata

Weitere Informationen finden Sie im Autorisierungsleitfaden.

LabelFilterAction

Filterverhalten der angegebenen Liste der Label-IDs.

Enums
include Sie erhalten nur Push-Benachrichtigungen für Nachrichtenänderungen, die sich auf die angegebenen Label-IDs beziehen.
exclude Sie erhalten Push-Benachrichtigungen für alle Nachrichtenänderungen, außer für solche, die sich auf die angegebenen Label-IDs beziehen.