مزامنة البرامج مع Gmail

يوضّح هذا المستند كيفية مزامنة العملاء باستخدام Gmail API.

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

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

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

اتّبِع الخطوات التالية لإجراء مزامنة كاملة:

  1. استدعِ طريقة messages.list لاسترداد الصفحة الأولى من أرقام تعريف الرسائل.

  2. أنشئ طلبًا مجمّعًا من طلبات طريقة messages.get لكل رسالة من الرسائل التي تم عرضها في طلب القائمة.

    إذا كان تطبيقك يعرض محتوى الرسائل، عليك ضبط Format على format=FULL أو format=RAW في المرة الأولى التي يسترد فيها تطبيقك رسالة، ثم تخزين النتائج مؤقتًا لتجنُّب عمليات الاسترداد الإضافية. إذا كنت تسترجع رسالة تم تخزينها مؤقتًا من قبل، عليك استخدام format=MINIMAL لتقليل حجم الردّ لأنّ labelIds هو الجزء الوحيد الذي قد يتغيّر.

  3. ادمج التعديلات في النتائج المخزّنة مؤقتًا. يجب أن يخزّن تطبيقك historyId لأحدث رسالة (الرسالة الأولى في استجابة list) من أجل عمليات المزامنة الجزئية المستقبلية.

المزامنة الجزئية

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

يجب ضبط مَعلمة طلب البحث startHistoryId على historyId لرسالة حديثة. لاسترداد historyId رسالة حديثة، استخدِم الطريقتَين messages.get أو messages.list. يمكنك أيضًا ضبط القيمة أثناء المزامنة الكاملة أو الجزئية لاستخدامها في المستقبل.

يتضمّن عنصر History الذي تم عرضه أرقام تعريف الرسائل ونوع التغيير لكل رسالة، مثل إضافة رسالة أو تعديل التصنيفات، منذ وقت startHistoryId المحدّد.

القيود

تتوفّر سجلّات السجلّ عادةً لمدة أسبوع واحد على الأقل، وغالبًا ما تكون متاحة لفترة أطول. ومع ذلك، قد تكون الفترة الزمنية التي تتوفّر فيها السجلات أقل بكثير، وقد لا تتوفّر السجلات أحيانًا في حالات نادرة.

إذا كان startHistoryId الذي يقدّمه العميل خارج النطاق المتاح لسجلات السجلّ، ستعرض Gmail API ردًّا يتضمّن الخطأ HTTP 404. في هذه الحالة، على العميل إجراء مزامنة كاملة.