在 Gmail API 中設定推播通知

本文說明如何在 Gmail API 中管理推播通知。

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 Cloud 控制台中列出的專案 ID)。

建立訂閱項目

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

授予主題的發布權限

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

如要這麼做，請將 publish 權限授予 gmail-api-push@system.gserviceaccount.com。如要執行這項操作，請按照存取權控管說明，在 Google Cloud 控制台中使用 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前處理變更，請參閱「將用戶端與 Gmail API 同步處理」。

此外，如果 watch 呼叫成功，系統會立即將通知傳送至 Cloud Pub/Sub 主題。

如果 watch 呼叫傳回錯誤，詳細資料應會說明問題來源。這通常是 Cloud Pub/Sub 主題和訂閱設定的問題。請參閱 Cloud Pub/Sub 說明文件，確認設定正確無誤，並取得主題和訂閱問題的偵錯協助。

更新信箱監控

您必須每 7 天至少呼叫一次 watch，否則將無法再接收使用者的更新。建議您每天呼叫 watch 一次。watch 方法的回應也會包含 expiration 欄位，其中含有 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以來所做的變更詳細資料，如「使用 Gmail API 同步處理用戶端」一文所述。

舉例來說，您可以使用 history.list 方法，找出初始 watch 要求與收到上一個範例中分享的通知訊息之間發生的變更。將 1234567890 做為 startHistoryId 傳遞至 history.list。之後，您可以將 9876543210 持久儲存為最後已知的 historyId，以供日後使用。

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

根據通知內容採取行動

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

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

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

停止信箱更新

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

限制

使用伺服器推播通知時，有下列限制：

通知頻率上限

每個受監控的 Gmail 使用者最多每秒會收到一個事件的通知。如果使用者通知超出這個速率，系統就會捨棄。處理通知時，請小心不要觸發其他通知，否則可能會啟動通知迴圈。

可靠性

通常所有通知都會在幾秒內可靠地送達，但有時通知可能會延遲或遺失。請妥善處理這種可能性，確保應用程式即使未收到推送訊息，仍能同步處理。舉例來說，如果使用者一段時間沒有收到通知，可以改為定期呼叫 history.list 方法。

Cloud Pub/Sub 限制

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