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

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

مطالب

نمای کلی

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

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

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

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

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

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

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

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

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

در اینجا پرس و جوهای نمونه برای موردی وجود دارد که نیاز به همگام سازی صفحه بندی شده افزایشی دارد:

پرس و جو اصلی

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

// Result contains the following

"nextPageToken":"CiAKGjBpNDd2Nmp2Zml2cXRwYjBpOXA",

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

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

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

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

کد نمونه

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

  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

همگام سازی میراث

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