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

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

المحتويات

نظرة عامة

تتكون المزامنة التزايدية من مرحلتين:

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

المزامنة القديمة

بالنسبة إلى مجموعات الأحداث، يظل من الممكن إجراء المزامنة على الطريقة القديمة من خلال الاحتفاظ بقيمة الحقل الذي تم تعديله من طلب قائمة الأحداث، ثم استخدام الحقل modifiedSince لاسترداد الأحداث التي تم تعديلها. لم يعُد ننصح باستخدام هذا الأسلوب لأنّه أكثر عرضة للأخطاء في ما يتعلق بالتحديثات الفائتة (على سبيل المثال، إذا لم يتم فرض قيود على طلبات البحث). علاوةً على ذلك، فهو متاح للفعاليات فقط.