本文說明如何使用 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 應將通知傳送至該主題。主題名稱可以是您在專案下選擇的任何名稱 (例如 matching-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 同步」。
此外，成功的 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 同步」一文所述。
舉例來說，您可以使用 history.list 方法，找出初始 watch 要求與收到上一個範例中分享的通知訊息之間發生的變更。將 1234567890 做為 history.list 傳遞至 startHistoryId。之後，您可以將 9876543210 持久儲存為最後已知的 historyId，以供日後使用。
如果您改為設定提取訂閱項目，請參閱 Cloud Pub/Sub 提取訂閱項目指南中的程式碼範例，進一步瞭解如何接收訊息。
根據通知內容採取行動
您必須確認所有通知。如果您使用 Webhook push delivery，成功回應 (例如 HTTP 200) 即表示確認收到通知。
如果您使用提取傳送 (REST 提取、RPC 提取或 RPC 串流提取)，則必須使用 REST 或 RPC 確認方法來確認訊息。如要進一步瞭解如何使用官方 RPC 型用戶端程式庫非同步或同步確認訊息，請參閱 Cloud Pub/Sub 提取訂閱項目指南中的程式碼範例。
如果未確認通知 (例如，Webhook 回呼傳回錯誤或逾時)，Cloud Pub/Sub 會在稍後重新傳送通知。
停止接收信箱更新通知
如要停止接收信箱的更新，請呼叫 stop 方法。所有新通知應會在幾分鐘內停止傳送。
限制
使用伺服器推送通知時，請注意下列限制：
通知頻率上限
每個受監控的 Gmail 使用者最多每秒會收到一個事件的通知。如果使用者通知超出該速率，服務就會捨棄。處理通知時，請小心不要觸發其他通知，以免啟動通知迴圈。
可靠性
通常，Cloud Pub/Sub 會在幾秒內傳送通知。不過，在極少數情況下，通知可能會延遲或遺失。請妥善處理這種情況，確保應用程式即使未收到推播訊息，仍能同步處理。舉例來說，如果使用者一段時間沒有收到通知，可以改為定期呼叫 history.list 方法。
Cloud Pub/Sub 限制
Cloud Pub/Sub API 也有自己的限制，詳情請參閱定價和配額說明文件。