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 相關的異動除外。