Tổng quan
API Gmail cung cấp thông báo đẩy của máy chủ cho phép bạn theo dõi các thay đổi đối với hộp thư Gmail. Bạn có thể sử dụng tính năng này để cải thiện hiệu suất của ứng dụng. Tính năng này cho phép bạn loại bỏ các chi phí mạng và tính toán bổ sung liên quan đến việc thăm dò ý kiến các tài nguyên để xác định xem các tài nguyên đó có thay đổi hay không. Bất cứ khi nào một hộp thư thay đổi, API Gmail sẽ thông báo cho ứng dụng máy chủ phụ trợ của bạn.
Thiết lập Cloud Pub/Sub ban đầu
API Gmail sử dụng API Cloud Pub/Sub để phân phối thông báo đẩy. Điều này cho phép thông báo thông qua nhiều phương thức, bao gồm cả webhook và thăm dò ý kiến trên một điểm cuối của gói thuê bao.
Điều kiện tiên quyết
Để hoàn tất phần còn lại của quy trình thiết lập này, hãy đảm bảo bạn đáp ứng Các điều kiện tiên quyết của Cloud Pub/Sub, sau đó thiết lập ứng dụng Cloud Pub/Sub.
Tạo một chủ đề
Sử dụng ứng dụng Cloud Pub/Sub, hãy tạo chủ đề mà API Gmail sẽ gửi thông báo đến. Tên chủ đề có thể là bất kỳ tên nào bạn chọn trong dự án (tức là khớp với projects/myproject/topics/*, trong đó myproject là Mã dự án được liệt kê cho dự án của bạn trong Google Developers Console).
Tạo gói thuê bao
Làm theo Hướng dẫn dành cho người đăng ký Cloud Pub/Sub để thiết lập gói thuê bao cho chủ đề mà bạn đã tạo. Định cấu hình loại gói thuê bao thành một lệnh đẩy webhook (tức là lệnh gọi lại HTTP POST) hoặc lệnh kéo (tức là do ứng dụng của bạn khởi tạo). Đây là cách ứng dụng của bạn nhận được thông báo về nội dung cập nhật.
Cấp quyền phát hành trên chủ đề của bạn
Cloud Pub/Sub yêu cầu bạn cấp các đặc quyền cho Gmail để phát hành thông báo về chủ đề của bạn.
Để làm việc này, bạn cần cấp đặc quyền publish cho gmail-api-push@system.gserviceaccount.com. Bạn có thể thực hiện việc này bằng cách sử dụng giao diện quyền trong Cloud Pub/Sub Developer Console theo hướng dẫn kiểm soát quyền truy cập ở cấp tài nguyên.
Nhận thông tin cập nhật về hộp thư Gmail
Sau khi hoàn tất quá trình thiết lập ban đầu của Cloud Pub/Sub, hãy định cấu hình tài khoản Gmail để gửi thông báo về nội dung cập nhật hộp thư.
Yêu cầu xem
Để định cấu hình tài khoản Gmail nhằm gửi thông báo đến chủ đề Cloud Pub/Sub, bạn chỉ cần sử dụng ứng dụng Gmail API để gọi watch trên hộp thư của người dùng Gmail tương tự như mọi lệnh gọi API Gmail khác.
Để làm như vậy, hãy cung cấp tên chủ đề đã tạo ở trên và mọi tuỳ chọn khác trong yêu cầu watch, chẳng hạn như labels để lọc. Ví dụ: để nhận thông báo mỗi khi có thay đổi đối với Hộp thư đến:
Giao thức
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()
Xem phản hồi
Nếu yêu cầu watch thành công, bạn sẽ nhận được phản hồi như sau:
{
historyId: 1234567890
expiration: 1431990098200
}
với hộp thư hiện tại historyId cho người dùng. Tất cả thay đổi sau đó
historyId sẽ được thông báo cho ứng dụng của bạn. Nếu bạn cần xử lý các thay đổi trước historyId này, hãy tham khảo hướng dẫn đồng bộ hoá.
Ngoài ra, một lệnh gọi watch thành công sẽ khiến thông báo được gửi ngay đến chủ đề Cloud Pub/Sub của bạn.
Nếu bạn nhận được lỗi từ lệnh gọi watch, thông tin chi tiết sẽ giải thích nguồn gốc của vấn đề, thường là do cách thiết lập chủ đề và gói thuê bao Cloud Pub/Sub. Hãy tham khảo tài liệu về Cloud Pub/Sub để xác nhận rằng bạn đã thiết lập đúng cách và để được trợ giúp khắc phục sự cố về chủ đề và gói thuê bao.
Gia hạn tính năng xem hộp thư
Bạn phải gọi lại watch ít nhất mỗi 7 ngày một lần, nếu không, bạn sẽ ngừng nhận thông tin cập nhật về người dùng. Bạn nên gọi watch một lần mỗi ngày. Phản hồi watch cũng có trường hết hạn với dấu thời gian cho thời điểm hết hạn watch.
Nhận thông báo
Bất cứ khi nào có nội dung cập nhật hộp thư khớp với watch, ứng dụng của bạn sẽ nhận được thông báo mô tả nội dung thay đổi.
Nếu bạn đã định cấu hình gói thuê bao đẩy, thì thông báo webhook đến máy chủ của bạn sẽ tuân theo 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"
}
Nội dung POST HTTP là JSON và tải trọng thông báo thực tế của Gmail nằm trong trường message.data. Trường message.data đó là một chuỗi được mã hoá base64url giải mã thành một đối tượng JSON chứa địa chỉ email và mã nhận dạng nhật ký hộp thư mới cho người dùng:
{"emailAddress": "user@example.com", "historyId": "9876543210"}
Sau đó, bạn có thể sử dụng history.list để lấy thông tin chi tiết về thay đổi cho người dùng kể từ historyId được biết gần đây nhất của họ, theo hướng dẫn đồng bộ hoá.
Nếu bạn đã định cấu hình gói thuê bao kéo, hãy tham khảo các mã mẫu trong Hướng dẫn về gói thuê bao kéo của người đăng ký Cloud Pub/Sub để biết thêm thông tin chi tiết về cách nhận thông báo.
Phản hồi thông báo
Bạn cần xác nhận tất cả thông báo. Nếu bạn sử dụng cách phân phối thông báo đẩy qua webhook, thì việc phản hồi thành công (ví dụ: HTTP 200) sẽ xác nhận thông báo.
Nếu sử dụng phương thức phân phối kéo (REST Pull, RPC Pull hoặc RPC StreamingPull), thì bạn phải tiếp tục bằng lệnh gọi xác nhận (REST hoặc RPC). Hãy tham khảo các mã mẫu trong Hướng dẫn về tính năng kéo của người đăng ký Cloud Pub/Sub để biết thêm thông tin chi tiết về cách xác nhận tin nhắn không đồng bộ hoặc đồng bộ bằng cách sử dụng thư viện ứng dụng dựa trên RPC chính thức.
Nếu thông báo không được xác nhận (ví dụ: lệnh gọi lại webhook của bạn trả về lỗi hoặc hết thời gian chờ), Cloud Pub/Sub sẽ thử lại thông báo sau.
Dừng cập nhật hộp thư
Để ngừng nhận thông tin cập nhật về một hộp thư, hãy gọi stop và tất cả thông báo mới sẽ ngừng trong vòng vài phút.
Các điểm hạn chế
Tốc độ thông báo tối đa
Mỗi người dùng Gmail đang được theo dõi có tốc độ thông báo tối đa là 1 sự kiện/giây. Mọi thông báo của người dùng vượt quá tốc độ đó sẽ bị loại bỏ. Hãy cẩn thận khi xử lý thông báo để đảm bảo không kích hoạt thông báo khác, từ đó bắt đầu một vòng lặp thông báo.
Độ tin cậy
Thông thường, tất cả thông báo sẽ được phân phối một cách đáng tin cậy trong vòng vài giây; tuy nhiên, trong một số trường hợp cực đoan, thông báo có thể bị trì hoãn hoặc bị loại bỏ.
Hãy nhớ xử lý khả năng này một cách linh hoạt để ứng dụng vẫn đồng bộ hoá ngay cả khi không nhận được thông báo đẩy. Ví dụ: quay lại gọi định kỳ history.list sau một khoảng thời gian không có thông báo cho người dùng.
Giới hạn của Cloud Pub/Sub
API Cloud Pub/Sub cũng có những giới hạn riêng, được nêu chi tiết trong tài liệu về giá và hạn mức.