推播通知

總覽

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 訂閱者指南的說明，設定您所建立主題的訂閱項目。將訂閱類型設為 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 取得使用者自上次已知 historyId 以來的變更詳細資料。

舉例來說，如要使用 history.list 找出初始 watch 呼叫與收到上一個範例中分享的通知訊息之間發生的變更，請將 1234567890 做為 startHistoryId 傳遞至 history.list。之後，9876543210 可做為最後已知的 historyId 保留，以供日後使用。

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

回覆通知

所有通知都必須確認。如果使用 Webhook 推送傳送，成功回應 (例如 HTTP 200) 即表示確認收到通知。

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

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

停止接收信箱更新通知

如要停止接收信箱的更新通知，請呼叫 stop，幾分鐘內就不會再收到任何新通知。

限制

通知頻率上限

每個受監控的 Gmail 使用者最多每秒會收到 1 個事件通知。如果使用者通知超過這個速率，系統就會捨棄。處理通知時請小心，以免觸發其他通知，進而啟動通知迴圈。

可靠性

通常所有通知都應在幾秒內可靠地傳送； 不過，在某些極端情況下，通知可能會延遲或遺失。 請務必妥善處理這種情況，確保應用程式即使未收到推播訊息，仍能同步處理。舉例來說，如果使用者一段時間未收到通知，則可改為定期呼叫 history.list。

Cloud Pub/Sub 限制

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