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

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

المحتويات

نظرة عامة

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

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

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

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

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

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

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

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