Menyinkronkan resource secara efisien

Panduan ini menjelaskan cara menerapkan "sinkronisasi inkremental" data kalender. Dengan menggunakan metode ini, Anda dapat menyinkronkan data untuk semua koleksi kalender sekaligus menghemat bandwidth.

Daftar Isi

Ringkasan

Sinkronisasi inkremental terdiri dari dua tahap:

1. Sinkronisasi penuh awal dilakukan satu kali di awal untuk sepenuhnya menyinkronkan status klien dengan status server. Klien akan mendapatkan token sinkronisasi yang perlu dipertahankan.

2. Sinkronisasi inkremental dilakukan berulang kali dan memperbarui klien dengan semua perubahan yang terjadi sejak sinkronisasi sebelumnya. Setiap kali, klien memberikan token sinkronisasi sebelumnya yang diperoleh dari server dan menyimpan token sinkronisasi baru dari respons.

Token sinkronisasi adalah bagian data yang dipertukarkan antara server dan klien, dan memiliki peran penting dalam proses sinkronisasi. Contohnya akan terlihat seperti berikut:

"nextSyncToken": "CPDAlvWDx70CEPDAlvWDx70CGAU=",

Sinkronisasi penuh awal

Sinkronisasi penuh awal adalah permintaan asli untuk semua resource kumpulan yang ingin Anda sinkronkan. Secara opsional, Anda dapat membatasi permintaan daftar menggunakan parameter permintaan jika hanya ingin menyinkronkan subkumpulan resource tertentu.

Dalam respons terhadap operasi daftar, Anda akan menemukan kolom yang disebut nextSyncToken yang mewakili token sinkronisasi. Anda harus menyimpan nilai nextSyncToken. Jika kumpulan hasil terlalu besar dan respons di-pagination, kolom nextSyncToken hanya ada di halaman terakhir.

Anda tidak perlu khawatir tentang entri baru yang muncul saat membuat penomoran halaman — entri tersebut tidak akan terlewat. Informasi yang diperlukan agar server dapat membuat token sinkronisasi yang benar dienkode dalam token halaman.

Sinkronisasi inkremental

Sinkronisasi inkremental memungkinkan Anda mengambil semua resource yang telah diubah sejak permintaan sinkronisasi terakhir. Untuk melakukannya, Anda perlu melakukan permintaan daftar dengan token sinkronisasi terbaru yang ditentukan di kolom syncToken. Perlu diingat bahwa hasilnya akan selalu berisi entri yang dihapus, sehingga klien mendapatkan kesempatan untuk menghapusnya dari penyimpanan.

Jika sejumlah besar resource telah berubah sejak permintaan sinkronisasi inkremental terakhir, Anda mungkin menemukan pageToken, bukan syncToken, dalam hasil daftar. Dalam hal ini, Anda harus melakukan kueri daftar yang sama persis seperti yang digunakan untuk pengambilan halaman pertama dalam sinkronisasi inkremental (dengan syncToken yang sama persis), tambahkan pageToken ke dalamnya dan buat penomoran halaman untuk semua permintaan berikut hingga Anda menemukan syncToken lain di halaman terakhir. Pastikan untuk menyimpan syncToken ini untuk permintaan sinkronisasi berikutnya di masa mendatang.

Berikut adalah contoh kueri untuk kasus yang memerlukan sinkronisasi dengan penomoran halaman inkremental:

Kueri asli

GET /calendars/primary/events?maxResults=10&singleEvents=true&syncToken=CPDAlvWDx70CEPDAlvWDx

// Result contains the following

"nextPageToken":"CiAKGjBpNDd2Nmp2Zml2cXRwYjBpOXA",

Mengambil halaman berikutnya

GET /calendars/primary/events?maxResults=10&singleEvents=true&syncToken=CPDAlvWDx70CEPDAlvWDx&pageToken=CiAKGjBpNDd2Nmp2Zml2cXRwYjBpOXA

Kumpulan parameter kueri yang dapat digunakan pada sinkronisasi inkremental dibatasi. Setiap permintaan daftar harus menggunakan kumpulan parameter kueri yang sama, termasuk permintaan awal. Untuk setiap batasan pada setiap koleksi, lihat dokumentasi yang sesuai untuk permintaan daftar. Kode respons untuk kueri daftar yang berisi batasan yang tidak diizinkan adalah 400.

Sinkronisasi penuh diperlukan oleh server

Terkadang token sinkronisasi dibatalkan validasinya oleh server, karena berbagai alasan, termasuk masa berlaku token atau perubahan pada ACL terkait. Dalam kasus tersebut, server akan merespons permintaan inkremental dengan kode respons 410. Tindakan ini akan memicu penghapusan total penyimpanan klien dan sinkronisasi penuh baru.

Kode contoh

Cuplikan kode contoh di bawah menunjukkan cara menggunakan token sinkronisasi dengan library klien Java. Saat pertama kali metode run dipanggil, metode ini akan melakukan sinkronisasi penuh dan menyimpan token sinkronisasi. Pada setiap eksekusi berikutnya, token sinkronisasi yang disimpan akan dimuat dan sinkronisasi inkremental akan dilakukan.

  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

Sinkronisasi lama

Untuk koleksi peristiwa, Anda masih dapat melakukan sinkronisasi dengan cara lama dengan mempertahankan nilai kolom yang diperbarui dari permintaan daftar peristiwa, lalu menggunakan kolom modifiedSince untuk mengambil peristiwa yang diperbarui. Pendekatan ini tidak lagi direkomendasikan karena lebih rentan terhadap error terkait update yang terlewat (misalnya jika tidak menerapkan batasan kueri). Selain itu, fitur ini hanya tersedia untuk peristiwa.