Tổng quan
Gmail API cung cấp thông báo đẩy của máy chủ để bạn có thể 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. Điều này giúp bạn loại bỏ các chi phí mạng và điện toán bổ sung liên quan đến việc thăm dò tài nguyên để xác định xem chúng có thay đổi hay không. Bất cứ khi nào hộp thư thay đổi, Gmail API 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
Gmail API sử dụng Cloud Pub/Sub API để gử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 đăng ký duy nhất.
Đ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 một máy khách Cloud Pub/Sub.
Tạo một chủ đề
Bằng cách sử dụng ứng dụng Cloud Pub/Sub, hãy tạo chủ đề mà Gmail API 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 (tức là trùng 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 một gói thuê bao cho chủ đề mà bạn đã tạo. Định cấu hình loại thuê bao thành một thông báo 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 sẽ nhận được 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 cho Gmail các đặc quyền để phát hành thông báo về chủ đề của bạn.
Để làm được 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 của 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 Cloud Pub/Sub ban đầu, hãy định cấu hình tài khoản Gmail để gửi thông báo về các 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 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ư người dùng Gmail tương tự như mọi lệnh gọi Gmail API khác.
Để thực hiện việc này, hãy cung cấp tên chủ đề bạn đã tạo ở trên và mọi lựa 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 bất cứ khi nào có thay đổi đối với hộp thư đến, hãy làm như sau:
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()
Phản hồi trên đồng hồ
Nếu yêu cầu watch thành công, bạn sẽ nhận được một phản hồi như sau:
{
historyId: 1234567890
expiration: 1431990098200
}
với hộp thư historyId hiện tại của người dùng. Mọi 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, 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 một 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 đề. Nguồn gốc này thường liên quan đến việc thiết lập chủ đề và gói thuê bao Cloud Pub/Sub. Tham khảo tài liệu Cloud Pub/Sub để xác nhận rằng bạn đã thiết lập đúng cách và để được trợ giúp gỡ lỗi các vấn đề về chủ đề và gói thuê bao.
Làm mới chế độ xem 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 được 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 của watch.
Nhận thông báo
Bất cứ khi nào có nội dung cập nhật hộp thư trùng khớp với watch, ứng dụng của bạn sẽ nhận được một thông báo mô tả nội dung thay đổi.
Nếu bạn đã định cấu hình một gói thuê bao thông báo đẩ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 HTTP POST 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. Chuỗi này sẽ 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 của người dùng:
{"emailAddress": "user@example.com", "historyId": "9876543210"}
Sau đó, bạn có thể sử dụng history.list để nhận thông tin chi tiết về thay đổi của người dùng kể từ historyId được biết gần đây nhất, theo hướng dẫn đồng bộ hoá.
Ví dụ: để dùng history.list nhằm xác định những thay đổi xảy ra giữa lệnh gọi watch ban đầu và việc nhận được thông báo được chia sẻ trong ví dụ trước, hãy truyền 1234567890 làm startHistoryId đến history.list.
Sau đó,9876543210 có thể được duy trì dưới dạng historyId được biết đến gần đây nhất cho các trường hợp sử dụng trong tương lai.
Nếu bạn đã định cấu hình một gói thuê bao kéo, hãy tham khảo các mẫu mã trong Hướng dẫn kéo dữ liệu 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 phương thức gửi thông báo đẩy bằng 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 lấy dữ liệu (Lấy dữ liệu bằng REST, Lấy dữ liệu bằng RPC hoặc Lấy dữ liệu bằng RPC StreamingPull), thì bạn phải thực hiện một lệnh gọi xác nhận (REST hoặc RPC). Hãy tham khảo các mẫu mã trong Hướng dẫn kéo của người đăng ký Cloud Pub/Sub để biết thêm thông tin chi tiết về việc xác nhận tin nhắn không đồng bộ hoặc đồng bộ bằng cách sử dụng các 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 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 vào lúc khác.
Ngừ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 xuất hiện 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 đượ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 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 mộ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 gử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 biệt, thông báo có thể bị trì hoãn hoặc bị bỏ qua.
Hãy nhớ xử lý trường hợp này một cách thích hợp để ứ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 history.list định kỳ sau một khoảng thời gian mà người dùng không nhận được thông báo.
Các hạn chế của Cloud Pub/Sub
Cloud Pub/Sub API 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.