推播通知

總覽

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 回呼) 或拉取 (即由應用程式啟動)。這樣一來，應用程式就能接收更新通知。

授予主題的發布權限

您必須授予 Gmail 權限，才能讓 Cloud Pub/Sub 針對您的主題發布通知。

為此，您必須將 publish 權限授予 gmail-api-push@system.gserviceaccount.com。您可以使用 Cloud Pub/Sub 開發人員控制台權限介面，按照資源層級存取權控管操作說明進行操作。

取得 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 編碼字串，會解碼為 JSON 物件，其中包含使用者的電子郵件地址和新的信箱記錄 ID：

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

接著，您可以使用 history.list 取得使用者自最後已知的歷程記錄 ID 以來的變更詳細資料，如同步處理指南所述。

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

回覆通知

所有通知都必須獲得確認。如果您使用 webhook 推送傳送，則成功回應 (例如 HTTP 200) 會確認通知。

如果使用提取提交 (REST 提取、RPC 提取或 RPC 串流提取)，則必須接著傳送確認呼叫 (REST 或 RPC)。如要進一步瞭解如何使用官方的 RPC 用戶端程式庫，以非同步或同步方式回應訊息，請參閱 Cloud Pub/Sub 訂閱者提取指南中的程式碼範例。

如果未收到通知 (例如 Webhook 回呼傳回錯誤或逾時)，Cloud Pub/Sub 會在稍後重新嘗試傳送通知。

停止信箱更新

如要停止接收信箱更新，請呼叫 stop，所有新通知應會在幾分鐘內停止。

限制

通知頻率上限

每位受監控的 Gmail 使用者，通知率上限為 1 個事件/秒。超過此上限的使用者通知會遭到捨棄。處理通知時請小心，確保不會觸發其他通知，進而啟動通知迴圈。

可靠性

通常，所有通知都應在幾秒內可靠地傳送；但在某些極端情況下，通知可能會延遲或遺失。請務必妥善處理這種可能性，讓應用程式即使未收到推播訊息，也能順利同步處理。例如，在一段時間內未向使用者發出通知後，改為定期呼叫 history.list。

Cloud Pub/Sub 限制

Cloud Pub/Sub API 也有自身的限制，詳情請參閱定價和配額說明文件。