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

有关详情,请参阅授权指南

LabelFilterAction

指定的 labelId 列表的过滤行为。

枚举
include 仅在与指定的 labelId 相关的邮件变更时收到推送通知。
exclude 获取所有消息更改的推送通知,与指定的 labelId 相关的更改除外。