مزامنة العملاء مع Gmail

يعد الحفاظ على مزامنة البرنامج مع Gmail أمرًا في غاية الأهمية بالنسبة إلى معظم سيناريوهات التطبيقات. هناك سيناريوهان عامان للمزامنة: المزامنة الكاملة والمزامنة الجزئية. تكون المزامنة الكاملة مطلوبة في المرة الأولى التي يتصل فيها عميلك بـ Gmail، وفي بعض السيناريوهات النادرة الأخرى. إذا تمت مزامنة البرنامج مؤخرًا، فإن المزامنة الجزئية هي بديل أقل أهمية للمزامنة الكاملة. يمكنك أيضًا استخدام الإشعارات الفورية لتشغيل المزامنة الجزئية في الوقت الفعلي وعند الضرورة فقط، ما يؤدي إلى تجنُّب الاستطلاعات غير الضرورية.

الفهرس

المزامنة الكاملة

عند اتصال تطبيقك بـ Gmail لأول مرة، أو إذا كانت المزامنة الجزئية غير متاحة، يجب إجراء مزامنة كاملة. وفي عملية المزامنة الكاملة، يجب أن يسترد تطبيقك ويخزّن أكبر عدد ممكن من الرسائل أو سلاسل المحادثات حسب الضرورة لغرضك. على سبيل المثال، إذا كان التطبيق يعرض قائمة بالرسائل الأخيرة، قد ترغب في استرداد عدد كافٍ من الرسائل وتخزينها مؤقتًا للسماح بواجهة سريعة الاستجابة إذا انتقل المستخدم إلى ما بعد أول عدة رسائل معروضة. إليك الإجراءات العامة لتنفيذ عملية مزامنة كاملة:

  1. استدعِ الرقم messages.list لاسترداد الصفحة الأولى من معرّفات الرسائل.
  2. أنشِئ طلبًا مجمّعًا من طلبات messages.get لكل رسالة من الرسائل التي يعرضها طلب القائمة. إذا كان تطبيقك يعرض محتوى الرسائل، يجب استخدام format=FULL أو format=RAW في المرة الأولى التي يسترد فيها التطبيق رسالة ويخزِّن النتائج مؤقتًا لتجنب أي عمليات إضافية لاسترداد البيانات. إذا كنت تسترجع رسالة مخزّنة مؤقتًا في السابق، عليك استخدام format=MINIMAL لتقليل حجم الرد، لأنّ labelIds فقط قد يتغيّر.
  3. ادمج التحديثات في النتائج المخزّنة مؤقتًا. يجب أن يخزّن تطبيقك historyId لأحدث رسالة (الرسالة الأولى في استجابة list) لإجراء مزامنة جزئية في المستقبل.

مزامنة جزئية

إذا تمت مزامنة تطبيقك مؤخرًا، يمكنك إجراء عملية مزامنة جزئية باستخدام الطريقة history.list لعرض جميع سجلات السجلّ الأحدث من startHistoryId الذي حددته في طلبك. توفر سجلات السجلّ أرقام تعريف الرسائل ونوع التغيير لكل رسالة، مثل الرسائل التي تمت إضافتها أو حذفها أو التصنيفات التي تم تعديلها منذ وقت startHistoryId. يمكنك الحصول على historyId لأحدث رسالة من عملية مزامنة كاملة أو جزئية وتخزينها على هيئة startHistoryId لعمليات المزامنة الجزئية المستقبلية.

القيود

تكون سجلات السجل متاحة عادةً لمدة أسبوع واحد على الأقل وأكثر من ذلك في كثير من الأحيان. ومع ذلك، قد تكون الفترة الزمنية التي تتوفر فيها السجلات أقل بشكل ملحوظ، وقد لا تكون السجلات متاحة أحيانًا في حالات نادرة. إذا كانت واجهة برمجة التطبيقات startHistoryId التي يوفّرها العميل خارج النطاق المتاح لسجلّات السجلّ، تعرض واجهة برمجة التطبيقات استجابة الخطأ HTTP 404. في هذه الحالة، يجب أن يُجري البرنامج مزامنة كاملة كما هو موضّح في القسم السابق.