Đồng bộ hoá tài nguyên một cách hiệu quả

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. Khi sử dụng phương thức này, bạn có thể đồng bộ hoá dữ liệu của tất cả các bộ sưu tập lịch, đồng thời tiết kiệm 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:

1. Quá trình đồng bộ hoá toàn bộ ban đầu được thực hiện một lần ngay từ đầu để đồng bộ hoá hoàn toàn trạng thái của ứng dụng với trạng thái của máy chủ. Máy khách sẽ nhận được mã thông báo đồng bộ hoá cần thiết.

2. Quá trình đồng bộ hoá gia tăng được thực hiện nhiều lần và cập nhật cho ứng dụng tất cả thay đổi đã diễn ra kể từ lần đồng bộ hoá trước đó. Mỗi lần, ứng dụng sẽ 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 mà bạn muốn đồng bộ hoá. Bạn có thể tuỳ ý hạn chế yêu cầu danh sách bằng cách sử dụng các tham số yêu cầu nếu chỉ muốn đồng bộ hoá một tập hợp con tài nguyên cụ thể.

Trong phản hồi cho thao tác danh sách, bạn sẽ thấy một trường có tên là 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 được phân trang, thì trường nextSyncToken chỉ xuất hiện trên trang cuối cùng.

Đồng bộ hoá dần dần

Tính năng đồ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ừ yêu cầu đồng bộ hoá gần đây nhất. Để thực hiện việc này, bạn cần thực hiện yêu cầu danh sách 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 đã xoá để các ứng dụng có cơ hội xoá các mục đó khỏi bộ nhớ.

Trong trường hợp một số lượng lớn tài nguyên đã thay đổi kể từ yêu cầu đồng bộ hoá gia tăng gần đây nhất, 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 cùng một truy vấn danh sách như đã dùng để truy xuất trang đầu tiên trong quá trình đồng bộ hoá tăng dần (với cùng một syncToken), hãy thêm pageToken vào trang đó và phân trang thông 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 yêu cầu đồng bộ hoá tiếp theo sau này.

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 cả việc hết hạn mã thông báo hoặc các thay đổi trong các ACL liên quan. Trong những trường hợp như vậy, máy chủ sẽ phản hồi một yêu cầu gia tăng bằng một 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 ứng dụng và một lượt đồ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. Khi gọi phương thức chạy lần đầu tiên, phương thức này sẽ đồ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, ứng dụng sẽ tải mã thông báo đồng bộ hoá đã lưu và thực hiện quá trình đồng bộ hoá gia tăng.

  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.");
  }
SyncTokenSample.java

Đồng bộ hoá cũ

Đối với các bộ sưu tập sự kiện, bạn vẫn có thể đồng bộ hoá theo cách cũ bằng cách giữ lại giá trị của trường đã cập nhật từ yêu cầu danh sách sự kiện, sau đó sử dụng trường modifiedSince để truy xuất các sự kiện đã cập nhật. Bạn không nên dùng phương pháp này nữa vì phương pháp này dễ gặp lỗi hơn do các bản cập nhật bị bỏ lỡ (ví dụ: nếu không thực thi các quy tắc hạn chế đối với truy vấn). Hơn nữa, tính năng này chỉ dành cho các sự kiện.