همگام سازی منابع به طور موثر

این راهنما نحوه‌ی پیاده‌سازی همگام‌سازی افزایشی داده‌های تقویم را شرح می‌دهد. با استفاده از این روش، می‌توانید داده‌های تمام مجموعه‌های تقویم را همگام‌سازی کنید و در عین حال در پهنای باند صرفه‌جویی کنید.

فهرست مطالب

نمای کلی

همگام‌سازی افزایشی شامل دو مرحله است:

  1. همگام‌سازی کامل اولیه : یک بار در ابتدا برای همگام‌سازی کامل وضعیت کلاینت با وضعیت سرور انجام می‌شود. کلاینت یک توکن همگام‌سازی دریافت می‌کند که باید آن را حفظ کند.

  2. همگام‌سازی افزایشی : به طور مکرر انجام می‌شود تا کلاینت را با تمام تغییرات ایجاد شده از زمان همگام‌سازی قبلی به‌روزرسانی کند. هر بار، کلاینت توکن همگام‌سازی قبلی را که از سرور دریافت کرده است، ارائه می‌دهد و توکن همگام‌سازی جدید را از پاسخ ذخیره می‌کند.

همگام‌سازی کامل اولیه

همگام‌سازی کامل اولیه، درخواست اصلی برای تمام منابع مجموعه‌ای است که می‌خواهید همگام‌سازی کنید. اگر فقط می‌خواهید زیرمجموعه خاصی از منابع را همگام‌سازی کنید، می‌توانید درخواست لیست را با استفاده از پارامترهای درخواست محدود کنید.

در پاسخ به عملیات لیست، پاسخ شامل فیلدی به نام nextSyncToken است که نشان دهنده یک توکن همگام‌سازی است. شما باید مقدار nextSyncToken را ذخیره کنید. اگر مجموعه نتایج خیلی بزرگ باشد و پاسخ صفحه‌بندی شده باشد، فیلد nextSyncToken فقط در صفحه آخر وجود دارد.

همگام‌سازی افزایشی

همگام‌سازی افزایشی به شما امکان می‌دهد تمام منابعی را که از آخرین درخواست همگام‌سازی تغییر یافته‌اند، بازیابی کنید. برای انجام این کار، یک درخواست فهرست با جدیدترین توکن همگام‌سازی خود که در فیلد syncToken مشخص شده است، انجام دهید. به خاطر داشته باشید که نتیجه همیشه شامل ورودی‌های حذف شده است، بنابراین کلاینت‌ها می‌توانند آنها را از حافظه حذف کنند.

در مواردی که تعداد زیادی از منابع از زمان آخرین درخواست همگام‌سازی افزایشی تغییر کرده‌اند، ممکن است به جای syncToken در لیست نتایج، یک pageToken پیدا کنید. در این موارد، همان کوئری لیست مورد استفاده برای بازیابی صفحه اول در همگام‌سازی افزایشی (با همان syncToken ) را اجرا کنید، pageToken به آن اضافه کنید و درخواست‌های بعدی را صفحه‌بندی کنید تا syncToken دیگری را در صفحه آخر پیدا کنید. این syncToken برای درخواست همگام‌سازی بعدی ذخیره کنید.

مثال‌های زیر یک همگام‌سازی صفحه‌بندی‌شده‌ی افزایشی را نشان می‌دهند:

پرس و جوی اصلی

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

نتیجه شامل موارد زیر است:

{
  "nextPageToken": "CiAKGjBpNDd2Nmp2Zml2cXRwYjBpOXA"
}

بازیابی صفحه بعدی

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

همگام‌سازی کامل مورد نیاز توسط سرور

سرور گاهی اوقات به دلیل انقضای توکن یا تغییر در ACL های مرتبط، توکن‌های همگام‌سازی را نامعتبر می‌کند. در چنین مواردی، سرور به یک درخواست افزایشی با کد وضعیت HTTP 410 پاسخ می‌دهد. در این صورت، حافظه کلاینت را پاک کرده و یک همگام‌سازی کامل جدید انجام دهید.

کد نمونه

نمونه زیر نحوه استفاده از توکن‌های همگام‌سازی (sync tokens) را با کتابخانه کلاینت جاوا نشان می‌دهد. اولین باری که متد run() فراخوانی می‌شود، یک همگام‌سازی کامل انجام می‌دهد و توکن همگام‌سازی را ذخیره می‌کند. در هر اجرای بعدی، توکن همگام‌سازی ذخیره شده را بارگذاری می‌کند و یک همگام‌سازی افزایشی انجام می‌دهد.

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

همگام‌سازی قدیمی

برای مجموعه‌های رویداد، می‌توانید با ذخیره مقدار فیلد updated از یک درخواست فهرست رویدادها و سپس استفاده از فیلد updatedMin برای بازیابی رویدادهای به‌روزرسانی‌شده، همگام‌سازی قدیمی را انجام دهید. این رویکرد دیگر توصیه نمی‌شود زیرا مستعد خطا است (برای مثال، محدودیت‌های پرس‌وجو را اعمال نمی‌کند) و فقط برای رویدادها در دسترس است.