مزامنة الموارد بكفاءة

يصف هذا الدليل كيفية تنفيذ "المزامنة التزايدية" لبيانات التقويم. وباستخدام هذه الطريقة، يمكنك الاحتفاظ ببيانات جميع مجموعات التقويم متزامنة مع توفير معدل نقل البيانات.

الفهرس

نظرة عامة

تتألف المزامنة التدريجية من مرحلتين:

  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. من المفترض أن يؤدي ذلك إلى مسح متجر العميل بالكامل ومزامنة كاملة جديدة.

نموذج التعليمات البرمجية

يوضح مقتطف الرمز النموذجي أدناه كيفية استخدام الرموز المميزة للمزامنة مع مكتبة عميل 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 لاسترداد الأحداث المعدَّلة. لم يعُد من المستحسن اتّباع هذا الأسلوب لأنّه أكثر عرضة للأخطاء في ما يتعلّق بالتحديثات الفائتة (على سبيل المثال، في حال عدم فرض قيود على طلبات البحث). بالإضافة إلى ذلك، يتوفر هذا الخيار للأحداث فقط.