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