Tổng quan
API Gmail cung cấp thông báo đẩy của máy chủ cho phép bạn chú ý đến những thay đổi đối với hộp thư của 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. Điều này cho phép bạn loại bỏ mạng bổ sung và tính toán chi phí liên quan đến các tài nguyên thăm dò ý kiến để xác định xem các tài nguyên đó có thay đổi hay không. Bất cứ khi nào hộp thư thay đổi, API Gmail sẽ thông báo cho ứng dụng máy chủ phụ trợ.
Thiết lập Cloud Pub/Sub ban đầu
API Gmail sử dụng API Cloud Pub/Sub để gửi thông báo đẩy. Điều này cho phép gửi thông báo qua nhiều phương thức, bao gồm cả webhook và cuộc thăm dò ý kiến về 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 Điều kiện tiên quyết về Cloud Pub/Sub, sau đó thiết lập máy khách Cloud Pub/Sub.
Tạo một chủ đề
Bằng cách sử dụng máy khách 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 của mình (chẳng hạn như 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).
Bạn nên sử dụng một chủ đề duy nhất cho mọi thông báo đẩy của API Gmail cho ứng dụng của mình, do các giới hạn của Cloud Pub/Sub về số lượng chủ đề.
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 theo chủ đề mà bạn đã tạo. Định cấu hình loại gói thuê bao là đẩy webhook (tức là lệnh gọi lại POST HTTP) hoặc kéo (tức là do ứng dụng của bạn bắt đầu). Đây là cách ứng dụng của bạn sẽ nhận thông báo về các bản 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 quyền của Gmail để xuất bản 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 của publish cho gmail-api-push@system.gserviceaccount.com. Bạn có thể thực hiện việc này thông qua 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.
Đang nhận thông tin cập nhật về hộp thư của Gmail
Sau khi hoàn tất quy trình thiết lập Cloud Pub/Sub ban đầu, hãy định cấu hình tài khoản Gmail để gửi thông báo về thông tin 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 API Gmail để 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ủ đề được tạo ở trên và mọi tuỳ chọn khác trong yêu cầu watch của bạn, chẳng hạn như labels để lọc. Ví dụ: để được thông báo bất cứ khi nào có thay đổi được thực hiện đố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ư:
{
historyId: 1234567890
expiration: 1431990098200
}
với hộp thư hiện tại historyId cho người dùng. Mọi thay đổi sau đó
historyId sẽ được thông báo cho khách hà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 lập tức đến chủ đề Cloud Pub/Sub của bạn.
Nếu bạn gặp 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à trong quá trình thiết lập chủ đề và gói thuê bao trên 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 về cách gỡ lỗi liên quan đến các vấn đề liên quan đến gói thuê bao cũng như chủ đề.
Đang gia hạn đồng hồ hộp thư
Bạn phải gọi lại watch ít nhất 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 cho 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ó một trường hết hạn với dấu thời gian hết hạn watch.
Nhận thông báo
Bất cứ khi nào có bản cập nhật hộp thư khớp với watch của bạn, ứng dụng của bạn sẽ nhận được thông báo mô tả thay đổi.
Nếu bạn đã định cấu hình gói thuê bao đẩy, thì thông báo webhook tới máy chủ 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 yêu cầu POST qua HTTP là JSON và tải trọng thông báo Gmail thực tế 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 đối tượng JSON chứa địa chỉ email và mã nhật ký hộp thư mới cho người dùng:
{"emailAddress": "user@example.com", "historyId": "9876543210"}
Sau đó, bạn có thể dùng history.list để lấy thông tin chi tiết về thay đổi cho người dùng kể từ mã nhật ký đã 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 lấy dữ liệu, hãy tham khảo các mã mẫu trong Hướng dẫn lấy người đăng ký Cloud Pub/Sub để biết thêm 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ả các thông báo. Nếu bạn sử dụng tính năng phân phối đẩy webhook, thì 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 theo dõi 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 lấy người đăng ký Cloud Pub/Sub để biết thêm thông tin về cách xác nhận thông báo không đồng bộ hoặc đồng bộ bằng thư viện ứng dụng chính thức dựa trên RPC.
Nếu thông báo không được xác nhận (ví dụ: lệnh gọi lại webhook 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 trên hộp thư, hãy gọi
stop và tất cả thông báo mới
sẽ dừng trong vòng vài phút.
Các điểm hạn chế
Tỷ lệ thông báo tối đa
Mỗi người dùng Gmail đang bị theo dõi có tỷ lệ 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 cao hơn tỷ lệ đó 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 một thông báo khác và do đó bắt đầu vòng lặp thông báo.
Độ tin cậy
Thông thường, tất cả các thông báo cần được gửi một cách ổn định trong vòng vài giây. Tuy nhiên, trong một số trường hợp nghiêm trọng, thông báo có thể bị trì hoãn hoặc bị bỏ qua.
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 nào. Ví dụ: quay lại gọi định kỳ history.list sau một khoảng thời gian mà không có thông báo nào cho người dùng.
Các giới hạn của Cloud Pub/Sub
API Cloud Pub/Sub cũng có các hạn chế riêng, cụ thể là được nêu chi tiết trong tài liệu về pricing và quotas.