مزامنة العملاء مع 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. في هذه الحالة، على العميل إجراء مزامنة كاملة كما هو موضّح في القسم السابق.