Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang
Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Việc giữ cho ứng dụng của bạn được đồng bộ hoá với Gmail là điều quan trọng đối với hầu hết các trường hợp ứng dụng. Có 2 trường hợp đồng bộ hoá tổng thể: đồng bộ hoá toàn bộ và đồng bộ hoá một phần. Bạn phải đồng bộ hoá toàn bộ vào lần đầu tiên ứng dụng của bạn kết nối với Gmail và trong một số trường hợp hiếm gặp khác. Nếu gần đây ứng dụng của bạn đã đồng bộ hoá, thì đồng bộ hoá một phần là một giải pháp thay thế có trọng lượng nhẹ hơn cho đồng bộ hoá đầy đủ. Bạn cũng có thể sử dụng thông báo đẩy để kích hoạt quá trình đồng bộ hoá một phần theo thời gian thực và chỉ khi cần thiết, nhờ đó tránh được việc thăm dò ý kiến không cần thiết.
Nội dung
Đồng bộ hoá toàn bộ
Lần đầu tiên ứng dụng của bạn kết nối với Gmail hoặc nếu không có tính năng đồng bộ hoá một phần, bạn phải thực hiện đồng bộ hoá toàn bộ. Trong thao tác đồng bộ hoá đầy đủ, ứng dụng của bạn sẽ truy xuất và lưu trữ nhiều tin nhắn hoặc luồng gần đây nhất khi cần thiết cho mục đích của bạn. Ví dụ: nếu ứng dụng của bạn hiển thị danh sách các tin nhắn gần đây, bạn có thể muốn truy xuất và lưu vào bộ nhớ đệm đủ số lượng tin nhắn để cho phép giao diện phản hồi nếu người dùng cuộn qua vài tin nhắn đầu tiên được hiển thị. Quy trình chung để thực hiện thao tác đồng bộ hoá đầy đủ như sau:
Gọi messages.list để truy xuất trang đầu tiên của mã nhận dạng tin nhắn.
Tạo một yêu cầu hàng loạt gồm các yêu cầu messages.get cho từng thông báo do yêu cầu danh sách trả về. Nếu ứng dụng của bạn hiển thị nội dung tin nhắn, bạn nên sử dụng format=FULL hoặc format=RAW vào lần đầu tiên ứng dụng truy xuất một tin nhắn và lưu kết quả vào bộ nhớ đệm để tránh các thao tác truy xuất bổ sung. Nếu đang truy xuất một thông báo đã lưu vào bộ nhớ đệm trước đó, bạn nên sử dụng format=MINIMAL để giảm kích thước của phản hồi vì chỉ labelIds mới có thể thay đổi.
Hợp nhất nội dung cập nhật vào kết quả được lưu vào bộ nhớ đệm. Ứng dụng của bạn nên lưu trữ historyId của tin nhắn gần đây nhất (tin nhắn đầu tiên trong phản hồi list) để đồng bộ hoá một phần trong tương lai.
Đồng bộ hoá một phần
Nếu ứng dụng của bạn đã đồng bộ hoá gần đây, bạn có thể thực hiện đồng bộ hoá một phần bằng phương thức history.list để trả về tất cả các bản ghi nhật ký mới hơn startHistoryId mà bạn chỉ định trong yêu cầu. Nhật ký cung cấp mã thông báo và loại thay đổi cho từng thông báo, chẳng hạn như thông báo được thêm, bị xoá hoặc nhãn được sửa đổi kể từ thời điểm startHistoryId. Bạn có thể lấy và lưu trữ historyId của thông báo gần đây nhất từ một quy trình đồng bộ hoá toàn bộ hoặc một phần để cung cấp dưới dạng startHistoryId cho các thao tác đồng bộ hoá một phần trong tương lai.
Các điểm hạn chế
Các bản ghi nhật ký thường có sẵn trong ít nhất một tuần và thường lâu hơn. Tuy nhiên, khoảng thời gian mà bản ghi có sẵn có thể ngắn hơn đáng kể và đôi khi bản ghi có thể không có trong một số ít trường hợp. Nếu startHistoryId do máy khách của bạn cung cấp nằm ngoài phạm vi có sẵn của các bản ghi nhật ký, thì API sẽ trả về một phản hồi lỗi HTTP 404. Trong trường hợp này, ứng dụng khách của bạn phải thực hiện quy trình đồng bộ hoá đầy đủ như mô tả trong phần trước.
[null,null,["Cập nhật lần gần đây nhất: 2025-08-29 UTC."],[],[],null,["# Synchronizing Clients with Gmail\n\nKeeping your client synchronized with Gmail is important for most application\nscenarios. There are two overall synchronization scenarios: full synchronization\nand partial synchronization. Full synchronization is required the first time\nyour client connects to Gmail and in some other rare scenarios. If your client\nhas recently synchronized, partial synchronization is a lighter-weight\nalternative to a full sync. You can also use [push notifications](/workspace/gmail/api/guides/push)\nto trigger partial synchronization in real-time and only when necessary, thereby\navoiding needless polling.\n\nContents\n--------\n\nFull synchronization\n--------------------\n\nThe first time your application connects to Gmail, or if partial synchronization\nis not available, you must perform a full sync. In a full sync operation, your\napplication should retrieve and store as many of the most recent messages or\nthreads as are necessary for your purpose. For example, if your application\ndisplays a list of recent messages, you may wish to retrieve and cache enough\nmessages to allow for a responsive interface if the user scrolls beyond the\nfirst several messages displayed. The general procedure for performing a full\nsync operation is as follows:\n\n1. Call [`messages.list`](/workspace/gmail/api/v1/reference/users/messages/list) to retrieve the first page of message IDs.\n2. Create a [batch request](/workspace/gmail/api/guides/batch) of [`messages.get`](/workspace/gmail/api/v1/reference/users/messages/get) requests for each of the messages returned by the list request. If your application displays message contents, you should use `format=FULL` or `format=RAW` the first time your application retrieves a message and cache the results to avoid additional retrieval operations. If you are retrieving a previously cached message, you should use `format=MINIMAL` to reduce the size of the response as only the `labelIds` may change.\n3. Merge the updates into your cached results. Your application should store the `historyId` of the most recent message (the first message in the `list` response) for future partial synchronization.\n\n| **Note:** You can also perform synchronization using the equivalent [`Threads` resource](/workspace/gmail/api/v1/reference/users/threads) methods. This may be advantageous if your application primarily works with threads or only requires message metadata.\n\nPartial synchronization\n-----------------------\n\nIf your application has synchronized recently, you can perform a partial\nsync using the [`history.list`](/workspace/gmail/api/v1/reference/users/history/list)\nmethod to return all history records newer than the `startHistoryId` you specify\nin your request. History records provide message IDs and type of change for\neach message, such as message added, deleted, or labels modified since the time\nof the `startHistoryId`. You can obtain and store the `historyId` of the most\nrecent message from a full or partial sync to provide as a `startHistoryId` for\nfuture partial synchronization operations.\n\nLimitations\n-----------\n\nHistory records are typically available for at least one week and often\nlonger. However, the time period for which records are available may be\nsignificantly less and records may sometimes be unavailable in rare cases. If\nthe `startHistoryId` supplied by your client is outside the available range of\nhistory records, the API returns an `HTTP 404` error response. In this case,\nyour client must perform a full sync as described in the previous section."]]
