Method: users.watch
Restez organisé à l'aide des collections
Enregistrez et classez les contenus selon vos préférences.
Configurez ou mettez à jour une surveillance des notifications push sur la boîte de réception de l'utilisateur donné.
Requête HTTP
POST https://gmail.googleapis.com/gmail/v1/users/{userId}/watch
L'URL utilise la syntaxe de transcodage gRPC.
Paramètres de chemin d'accès
| Paramètres |
userId |
string
Adresse e-mail de l'utilisateur. La valeur spéciale me peut être utilisée pour indiquer l'utilisateur authentifié.
|
Corps de la requête
Le corps de la requête contient des données présentant la structure suivante :
| Champs |
labelIds[] |
string
Liste des ID de libellé pour lesquels les notifications doivent être limitées. Par défaut, si aucun paramètre n'est spécifié, toutes les modifications sont appliquées. Si spécifié, indique les libellés requis pour qu'une notification push soit générée.
|
labelFilterAction
(deprecated) |
enum (LabelFilterAction)
Comportement de filtrage de labelIds list spécifié. Ce champ a été abandonné, car il entraînait un comportement incorrect dans certains cas. Utilisez plutôt labelFilterBehavior.
|
labelFilterBehavior |
enum (LabelFilterAction)
Comportement de filtrage de labelIds list spécifié. Ce champ remplace labelFilterAction. S'il est défini, labelFilterAction est ignoré.
|
topicName |
string
Nom de sujet de l'API Google Cloud Pub/Sub complet dans lequel publier les événements. Ce nom de sujet doit déjà exister dans Cloud Pub/Sub, et vous devez déjà avoir accordé à Gmail l'autorisation de "publier". Par exemple, "projects/mon-identifiant-de-projet/topics/mon-nom-de-sujet" (en utilisant le format de dénomination des sujets "v1" de Cloud Pub/Sub). Notez que la partie "my-project-identifier" doit correspondre exactement à l'ID de votre projet Google Developer (celui qui exécute cette requête de surveillance).
|
Corps de la réponse
Réponse de la montre à une notification push.
Si la requête aboutit, le corps de la réponse contient des données qui ont la structure suivante :
| Représentation JSON |
{
"historyId": string,
"expiration": string
} |
| Champs |
historyId |
string
ID de l'enregistrement d'historique actuel de la boîte de réception.
|
expiration |
string (int64 format)
Date à laquelle Gmail cessera d'envoyer des notifications pour les mises à jour de la boîte de réception (millisecondes de l'ère). Appelez watch avant cette heure pour renouveler la montre.
|
Champs d'application des autorisations
Nécessite l'un des champs d'application OAuth suivants :
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
Pour en savoir plus, consultez le guide d'autorisation.
LabelFilterAction
Comportement de filtrage de la liste "labelIds" spécifié.
| Enums |
include |
Ne recevoir des notifications push que pour les modifications de message liées aux ID de libellé spécifiés. |
exclude |
Recevez des notifications push pour toutes les modifications apportées aux messages, à l'exception de celles liées aux ID de libellé spécifiés. |
Sauf indication contraire, le contenu de cette page est régi par une licence Creative Commons Attribution 4.0, et les échantillons de code sont régis par une licence Apache 2.0. Pour en savoir plus, consultez les Règles du site Google Developers. Java est une marque déposée d'Oracle et/ou de ses sociétés affiliées.
Dernière mise à jour le 2025/07/25 (UTC).
[null,null,["Dernière mise à jour le 2025/07/25 (UTC)."],[],[],null,["# Method: users.watch\n\n- [HTTP request](#body.HTTP_TEMPLATE)\n- [Path parameters](#body.PATH_PARAMETERS)\n- [Request body](#body.request_body)\n - [JSON representation](#body.request_body.SCHEMA_REPRESENTATION)\n- [Response body](#body.response_body)\n - [JSON representation](#body.WatchResponse.SCHEMA_REPRESENTATION)\n- [Authorization scopes](#body.aspect)\n- [LabelFilterAction](#LabelFilterAction)\n\nSet up or update a push notification watch on the given user mailbox.\n\n### HTTP request\n\n`POST https://gmail.googleapis.com/gmail/v1/users/{userId}/watch`\n\nThe URL uses [gRPC Transcoding](https://google.aip.dev/127) syntax.\n\n### Path parameters\n\n| Parameters ||\n|----------|-----------------------------------------------------------------------------------------------------------|\n| `userId` | `string` The user's email address. The special value `me` can be used to indicate the authenticated user. |\n\n### Request body\n\nThe request body contains data with the following structure:\n\n| JSON representation |\n|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| ``` { \"labelIds\": [ string ], \"labelFilterAction\": enum (/workspace/gmail/api/reference/rest/v1/users/watch#LabelFilterAction), \"labelFilterBehavior\": enum (/workspace/gmail/api/reference/rest/v1/users/watch#LabelFilterAction), \"topicName\": string } ``` |\n\n| Fields ||\n|--------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `labelIds[]` | `string` List of labelIds to restrict notifications about. By default, if unspecified, all changes are pushed out. If specified then dictates which labels are required for a push notification to be generated. |\n| `labelFilterAction` **(deprecated)** | `enum (`[LabelFilterAction](/workspace/gmail/api/reference/rest/v1/users/watch#LabelFilterAction)`)` Filtering behavior of `labelIds list` specified. This field is deprecated because it caused incorrect behavior in some cases; use `labelFilterBehavior` instead. |\n| `labelFilterBehavior` | `enum (`[LabelFilterAction](/workspace/gmail/api/reference/rest/v1/users/watch#LabelFilterAction)`)` Filtering behavior of `labelIds list` specified. This field replaces `labelFilterAction`; if set, `labelFilterAction` is ignored. |\n| `topicName` | `string` A fully qualified Google Cloud Pub/Sub API topic name to publish the events to. This topic name **must** already exist in Cloud Pub/Sub and you **must** have already granted gmail \"publish\" permission on it. For example, \"projects/my-project-identifier/topics/my-topic-name\" (using the Cloud Pub/Sub \"v1\" topic naming format). Note that the \"my-project-identifier\" portion must exactly match your Google developer project id (the one executing this watch request). |\n\n### Response body\n\nPush notification watch response.\n\nIf successful, the response body contains data with the following structure:\n\n| JSON representation |\n|-------------------------------------------------------|\n| ``` { \"historyId\": string, \"expiration\": string } ``` |\n\n| Fields ||\n|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `historyId` | `string` The ID of the mailbox's current history record. |\n| `expiration` | `string (`[int64](https://developers.google.com/discovery/v1/type-format)` format)` When Gmail will stop sending notifications for mailbox updates (epoch millis). Call `watch` again before this time to renew the watch. |\n\n### Authorization scopes\n\nRequires one of the following OAuth scopes:\n\n- `https://mail.google.com/`\n- `\n https://www.googleapis.com/auth/gmail.modify`\n- `\n https://www.googleapis.com/auth/gmail.readonly`\n- `\n https://www.googleapis.com/auth/gmail.metadata`\n\nFor more information, see the [Authorization guide](/workspace/guides/configure-oauth-consent).\n\nLabelFilterAction\n-----------------\n\nFiltering behavior of labelIds list specified.\n\n| Enums ||\n|-----------|---------------------------------------------------------------------------------------------|\n| `include` | Only get push notifications for message changes relating to labelIds specified. |\n| `exclude` | Get push notifications for all message changes except those relating to labelIds specified. |"]]
