Method: users.watch

为指定用户邮箱设置或更新推送通知监听器。

HTTP 请求

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

网址采用 gRPC 转码语法。

路径参数

参数
userId

string

用户的电子邮件地址。特殊值 me 可用于表示经过身份验证的用户。

请求正文

请求正文中包含结构如下的数据：

JSON 表示法 
{
  "labelIds": [
    string
  ],
  "labelFilterAction": enum (LabelFilterAction),
  "labelFilterBehavior": enum (LabelFilterAction),
  "topicName": string
}
字段
labelIds[]

string

要限制通知的 labelId 列表。默认情况下，如果未指定，则会推送所有更改。如果指定了此参数，则表示生成推送通知所需的标签。
labelFilterAction
(deprecated)

enum (LabelFilterAction)

指定了 labelIds list 的过滤行为。此字段已弃用，因为它在某些情况下会导致错误行为；请改用 labelFilterBehavior。
labelFilterBehavior

enum (LabelFilterAction)

指定了 labelIds list 的过滤行为。此字段会替换 labelFilterAction；如果设置了此字段，系统会忽略 labelFilterAction。
topicName

string

用于发布事件的完全限定的 Google Cloud Pub/Sub API 主题名称。此主题名称必须已在 Cloud Pub/Sub 中存在，并且您必须已向 Gmail 授予该主题的“发布”权限。例如，“projects/my-project-identifier/topics/my-topic-name”（使用 Cloud Pub/Sub“v1”主题命名格式）。

请注意，“my-project-identifier”部分必须与您的 Google 开发者项目 ID（执行此手表请求的 ID）完全一致。

响应正文

推送通知手表回复。

如果成功，响应正文将包含结构如下的数据：

JSON 表示法 
{
  "historyId": string,
  "expiration": string
}
字段
historyId

string

相应邮箱的当前历史记录的 ID。
expiration

string (int64 format)

Gmail 将停止发送邮箱更新通知的时间（以纪元毫秒为单位）。请在此时间之前再次致电 watch 以续订手表。

授权范围

需要以下 OAuth 范围之一：

  • 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

如需了解详情，请参阅 OAuth 2.0 Overview。

LabelFilterAction

指定了 labelIds 列表的过滤行为。

枚举
include 仅针对与指定 labelIds 相关的消息更改接收推送通知。
exclude 针对所有消息更改（与指定 labelIds 相关的更改除外）接收推送通知。