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

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

المحتويات

نظرة عامة

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

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

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

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

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

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

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

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

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

يطلب الخادم إجراء مزامنة كاملة

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