Tài liệu này giải thích cách quản lý thông báo đẩy trong Gmail API.
API Gmail cung cấp công nghệ đẩy của máy chủ cho phép bạn theo dõi những thay đổi đối với hộp thư Gmail. Hãy sử dụng tính năng này để cải thiện hiệu suất của ứng dụng. Việc này giúp loại bỏ chi phí mạng và chi phí tính toán bổ sung của các tài nguyên thăm dò để 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 bằng 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 quy trình thiết lập này, hãy đáp ứng các điều kiện tiên quyết của Cloud Pub/Sub, sau đó thiết lập một ứng dụng 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 (ví dụ: projects/myproject/topics/* trùng khớp, trong đó myproject là mã dự án được liệt kê cho dự án của bạn trong bảng điều khiển Cloud).
Tạo gói thuê bao
Để thiết lập gói thuê bao cho chủ đề mà bạn đã tạo, hãy làm theo hướng dẫn về Loại gói thuê bao Cloud Pub/Sub. Đị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 một yêu cầu 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 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 như vậy, hãy 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 bảng điều khiển quyền Cloud Pub/Sub trong bảng điều khiển Google Cloud bằng cách làm theo hướng dẫn kiểm soát quyền truy cập này.
Cấu hình chia sẻ bị hạn chế theo miền của tổ chức có thể ngăn bạn cấp quyền xuất bản. Để giải quyết vấn đề này, bạn có thể định cấu hình một trường hợp ngoại lệ cho tài khoản dịch vụ này.
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ề 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, hãy dùng ứng dụng Gmail API để gọi phương thức watch trên hộp thư người dùng Gmail. Điều này tương tự như mọi lệnh gọi API Gmail khác. Cung cấp tên chủ đề mà bạn đã tạo 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ụ: sử dụng yêu cầu sau để nhận thông báo bất cứ khi nào 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 câu trả lờ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 }
Phản hồi này chứa hộp thư historyId hiện tại của người dùng. Ứng dụng của bạn sẽ nhận được thông báo về mọi thay đổi sau ngày historyId. Nếu bạn cần xử lý các thay đổi trước ngày historyId, hãy tham khảo bài viết Đồng bộ hoá ứng dụng với API Gmail.
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ì thông tin chi tiết sẽ giải thích nguồn gốc của vấn đề. Đây thường là vấn đề với 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 chế độ thiết lập là chính xác và để được trợ giúp gỡ lỗi các vấn đề về chủ đề và gói thuê bao.
Gia hạn tính năng theo dõi hộp thư
Bạn phải gọi watch ít nhất một lần mỗi 7 ngày, 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 của phương thức watch cũng có một trường expiration có 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 đẩy, thì thông báo webhook gửi đế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, 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 phương thức history.list để nhận thông tin chi tiết về các thay đổi đối với người dùng kể từ lần gần nhất được biết
historyId, như mô tả trong phần Đồng bộ hoá ứng dụng với API Gmail.
Ví dụ: hãy sử dụng phương thức history.list để xác định những thay đổi xảy ra giữa yêu cầu watch ban đầu và việc nhận thông báo được chia sẻ trong ví dụ trước. Truyền 1234567890 làm startHistoryId đến history.list. Sau đó, bạn có thể duy trì 9876543210 dưới dạng historyId historyId đã biết 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 thuê bao kéo, hãy tham khảo các mẫu mã trong hướng dẫn về thuê bao kéo của Cloud Pub/Sub để biết thêm thông tin về cách nhận tin nhắn.
Trả lời các thông báo
Bạn phải 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 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), 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 pull subscriptions (kéo thông tin thuê bao) của Cloud Pub/Sub để biết thêm thông tin chi tiết về việc xác nhận thông báo 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 bạn không xác nhận các thông báo (ví dụ: nếu 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 một thời điểm khác.
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 phương thức stop. 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ế
Sau đây là những hạn chế khi làm việc với thông báo đẩy từ máy 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à một sự kiện mỗi giây. Mọi thông báo người dùng vượt quá tốc độ đó đều sẽ bị loại bỏ. Khi xử lý thông báo, hãy cẩn thận để không kích hoạt một thông báo khác. Điều này có thể 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 đều đượ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ị chậm trễ hoặc bị bỏ qua.
Xử lý trường hợp này một cách khéo léo để ứ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 phương thức history.list theo đị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 giới hạn của Cloud Pub/Sub
Cloud Pub/Sub API cũng có những hạn chế riêng, được trình bày chi tiết trong tài liệu về giá và hạn mức của API này.