推播通知

總覽

Gmail API 提供伺服器推播通知,可讓您注意 Gmail 信箱的異動情形。您可以使用這項功能來改善應用程式效能。如此一來,就能省去輪詢資源衍生的額外網路和運算費用,藉此判斷資源是否已變更。每當信箱變更時,Gmail API 都會通知後端伺服器應用程式。

Cloud Pub/Sub 初始設定

Gmail API 會使用 Cloud Pub/Sub API 發送推播通知。這可讓您透過各種方法接收通知,包括 Webhook,以及單一訂閱端點的輪詢功能。

必要條件

如要完成這項設定的其餘部分,請確認您符合 Cloud Pub/Sub 必要條件,然後設定 Cloud Pub/Sub 用戶端

建立主題

使用 Cloud Pub/Sub 用戶端建立 Gmail API 應傳送通知的主題。主題名稱可以是您在專案底下選擇的任何名稱 (也就是與 projects/myproject/topics/* 相符,其中 myproject 是 Google Developers Console 中針對專案列出的「專案 ID」)。

由於 Cloud Pub/Sub 對主題數量的限制,我們建議您為應用程式的所有 Gmail API 推播通知設定單一主題。

建立訂閱項目

請按照 Cloud Pub/Sub 訂閱者指南為您建立的主題設定訂閱項目。將訂閱類型設定為 Webhook 推送 (即 HTTP POST 回呼) 或提取 (即由應用程式啟動)。應用程式將採用這種方式接收更新通知。

授予主題的發布權限

Cloud Pub/Sub 會要求您授予 Gmail 權限,以便將通知發布至主題。

如要這麼做,您必須將 publish 權限授予 gmail-api-push@system.gserviceaccount.com。如要這麼做,請按照資源層級存取權控管操作說明使用 Cloud Pub/Sub Developer Console 權限介面進行操作。

取得 Gmail 信箱更新通知

初始 Cloud Pub/Sub 設定完成後,請將 Gmail 帳戶設為傳送信箱更新通知。

觀看請求

如要設定讓 Gmail 帳戶傳送通知至您的 Cloud Pub/Sub 主題,只需透過 Gmail API 用戶端,在 Gmail 使用者信箱上呼叫 watch,做法與任何其他 Gmail API 呼叫類似。方法是提供在上述步驟中建立的主題名稱,以及 watch 要求中的任何其他選項,例如用於篩選的 labels。舉例來說,如果想在收件匣有任何異動時收到通知:

通訊協定

POST "https://www.googleapis.com/gmail/v1/users/me/watch"
Content-type: application/json

{
  topicName: "projects/myproject/topics/mytopic",
  labelIds: ["INBOX"],
  labelFilterBehavior: "INCLUDE",
}

Python

request = {
  'labelIds': ['INBOX'],
  'topicName': 'projects/myproject/topics/mytopic',
  'labelFilterBehavior': 'INCLUDE'
}
gmail.users().watch(userId='me', body=request).execute()

觀看回覆

如果 watch 要求成功,您會收到類似下方的回應:

{
  historyId: 1234567890
  expiration: 1431990098200
}

使用者目前的信箱 (historyId)。historyId 之後的所有變更都會通知您的客戶。如果您需要在此 historyId之前處理變更,請參閱同步處理指南

此外,成功的 watch 呼叫應該會立即傳送通知至您的 Cloud Pub/Sub 主題。

如果您收到 watch 呼叫的錯誤訊息,詳細資料應說明問題來源,通常與 Cloud Pub/Sub 主題和訂閱的設定有關。請參閱 Cloud Pub/Sub 說明文件,確認設定正確無誤,以及協助您對主題和訂閱問題進行偵錯。

正在續購信箱手錶

您必須至少每 7 天重新呼叫 watch,否則將無法再收到使用者更新。建議每天呼叫 watch 一次。watch 回應還包含一個到期欄位,其中含有 watch 到期時間的時間戳記。

接收通知

每當發生與 watch 相符的信箱更新時,應用程式就會收到說明異動的通知訊息。

如果您設定了推送訂閱項目,則傳送至您伺服器的 Webhook 通知將符合 PubsubMessage

POST https://yourserver.example.com/yourUrl
Content-type: application/json

{
  message:
  {
    // This is the actual notification data, as base64url-encoded JSON.
    data: "eyJlbWFpbEFkZHJlc3MiOiAidXNlckBleGFtcGxlLmNvbSIsICJoaXN0b3J5SWQiOiAiMTIzNDU2Nzg5MCJ9",

    // This is a Cloud Pub/Sub message id, unrelated to Gmail messages.
    "messageId": "2070443601311540",

    // This is the publish time of the message.
    "publishTime": "2021-02-26T19:13:55.749Z",
  }

  subscription: "projects/myproject/subscriptions/mysubscription"
}

HTTP POST 主體為 JSON,而實際的 Gmail 通知酬載位於 message.data 欄位中。message.data 欄位是採用 Base64url 編碼的字串,會解碼成包含電子郵件地址和使用者新信箱記錄 ID 的 JSON 物件:

{"emailAddress": "user@example.com", "historyId": "9876543210"}

接著,您可以根據同步處理指南,使用 history.list 取得使用者上次已知記錄 Id 至今的變更詳細資料。

如果您改為設定了提取訂閱項目,請參閱 Cloud Pub/Sub 訂閱者提取指南中的程式碼範例,進一步瞭解如何接收訊息。

回應通知

所有通知都必須確認。如果您使用 Webhook 推送傳送,那麼成功回應 (例如 HTTP 200) 就會確認通知。

如果您使用提取傳遞 (REST PullRPC 提取RPC StreamingPull),則必須以確認呼叫 (RESTRPC) 進行後續處理。如要進一步瞭解如何透過非同步同步的方式,使用官方 RPC 型用戶端程式庫確認訊息,請參閱 Cloud Pub/Sub 訂閱者提取指南中的程式碼範例。

如未確認通知 (例如 Webhook 回呼傳回錯誤或逾時),Cloud Pub/Sub 會稍後重試通知。

停止接收信箱更新

如要停止接收信箱的最新動態,請呼叫 stop,所有新通知都應在幾分鐘內停止。

限制

通知頻率上限

每位正在觀看的 Gmail 使用者設定的通知速率上限為每秒 1 個事件。凡是超過這個速率的使用者通知,系統將捨棄這類通知。處理通知時請務必小心,以免不會觸發其他通知,進而啟動通知迴圈。

可靠性

一般來說,所有通知都應該在幾秒內可靠地傳送;不過在某些極端情況下,通知可能會延遲或捨棄。請務必妥善處理這種情況,確保即使未收到推送訊息,應用程式仍會保持同步。舉例來說,在一段時間內沒有使用者通知的情況下,改回定期呼叫 history.list

Cloud Pub/Sub 限制

Cloud Pub/Sub API 也有各自的限制,詳情請參閱相關pricingquotas說明文件。