Tài liệu này giải thích cách quản lý thông báo đẩy bằng Gmail API.
Gmail API cung cấp thông báo đẩy của máy chủ để bạn có thể 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 bạn nhận 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 Cloud Console).
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 đẩy webhook (tức là lệnh gọi lại HTTP POST) hoặc một 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 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 Google Cloud Console 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ẻ có giới hạn theo miền của tổ chức bạn 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 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ề 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 để được thông báo mỗi khi có thay đổi trong 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 một phản hồi như sau:
{
"historyId": "1234567890",
"expiration": "1431990098200"
}
Phản hồi này chứa historyId hộp thư 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 phần Đồng bộ hoá ứng dụng với Gmail.
Ngoài ra, một lệnh gọi watch thành công sẽ gửi ngay một thông báo đế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 đề. Đâ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 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.
Gia hạn tính năng theo dõi hộp thư
Bạn phải gọi phương thức watch ít nhất một lần mỗi 7 ngày, 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 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 đế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 của 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
historyId, như mô tả trong phần Đồng bộ hoá ứng dụng với 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 đã biết gần đây nhất historyId 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 thuê bao kéo 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 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 kéo, RPC kéo hoặc RPC kéo trực tuyến), bạn phải xác nhận các thông báo bằng phương thức 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 đăng ký) của 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 thư viện ứng dụng khách 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ờ), thì 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ần suất 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. Dịch vụ sẽ loại bỏ mọi thông báo người dùng vượt quá tốc độ đó. 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, Cloud Pub/Sub sẽ gửi thông báo trong vòng vài giây. Tuy nhiên, trong một số ít trường hợp, thông báo có thể bị trễ hoặc bị bỏ lỡ. Xử lý khả năng này một cách khéo léo để ứng dụng vẫn đồng bộ hoá ngay cả khi ứng dụng của bạn không nhận được thông báo đẩy. Ví dụ: quay lại việc định kỳ gọi phương thức history.list 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.