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