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

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

المحتويات

نظرة عامة

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

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