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

يوضّح هذا الدليل كيفية تنفيذ المزامنة التزايدية لبيانات التقويم. باستخدام هذه الطريقة، يمكنك إبقاء بيانات جميع مجموعات التقويم متزامنة مع توفير معدل نقل البيانات.

المحتويات

نظرة عامة

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

  1. المزامنة الكاملة الأولية: يتم تنفيذها مرة واحدة في البداية لمزامنة حالة العميل مع حالة الخادم بشكل كامل. يحصل العميل على رمز مميّز للمزامنة يجب أن يحتفظ به.

  2. المزامنة التزايدية: يتم تنفيذها بشكل متكرّر لتعديل بيانات العميل وفقًا لجميع التغييرات التي تم إجراؤها منذ المزامنة السابقة. في كل مرة، يقدّم العميل الرمز المميّز السابق للمزامنة الذي تم الحصول عليه من الخادم ويخزّن الرمز المميّز الجديد للمزامنة من الرد.

المزامنة الكاملة الأولية

المزامنة الكاملة الأولية هي الطلب الأصلي لجميع موارد المجموعة التي تريد مزامنتها. يمكنك اختياريًا حصر طلب القائمة باستخدام مَعلمات الطلب إذا كنت تريد مزامنة مجموعة فرعية معيّنة فقط من الموارد.

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

المزامنة التدريجية

تتيح لك المزامنة التفاضلية استرداد جميع الموارد التي تم تعديلها منذ آخر طلب مزامنة. لإجراء ذلك، أرسِل طلب قائمة مع تضمين رمز المزامنة الأخير في الحقل syncToken. يُرجى العِلم أنّ النتيجة تحتوي دائمًا على إدخالات محذوفة، لذا يمكن للعملاء إزالتها من مساحة التخزين.

في الحالات التي تم فيها تغيير عدد كبير من الموارد منذ آخر طلب مزامنة تدريجية، قد يظهر لك الرمز pageToken بدلاً من syncToken في نتيجة القائمة. في هذه الحالات، نفِّذ طلب البحث الخاص بالقائمة نفسه الذي تم استخدامه لاسترداد الصفحة الأولى في المزامنة التزايدية (باستخدام 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

مزامنة كاملة مطلوبة من الخادم

في بعض الأحيان، يبطل الخادم رموز المزامنة بسبب انتهاء صلاحية الرمز أو حدوث تغييرات في قوائم التحكّم بالوصول ذات الصلة. في هذه الحالات، يستجيب الخادم لطلب إضافي برمز حالة HTTP 410. في هذه الحالة، امحُ مساحة تخزين العميل وأجرِ مزامنة كاملة جديدة.

نموذج الرموز البرمجية

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