يعد الحفاظ على مزامنة البرنامج مع Gmail أمرًا في غاية الأهمية بالنسبة إلى معظم سيناريوهات التطبيقات. هناك سيناريوهان عامان للمزامنة: المزامنة الكاملة والمزامنة الجزئية. تكون المزامنة الكاملة مطلوبة في المرة الأولى التي يتصل فيها عميلك بـ Gmail، وفي بعض السيناريوهات النادرة الأخرى. إذا تمت مزامنة البرنامج مؤخرًا، فإن المزامنة الجزئية هي بديل أقل أهمية للمزامنة الكاملة. يمكنك أيضًا استخدام الإشعارات الفورية لتشغيل المزامنة الجزئية في الوقت الفعلي وعند الضرورة فقط، ما يؤدي إلى تجنُّب الاستطلاعات غير الضرورية.
الفهرس
المزامنة الكاملة
عند اتصال تطبيقك بـ Gmail لأول مرة، أو إذا كانت المزامنة الجزئية غير متاحة، يجب إجراء مزامنة كاملة. وفي عملية المزامنة الكاملة، يجب أن يسترد تطبيقك ويخزّن أكبر عدد ممكن من الرسائل أو سلاسل المحادثات حسب الضرورة لغرضك. على سبيل المثال، إذا كان التطبيق يعرض قائمة بالرسائل الأخيرة، قد ترغب في استرداد عدد كافٍ من الرسائل وتخزينها مؤقتًا للسماح بواجهة سريعة الاستجابة إذا انتقل المستخدم إلى ما بعد أول عدة رسائل معروضة. إليك الإجراءات العامة لتنفيذ عملية مزامنة كاملة:
- استدعِ الرقم
messages.list
لاسترداد الصفحة الأولى من معرّفات الرسائل. - أنشِئ طلبًا مجمّعًا من طلبات
messages.get
لكل رسالة من الرسائل التي يعرضها طلب القائمة. إذا كان تطبيقك يعرض محتوى الرسائل، يجب استخدامformat=FULL
أوformat=RAW
في المرة الأولى التي يسترد فيها التطبيق رسالة ويخزِّن النتائج مؤقتًا لتجنب أي عمليات إضافية لاسترداد البيانات. إذا كنت تسترجع رسالة مخزّنة مؤقتًا في السابق، عليك استخدامformat=MINIMAL
لتقليل حجم الرد، لأنّlabelIds
فقط قد يتغيّر. - ادمج التحديثات في النتائج المخزّنة مؤقتًا. يجب أن يخزّن تطبيقك
historyId
لأحدث رسالة (الرسالة الأولى في استجابةlist
) لإجراء مزامنة جزئية في المستقبل.
مزامنة جزئية
إذا تمت مزامنة تطبيقك مؤخرًا، يمكنك إجراء عملية مزامنة جزئية باستخدام الطريقة history.list
لعرض جميع سجلات السجلّ الأحدث من startHistoryId
الذي حددته في طلبك. توفر سجلات السجلّ أرقام تعريف الرسائل ونوع التغيير لكل رسالة،
مثل الرسائل التي تمت إضافتها أو حذفها أو التصنيفات التي تم تعديلها منذ وقت
startHistoryId
. يمكنك الحصول على historyId
لأحدث رسالة من عملية مزامنة كاملة أو جزئية وتخزينها على هيئة startHistoryId
لعمليات المزامنة الجزئية المستقبلية.
القيود
تكون سجلات السجل متاحة عادةً لمدة أسبوع واحد على الأقل
وأكثر من ذلك في كثير من الأحيان. ومع ذلك، قد تكون الفترة الزمنية التي تتوفر فيها السجلات
أقل بشكل ملحوظ، وقد لا تكون السجلات متاحة أحيانًا في حالات نادرة. إذا كانت واجهة برمجة التطبيقات startHistoryId
التي يوفّرها العميل خارج النطاق المتاح لسجلّات السجلّ، تعرض واجهة برمجة التطبيقات استجابة الخطأ HTTP 404
. في هذه الحالة،
يجب أن يُجري البرنامج مزامنة كاملة كما هو موضّح في القسم السابق.