همگام‌سازی کارآمد منابع

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

محتوا

نمای کلی

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

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

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

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

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

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

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

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

در مواردی که تعداد زیادی از منابع از آخرین درخواست همگام‌سازی افزایشی تغییر کرده‌اند، ممکن است به‌جای syncToken، pageToken را در نتیجه فهرست پیدا کنید. در این موارد باید دقیقاً همان پُرسمان فهرستی را که برای بازیابی صفحه اول در همگام‌سازی افزایشی استفاده شده بود (با دقیقاً همان 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 پاسخ خواهد داد. این کار باید باعث پاک‌سازی کامل فروشگاه کارخواه و همگام‌سازی کامل جدید شود.

کدگذاری نمونه

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

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

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

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