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

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

المحتويات

نظرة عامة

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

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

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

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