Hướng dẫn này mô tả cách triển khai tính năng "đồng bộ hoá gia tăng" dữ liệu lịch. Đang dùng , bạn có thể đồng bộ hoá dữ liệu của tất cả bộ sưu tập lịch trong khi lưu băng thông.
Nội dung
Tổng quan
Quá trình đồng bộ hoá tăng dần bao gồm 2 giai đoạn:
Lần đồng bộ hoá đầy đủ ban đầu được thực hiện một lần ngay từ đầu để đồng bộ hoá trạng thái của ứng dụng khách với trạng thái của máy chủ. Khách hàng sẽ nhận được một mã thông báo đồng bộ hoá cần duy trì.
Quá trình đồng bộ hoá gia tăng được thực hiện nhiều lần và cập nhật ứng dụng khách với tất cả các thay đổi đã xảy ra kể từ lần đồng bộ hoá trước đó. Mỗi lần, khách hàng cung cấp mã thông báo đồng bộ hoá trước đó nhận được từ máy chủ và lưu trữ mã thông báo đồng bộ hoá mới từ phản hồi.
Đồng bộ hoá toàn bộ lần đầu
Lần đồng bộ hoá đầy đủ ban đầu là yêu cầu ban đầu cho tất cả tài nguyên của bộ sưu tập bạn muốn đồng bộ hoá. Bạn có thể tuỳ ý giới hạn danh sách này bằng cách sử dụng các tham số yêu cầu nếu bạn chỉ muốn đồng bộ hoá một tập hợp con tài nguyên.
Trong phản hồi cho thao tác danh sách, bạn sẽ thấy một trường có tên
nextSyncToken đại diện cho mã thông báo đồng bộ hoá. Bạn cần lưu trữ giá trị của
nextSyncToken. Nếu tập hợp kết quả quá lớn và phản hồi nhận được
Paging, rồi đến nextSyncToken
chỉ xuất hiện trên trang cuối cùng.
Đồng bộ hoá dần dần
Quá trình đồng bộ hoá gia tăng cho phép bạn truy xuất tất cả tài nguyên đã
được sửa đổi kể từ lần yêu cầu đồng bộ hoá gần nhất. Để thực hiện điều này, bạn cần thực hiện một danh sách
yêu cầu bằng mã thông báo đồng bộ hoá gần đây nhất được chỉ định trong trường syncToken.
Hãy lưu ý rằng kết quả sẽ luôn chứa các mục đã bị xoá, để
khách hàng có thể xoá chúng khỏi bộ nhớ.
Trong trường hợp một số lượng lớn tài nguyên đã thay đổi kể từ lần kết thúc
yêu cầu đồng bộ hoá tăng dần, bạn có thể thấy pageToken thay vì syncToken trong kết quả danh sách. Trong những trường hợp này, bạn cần thực hiện giống hệt nhau
danh sách truy vấn như đã được sử dụng để truy xuất trang đầu tiên trong quá trình đồng bộ hoá gia tăng
(với cùng một syncToken), hãy thêm pageToken vào đó và
phân trang qua tất cả các yêu cầu sau cho đến khi bạn tìm thấy một syncToken khác trên trang cuối cùng. Hãy nhớ lưu trữ syncToken này cho lần đồng bộ hoá tiếp theo
yêu cầu trong tương lai.
Dưới đây là các truy vấn mẫu cho một trường hợp cần đồng bộ hoá phân trang gia tăng:
Truy vấn ban đầu
GET /calendars/primary/events?maxResults=10&singleEvents=true&syncToken=CPDAlvWDx70CEPDAlvWDx
// Result contains the following
"nextPageToken":"CiAKGjBpNDd2Nmp2Zml2cXRwYjBpOXA",
Truy xuất trang tiếp theo
GET /calendars/primary/events?maxResults=10&singleEvents=true&syncToken=CPDAlvWDx70CEPDAlvWDx&pageToken=CiAKGjBpNDd2Nmp2Zml2cXRwYjBpOXA
Máy chủ yêu cầu đồng bộ hóa toàn bộ
Đôi khi, mã thông báo đồng bộ hoá bị máy chủ vô hiệu hoá vì nhiều lý do
bao gồm hết hạn mã thông báo hoặc các thay đổi trong các ACL có liên quan.
Trong những trường hợp như vậy, máy chủ sẽ phản hồi yêu cầu gia tăng kèm theo
mã phản hồi 410. Thao tác này sẽ kích hoạt quá trình xoá sạch toàn bộ cửa hàng của khách hàng
và một phiên đồng bộ hoá hoàn toàn mới.
Mã mẫu
Đoạn mã mẫu dưới đây minh hoạ cách sử dụng mã thông báo đồng bộ hoá với Thư viện ứng dụng Java. Lần đầu tiên phương thức chạy được gọi sẽ thực hiện đồng bộ hoá toàn bộ và lưu trữ mã thông báo đồng bộ hoá. Trong mỗi lần thực thi tiếp theo, Chrome sẽ tải mã thông báo đồng bộ hoá đã lưu và thực hiện đồng bộ hoá dần dần.
private static void run() throws IOException {
// Construct the {@link Calendar.Events.List} request, but don't execute it yet.
Calendar.Events.List request = client.events().list("primary");
// Load the sync token stored from the last execution, if any.
String syncToken = syncSettingsDataStore.get(SYNC_TOKEN_KEY);
if (syncToken == null) {
System.out.println("Performing full sync.");
// Set the filters you want to use during the full sync. Sync tokens aren't compatible with
// most filters, but you may want to limit your full sync to only a certain date range.
// In this example we are only syncing events up to a year old.
Date oneYearAgo = Utils.getRelativeDate(java.util.Calendar.YEAR, -1);
request.setTimeMin(new DateTime(oneYearAgo, TimeZone.getTimeZone("UTC")));
} else {
System.out.println("Performing incremental sync.");
request.setSyncToken(syncToken);
}
// Retrieve the events, one page at a time.
String pageToken = null;
Events events = null;
do {
request.setPageToken(pageToken);
try {
events = request.execute();
} catch (GoogleJsonResponseException e) {
if (e.getStatusCode() == 410) {
// A 410 status code, "Gone", indicates that the sync token is invalid.
System.out.println("Invalid sync token, clearing event store and re-syncing.");
syncSettingsDataStore.delete(SYNC_TOKEN_KEY);
eventDataStore.clear();
run();
} else {
throw e;
}
}
List<Event> items = events.getItems();
if (items.size() == 0) {
System.out.println("No new events to sync.");
} else {
for (Event event : items) {
syncEvent(event);
}
}
pageToken = events.getNextPageToken();
} while (pageToken != null);
// Store the sync token from the last request to be used during the next execution.
syncSettingsDataStore.set(SYNC_TOKEN_KEY, events.getNextSyncToken());
System.out.println("Sync complete.");
}
Đồng bộ hoá cũ
Đối với bộ sưu tập sự kiện, bạn vẫn có thể đồng bộ hoá trong
theo cách cũ bằng cách giữ lại giá trị của trường đã cập nhật từ danh sách sự kiện
yêu cầu, rồi sử dụng trường modifiedSince để truy xuất các sự kiện đã cập nhật.
Phương pháp này không được đề xuất nữa vì phương pháp này dễ gặp lỗi hơn do
cho các bản cập nhật bị bỏ lỡ (chẳng hạn như nếu không thực thi các hạn chế truy vấn).
Hơn nữa, tính năng này chỉ dành cho các sự kiện.